Pular para o conteúdo
Atalho: /, ⌘K ou Ctrl+K

Troncos SIP

Conecte o seu PBX ou tronco SIP existente às chamadas do WhatsApp de um número conectado.

Ver em Markdown

Um tronco SIP conecta um sistema telefônico que você já opera, como um PBX ou uma plataforma de central de atendimento, às chamadas do WhatsApp de um número conectado. As chamadas recebidas do WhatsApp podem tocar no seu PBX, e o seu PBX pode ligar para usuários do WhatsApp pelo número. A Polymorfa não hospeda um PBX e não fornece números de telefone.

Os troncos SIP fazem parte das Chamadas. Toda equipe que usa as Chamadas pode criar troncos em qualquer um dos seus projetos; não é preciso se inscrever. No Console, proprietários e administradores da equipe adicionam, alteram e excluem troncos. Leia o endereço SIP e as portas aos quais o seu PBX se conecta pela API ou pelo Console; consulte Encontre o endereço SIP.

Como um tronco funciona #

Um tronco pertence a um projeto e tem uma direção:

directionEfeito
outboundA Polymorfa envia ao seu PBX as chamadas recebidas do WhatsApp das sessões roteadas.
inboundO seu PBX faz chamadas do WhatsApp por uma sessão do projeto.
bothAs duas opções acima.

Em uma chamada, o tronco é um participante chamado server:sip:<trunkId>. A conexão dele informa o transporte sip. As pessoas no WhatsApp sempre ouvem o seu PBX, e o seu PBX sempre as ouve. Ele nunca ouve o próprio áudio. Se o seu PBX e os seus outros participantes ouvem uns aos outros depende do modo conferência da sessão: ativado (o padrão), eles se ouvem; desativado, cada um ouve apenas as pessoas no WhatsApp. Os troncos SIP transportam apenas áudio.

Gerencie os troncos com a Platform API. A leitura exige sessions:read; toda alteração exige sessions:manage. Use uma chave de equipe com projectId, ou um token de projeto para o próprio projeto. Tokens de cliente não podem gerenciar troncos.

TypeScript:

O SDK gerencia os troncos com sipTrunks em um cliente de projeto; um cliente da equipe passa o ID do projeto como primeiro argumento de list e create.

Você também pode gerenciar os troncos no Console: abra um projeto, acesse Chamadas e escolha a aba Troncos SIP. Consulte Chamadas no Console.

Encontre o endereço SIP #

Todos os troncos de todos os projetos usam o mesmo endereço SIP. Leia-o com API Get SIP endpoint. Ele exige sessions:read e aceita uma chave de equipe ou um token de projeto:

cURL
curl "https://api.polymorfa.com/platform/sip/endpoint" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
TypeScript
const endpoint = await platform.sipTrunks.endpoint();
if (endpoint.data.status === "hosted") {
  console.log(endpoint.data.host, endpoint.data.transports, endpoint.data.rtp);
}

A resposta:

JSON
{
  "success": true,
  "data": {
    "status": "hosted",
    "host": "SIP_HOST",
    "transports": [
      { "transport": "udp", "port": 5060, "srtp": "not_supported" },
      { "transport": "tcp", "port": 5060, "srtp": "not_supported" },
      { "transport": "tls", "port": 5061, "srtp": "required" }
    ],
    "rtp": { "protocol": "udp", "portMin": 31000, "portMax": 31099 }
  }
}

A resposta descreve o ambiente ao qual a sua chave pertence, então use os valores que ela retorna em vez dos marcadores acima.

CampoDescrição
statushosted, ou sip_not_hosted quando o ambiente não tem endereço SIP.
hostNome do host para o qual o seu PBX envia SIP. null quando status é sip_not_hosted.
transportsCada transporte SIP com a porta dele. srtp é required para tls e not_supported para udp e tcp. Vazio quando status é sip_not_hosted.
rtpIntervalo de portas UDP que a Polymorfa usa para o áudio das chamadas. null quando status é sip_not_hosted.

Quando status é sip_not_hosted, o ambiente não tem um endereço SIP ao qual um PBX possa se conectar, e a resposta não retorna host nem portas.

