Guias

SIP

Quando o agente de voz e o simples reencaminhamento não chegam e pretende ligar um número ao seu próprio softphone ou sistema telefónico (PBX), precisa de um fornecedor de trunk SIP - a volai é um deles. Esta página é um guia passo a passo.

1Chamadas recebidas para o seu servidor SIP

Defina o encaminhamento do número para mode: "sip" e indique o seu sipUri - a partir daí a chamada vai diretamente para si, e não para o nosso agente nem para o reencaminhamento:

curl -X PATCH "https://volai.eu/v1/numbers/+420601234567" \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"routing": {"mode": "sip", "sipUri": "sip:rececao@o-seu-servidor.com"}}'

Só o minuto recebido é cobrado - 0,50 kr/min (≈ 0,02 EUR), sem agente adicional - a estrutura completa do pedido e os outros modos de encaminhamento estão na referência da API REST.

Autenticação na sua central

Primeiro enviamos a chamada para o seu servidor SIP como um INVITE sem autenticação para sipUri. Uma central que lhe responde com um pedido de autenticação (401/407) e recusa a chamada sem mais nunca a recebe nesta forma - não há ninguém que responda ao pedido. Por isso acrescente ao encaminhamento também sipUsername e sipPassword - preenchendo ambos, a nossa rede responde ao pedido (SIP digest) e marca o número chamado. Verificado com uma chamada real para o número SIP nativo da Vapi, que aceita credenciais independentemente do conteúdo. Se a sua própria central também estabelece a chamada, depende dela - tem de responder efetivamente ao INVITE com um pedido de autenticação e aceitar o nome de utilizador e a palavra-passe que indicar; não o garantimos para todas as centrais (nos testes falhou, por exemplo, com o domínio SIP da Twilio). Sem sipUsername e sipPassword, o encaminhamento mantém a forma atual, sem autenticação. As credenciais acrescentam-se assim:

curl -X PATCH "https://volai.eu/v1/numbers/+420601234567" \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"routing": {"mode": "sip", "sipUri": "sip:rececao@o-seu-servidor.com", "sipUsername": "rececao", "sipPassword": "supersecret123"}}'

Enviamos sempre o número chamado exatamente como aparece em sipUri antes do sinal @ - nunca acrescentamos nem retiramos um prefixo ou um zero inicial, pelo que a central de destino tem de tratar exatamente o que ali indicar.

Nem sipUsername nem sipPassword podem conter dois pontos, sinal @, espaços, aspas ou barra invertida, e cada um pode ter no máximo 64 caracteres.

Preencher apenas um dos dois é rejeitado - a API devolve "Please fill in both username and password, or leave both empty."

Dois pontos na parte do utilizador de sipUri (antes do sinal @) e uma porta no anfitrião (depois dos dois pontos a seguir ao servidor, por exemplo :5060) ainda não são suportados em conjunto com sipUsername e sipPassword - ambos devolvem o mesmo erro rígido. Sem credenciais, ambos continuam a funcionar sem alteração.

Exceção: um trunk SIP BYO da Vapi (endereço <credentialId>.sip.vapi.ai, ou <credentialId>.sip.eu.vapi.ai para uma organização na região da UE) não aceita credenciais. A Vapi reconhece as nossas chamadas pelo IP nos gateways do trunk e, com sipUsername e sipPassword preenchidos, a chamada nunca se estabelece, pelo que a API rejeita esse encaminhamento com o código de validação. O número SIP nativo da Vapi (sip:<name>@sip.vapi.ai) não é afetado.

2Credenciais SIP de um número

Obtenha as credenciais da linha com uma única chamada:

curl "https://volai.eu/v1/numbers/+420601234567/sip" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "server": "sip.volai.cz",
  "username": "123456",
  "password": "a1b2c3d4e5f6",
  "outboundTrunkAddress": "sip.volai.cz",
  "port": 5060,
  "transport": "tcp",
  "inboundSignallingCidrs": ["81.31.45.0/24"]
}

Configuração num softphone (Zoiper, Linphone)

Ambas as aplicações pedem basicamente o mesmo, apenas com nomes diferentes - procure "Add account" / "SIP account":

Depois de guardar, o softphone deve registar-se (um ícone de estado "online"/"registado") e as chamadas para o número começarão a tocar diretamente nele.

3Chamadas efetuadas a partir de um cliente SIP

Depois de o softphone estar registado, pode marcar por si próprio através desta linha - não precisa de chamar nenhuma das nossas APIs, marca diretamente a partir do cliente como numa linha telefónica normal.

4Limites

• Um registo por linha - um conjunto de credenciais suporta um dispositivo registado de cada vez. Se iniciar sessão com um segundo cliente, o primeiro perderá provavelmente o registo - não conte com vários dispositivos em simultâneo na mesma linha.
• Chamadas efetuadas a partir do seu próprio agente sim, peering completo de trunk não - as credenciais da linha permitem que o SEU cliente se registe connosco como telefone. As chamadas efetuadas a partir do seu próprio agente de voz (ElevenLabs ou outra plataforma) FUNCIONAM, no entanto, hoje - através do relay, veja Traga o seu próprio agente. Continua, porém, a não ser possível ligar a sua central como operador par com encaminhamento próprio para chamadas RECEBIDAS do exterior - para isso use o encaminhamento forward para o número da sua central.
• Apenas voz - sem vídeo nem outras extensões SIP.