Configure o seu firewall com estes valores:

  • Permita SIP nas portas listadas, nos dois sentidos, entre o seu PBX e os endereços para os quais host resolve.
  • Permita UDP nos dois sentidos entre as portas de mídia do seu PBX e o intervalo rtp nos mesmos endereços.
  • Prefira tls: ele criptografa a sinalização, e a exigência de SRTP dele criptografa o áudio. udp e tcp transportam os dois sem criptografia.

Você também encontra o endereço no Console, na página Troncos SIP.

Crie um tronco #

cURL
curl -X POST "https://api.polymorfa.com/platform/sip-trunks" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "PROJECT_ID",
    "name": "Head office PBX",
    "direction": "both",
    "outbound": {
      "targetUri": "sip:whatsapp@pbx.example.com:5061",
      "transport": "tls",
      "authUsername": "polymorfa",
      "authPassword": "PBX_PASSWORD"
    },
    "inbound": {
      "session": "support",
      "allowedAddresses": ["203.0.113.10", "198.51.100.0/28"],
      "allowedDestinations": ["+44", "+1415"]
    },
    "codecs": ["PCMA", "PCMU", "opus"],
    "maxConcurrentCalls": 30
  }'
TypeScript
// A project client: it supplies the project.
const created = await project.sipTrunks.create({
  name: "Head office PBX",
  direction: "both",
  outbound: {
    targetUri: "sip:whatsapp@pbx.example.com:5061",
    transport: "tls",
    authUsername: "polymorfa",
    authPassword: "PBX_PASSWORD",
  },
  inbound: {
    session: "support",
    allowedAddresses: ["203.0.113.10", "198.51.100.0/28"],
    allowedDestinations: ["+44", "+1415"],
  },
  codecs: ["PCMA", "PCMU", "opus"],
  maxConcurrentCalls: 30,
});

// Store the inbound password now in your application's secret store, which is not an SDK API.
// The API does not return it again. Do not log it.
await secretManager.store("sip/head-office/inbound", created.data.inboundCredentials);

A resposta retorna 201 com o tronco e, para troncos inbound e both, inboundCredentials:

JSON
{
  "success": true,
  "data": {
    "trunk": { "id": "TRUNK_ID", "direction": "both", "revision": 1, "...": "..." },
    "inboundCredentials": {
      "username": "tq7m4k2xmabn5c3dpe6fr2hw",
      "password": "SHOWN_ONCE",
      "realm": "polymorfa"
    }
  }
}

Um projeto comporta até 100 troncos. Cada tronco transporta no máximo maxConcurrentCalls chamadas ao mesmo tempo (de 1 a 500, padrão 30).

Envie chamadas do WhatsApp para o seu PBX #

Defina estes campos em outbound:

CampoDescrição
targetUriURI sip: ou sips: do seu PBX, com um nome de host público ou endereço IP e uma porta opcional. Uma parte de usuário, como em sip:support@pbx.example.com, se torna o usuário chamado.
transportudp, tcp ou tls. Uma URI sips: exige tls. A porta padrão é 5060, ou 5061 para tls.
authUsernameUsuário com que a Polymorfa responde quando o seu PBX envia um desafio digest. Defina-o junto com authPassword.
authPasswordSenha somente de escrita para authUsername.
fromUserSubstituição opcional do usuário do cabeçalho From. Defina-a quando o seu PBX exigir um endereço de origem fixo.

Depois, roteie as chamadas recebidas da sessão para o tronco:

Shell
curl -X PUT "https://api.polymorfa.com/platform/sessions/support/call-settings" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inboundRoute": "sip_trunk",
    "sipTrunkId": "TRUNK_ID",
    "sipClaim": true
  }'

O tronco precisa pertencer ao projeto da sessão e ter a direção outbound ou both. As configurações que você omite mantêm os valores; uma atualização posterior sem sipTrunkId mantém o tronco. Para parar de enviar chamadas ao tronco, envie "inboundRoute": "clients", o que também limpa sipTrunkId. Em um número da Cloud API, as chamadas recebidas só chegam ao tronco quando hostCloudApiCalls é true; consulte Números da Cloud API. Consulte Update call settings.

Quando uma chamada roteada toca, a Polymorfa liga para targetUri. A chamada continua tocando para os participantes do seu SDK, e eles podem atendê-la primeiro. A requisição para o seu PBX leva o ID da chamada do WhatsApp no cabeçalho X-Polymorfa-Call-ID.

  • Quando o seu PBX atende, a Polymorfa atende a chamada do WhatsApp como server:sip:<trunkId>. Com sipClaim: true, o atendimento faz o claim da chamada: os outros participantes param de tocar e não podem entrar. Com sipClaim: false, a chamada continua compartilhada e outros participantes podem entrar. Consulte Atender, entrar ou recusar.
  • Quando o seu PBX não atende, a chamada do WhatsApp continua tocando para os seus outros participantes até ser atendida ou recusada, ou até a janela de toque terminar.
  • Quando o seu PBX desliga, a conexão dele sai. Se o tronco fez o claim da chamada, a chamada termina. Quando a chamada do WhatsApp termina, a Polymorfa desliga o seu PBX.

O evento call.connection_left do tronco informa por que a conexão dele saiu:

reasonSignificado
leftO seu PBX desligou.
call_endedA chamada do WhatsApp terminou.
claimedOutro participante fez o claim da chamada antes.
sip_busyO seu PBX respondeu ocupado (486 ou 600).
sip_declinedO seu PBX recusou a chamada (603 ou 403).
sip_no_answerO seu PBX não atendeu em 60 segundos, ou respondeu 408, 480 ou 487.
sip_auth_failedO seu PBX rejeitou authUsername e authPassword.
sip_unavailableO destino estava inacessível, recusou a chamada ou retornou uma resposta inutilizável, inclusive um endereço de mídia para o qual a Polymorfa não envia.

Um tronco que nunca atendeu informa apenas a saída, sem uma entrada anterior.

Os controles de mídia ao vivo informam call_ended quando uma conexão estabelecida fecha porque a chamada terminou. Um desligamento normal pelo PBX continua como left. Os webhooks encerram as conexões ainda abertas com call.ended, sem um evento call.connection_left adicional.

Ligue para o WhatsApp a partir do seu PBX #

Configure o seu PBX com:

  • o host e uma porta de Encontre o endereço SIP;
  • inboundCredentials.username e password para a autenticação digest; e
  • o número do WhatsApp a chamar, no formato E.164, como parte de usuário da URI da requisição, por exemplo sip:+14155550100@SIP_HOST. O + inicial é opcional e um prefixo 00 é aceito.

Defina inbound.session como a sessão que faz as chamadas. A Polymorfa só aceita uma chamada quando as credenciais digest são válidas, a requisição vem de um dos allowedAddresses, o tronco está ativado, o projeto dele está ativo e o número corresponde a um dos allowedDestinations (ou a lista está vazia). A chamada conta para o mesmo limite por minuto de chamadas realizadas que as chamadas feitas pela API a partir dessa sessão.

O tronco faz o claim de toda chamada que faz. O seu PBX recebe:

RespostaQuando
401A requisição não tinha credenciais, ou reutilizou um desafio expirado ou já usado. Responda ao novo desafio.
403A autenticação falhou, o endereço ou o destino não é permitido, o tronco está desativado ou as chamadas estão desativadas na sessão dele.
404O usuário da URI da requisição não é um número de telefone, ou o número não está no WhatsApp.
180O telefone do usuário do WhatsApp está tocando.
200O usuário do WhatsApp atendeu.
408O usuário do WhatsApp não atendeu.
480Nenhuma sessão está definida, ou não foi possível conectar a chamada.
486O tronco já está transportando maxConcurrentCalls chamadas.
488A oferta não tem nenhum codec suportado, a segurança de mídia dela não corresponde ao transporte ou o endereço de mídia dela não é aceito (consulte Mídia e segurança).
503A capacidade de chamadas ou o limite por minuto foi atingido. Tente novamente mais tarde, depois do intervalo de Retry-After quando ele for enviado.
603O usuário do WhatsApp recusou a chamada.

Toda recusa de autenticação é o mesmo 403, então a resposta não revela qual verificação falhou. Falhas repetidas de autenticação bloqueiam temporariamente o endereço de origem. Quando o seu PBX cancela uma chamada que está tocando, a chamada do WhatsApp termina. Quando o seu PBX desliga uma chamada conectada, a chamada termina para todos.

Mídia e segurança #

  • Codecs. PCMU e PCMA (8 kHz) e Opus (48 kHz, mono), na ordem de codecs. Para Opus, anuncie opus/48000/2 no SDP; o áudio continua mono. Se um mapeamento de Opus for inutilizável, um codec PCMU ou PCMA oferecido pode transportar a chamada. O seu PBX precisa oferecer mídia no INVITE inicial; chamadas sem oferta são recusadas com 488. As respostas a chamadas da Polymorfa precisam manter o número de carga RTP de um codec oferecido. Alterações de mídia durante a chamada são recusadas.
  • Pacotes. 20 ms de áudio por pacote RTP.
  • Criptografia. Com tls, a sinalização é criptografada e a mídia usa SRTP com chaves SDES (AES_CM_128_HMAC_SHA1_80 ou AES_CM_128_HMAC_SHA1_32). Ofertas de RTP simples sobre TLS e ofertas de SRTP sobre UDP ou TCP são recusadas. Use tls quando o seu PBX estiver acessível pela internet.
  • Endereços. Envie mídia a partir do endereço na descrição de sessão do seu PBX ou a partir do endereço de onde vem a sua sinalização. A Polymorfa envia a mídia de volta ao endereço de onde chega o seu primeiro pacote de mídia.
  • PBX atrás de NAT. Um endereço privado (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 100.64.0.0/10 ou fc00::/7) na descrição de sessão só funciona quando a sua sinalização vem de um endereço público. Nesse caso, a Polymorfa não envia mídia até que o primeiro pacote de mídia do seu PBX chegue desse endereço de sinalização, então o seu PBX precisa começar a enviar mídia.
  • Endereços recusados. Descrições de sessão com um endereço de mídia de loopback, link-local, multicast, não especificado ou reservado são recusadas: a chamada do seu PBX recebe 488, e uma chamada para o seu PBX termina com sip_unavailable. Destinos de tronco em endereços privados, de loopback ou link-local são rejeitados.

Gerencie os troncos #

OperaçãoRequisição
Listar os troncos de um projetoGET /platform/sip-trunks?projectId=PROJECT_ID
Ler um troncoAPI Get SIP trunk
Alterar um troncoAPI Update SIP trunk
Excluir um troncoAPI Delete SIP trunk
Fazer a rotação da senha de entradaAPI Rotate SIP trunk credentials
Ler o endereço SIPAPI Get SIP endpoint

TypeScript:

Desative um tronco com project.sipTrunks.update(trunkId, { enabled: false, expectedRevision }) e emita uma nova senha de entrada com project.sipTrunks.rotateCredentials(trunkId).

  • PATCH altera apenas os campos que você envia. Omita authPassword para manter a senha armazenada; envie authUsername: null para remover os dois. Envie expectedRevision para recusar a alteração com 409 sip_trunk_revision_conflict quando outra pessoa tiver alterado o tronco antes.
  • Mudar direction para outbound remove as credenciais de entrada. Mudar um tronco outbound para inbound ou both cria um novo usuário; faça a rotação das credenciais dele para obter a senha.
  • A rotação de credenciais substitui a senha. A senha antiga deixa de funcionar em cerca de um minuto. A rotação retorna 409 state_conflict para troncos outbound.
  • Excluir um tronco para o qual uma sessão ainda envia chamadas retorna 409 sip_trunk_in_use. Antes, faça a sessão voltar a usar clients.
  • As alterações chegam ao roteamento de chamadas em cerca de um minuto. As chamadas em andamento continuam.
  • Quando o projeto de um tronco é desativado, alterar o tronco ou fazer a rotação das credenciais dele retorna 404 resource_not_found. A Polymorfa deixa de enviar chamadas ao tronco e recusa as chamadas do PBX dele em cerca de um minuto. Você ainda pode listar, ler e excluir o tronco.

Erros #

StatuscodeSignificado
400invalid_parameterUm campo está ausente ou é inválido; param indica qual.
400invalid_sip_trunkO tronco roteado não está no projeto da sessão ou não pode receber chamadas.
403permission_deniedA credencial é um token de cliente ou não alcança esse projeto.
404resource_not_foundO tronco ou o projeto não existe para a sua credencial, ou o projeto está desativado.
409sip_trunk_in_useUma sessão envia chamadas para o tronco.
409sip_trunk_revision_conflictO tronco mudou depois da revisão que você enviou.
409sip_trunk_limitO projeto já tem 100 troncos.
503sip_unavailableOs troncos SIP não estão disponíveis no momento.

Consulte Erros para o formato completo de erro.