Conecte-se via SIP (sem número de telefone)

Envie chamadas para um agente do ThunderPhone diretamente do seu PABX, operadora ou aplicação SIP, com um URI SIP único por chamada ou um endereço SIP permanente.

Se o seu próprio sistema já lida com números de telefone (um PABX, uma plataforma de contact center ou uma conta de operadora em que você alterna números), você pode enviar chamadas para um agente do ThunderPhone por SIP padrão. Você não importa nem compra um número no ThunderPhone. Seu sistema disca um endereço SIP e o agente atende.

Há dois tipos de endereço SIP:

Ambos os tipos são roteados para um agente da sua organização e ambos aparecem no histórico de chamadas como qualquer outra chamada recebida.

URI SIP por chamada#

1. Registre a chamada#

curl -X POST https://api.thunderphone.com/v1/calls/register-sip \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": 12,
    "to_number": "+14155550142",
    "variables": {"customer_name": "Ada"}
  }'

{
  "call_id": 862197007562,
  "sip_uri": "sip:c-1790372992.Qm3xT8vLk2PzR7nYw4HbJa.uF6sD1gK9eW2cX5vB8nM0q@sip.thunderphone.com",
  "expires_at": "2026-09-25T21:49:52Z",
  "agent_id": 12,
  "to_number": "+14155550142"
}

• to_number (opcional) é o número que quem liga discou no seu sistema. Ele é armazenado como o destino da chamada no histórico de chamadas, e o agente o vê como seu próprio número.
• variables (opcional) preenchem {{placeholders}} no prompt do agente, da mesma forma que em chamadas de saída.
• call_id é o id que a chamada terá no histórico de chamadas (GET /v1/calls/{call_id}) quando for conectada.

2. Disque a URI#

Envie a chamada para sip_uri em até 5 minutos. A URI funciona para apenas uma chamada: depois que uma chamada a usa, ela é consumida, mesmo que essa chamada termine rapidamente.

Com a Twilio, por exemplo, retorne este TwiML para a chamada que você quer transferir:

<Response>
  <Dial>
    <Sip>sip:c-1790372992.Qm3xT8vLk2PzR7nYw4HbJa.uF6sD1gK9eW2cX5vB8nM0q@sip.thunderphone.com;transport=tcp</Sip>
  </Dial>
</Response>

De um PABX, disque a URI como destino SIP. Não é necessário nome de usuário nem senha; o token é a credencial, portanto trate a URI como uma senha até que ela tenha sido usada.

Endpoint SIP (endereço permanente)#

1. Crie o endpoint#

curl -X POST https://api.thunderphone.com/v1/sip-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": 12, "name": "Main PBX"}'

{
  "id": 7,
  "name": "Main PBX",
  "agent_id": 12,
  "sip_uri": "sip:agent-12-jhxmginwjx@sip.thunderphone.com",
  "username": "tp409667538f83",
  "password": "8mJ0…",
  "allowed_source_cidrs": [],
  "status": "active",
  "created_at": "2026-09-25T21:46:18Z"
}

2. Aponte seu sistema para ele#

Configure um tronco SIP ou destino com:

Estas configurações de transporte e codec também se aplicam a URIs por chamada. Dois detalhes de rede são importantes para os dois tipos de endereço:

• Siga o Record-Route. Após o primeiro INVITE, o restante da sinalização da chamada (ACK, desligamento, transferências) vai para o servidor específico do ThunderPhone que respondeu, identificado no cabeçalho Record-Route (sip-1.thunderphone.com ou sip-2.thunderphone.com, ou seu endereço IP). Se você restringe SIP de saída, permita esses hosts, além de sip.thunderphone.com: 172.170.39.202 (sip), 13.86.104.121 (sip-1) e 20.80.98.90 (sip-2).
• O áudio vai para outro lugar. sip.thunderphone.com transporta apenas sinalização. Permita mídia (RTP) para os endereços e portas na resposta SDP.

Toda chamada para o endereço chega ao agente do endpoint, independentemente do número que quem liga discou do seu lado. Você nunca importa números, portanto alterná-los do seu lado não exige nenhuma alteração no ThunderPhone.

Transmita o número discado (opcional)#

Para registrar qual dos seus números quem liga discou, envie-o no INVITE em um cabeçalho X-Original-To (por exemplo, X-Original-To: +14155550142) ou em um cabeçalho padrão Diversion. O ThunderPhone o armazena como o destino da chamada.

O destino é escolhido nesta ordem: o to_number informado quando uma URI por chamada foi registrada, depois um número em X-Original-To, depois um em Diversion. Se nenhum deles fornecer um número, será exibido como sip:agent-12-jhxmginwjx (o endereço do endpoint) para um endpoint, ou sip:call para uma URI por chamada.

Com o Twilio, você pode adicionar o cabeçalho à URI SIP: sip:agent-12-jhxmginwjx@sip.thunderphone.com;transport=tcp?X-Original-To=%2B14155550142.

Restrinja IPs de origem (opcional)#

Defina allowed_source_cidrs para aceitar chamadas somente dos seus próprios endereços de sinalização, além do nome de usuário e da senha:

curl -X PATCH https://api.thunderphone.com/v1/sip-endpoints/7 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"allowed_source_cidrs": ["203.0.113.0/28"]}'

Chamadas de qualquer outro endereço são recusadas antes de chegarem ao agente. Use os endereços dos quais seu sistema envia sinalização SIP (para uma operadora como a Twilio, os intervalos de IP de sinalização publicados por ela), não seus endereços de mídia.

O que quem liga e seu sistema veem#

• Identificação de quem liga: a parte do usuário do cabeçalho From é armazenada como quem liga. Um número de telefone (dígitos, opcionalmente com +, espaços, hífens, pontos ou parênteses) é normalizado para E.164; qualquer outra coisa, como um nome de usuário SIP, é mantida como enviada. São mantidos no máximo 32 caracteres, e a ausência de quem liga é armazenada como anonymous.
• Chamadas recusadas: uma URI por chamada desconhecida ou expirada recebe SIP 404 Not Found. Uma URI por chamada já usada, um endpoint desativado ou uma origem fora da lista de permissões (incluindo qualquer chamada UDP para um endpoint com uma lista de permissões) é desconectada antes de o agente iniciar: seu sistema pode ver a chamada falhar ou conectar e encerrar imediatamente. Essas recusas não criam uma entrada no histórico de chamadas. Se sua organização estiver sem crédito ou tiver atingido seu limite de gastos, a chamada será recusada e aparecerá no histórico de chamadas como uma chamada com falha sem cobrança. Para tentar novamente uma tentativa por chamada, registre uma nova URI.
• Transferências: as transferências frias do agente funcionam (o ThunderPhone envia um SIP REFER, que seu sistema deve aceitar). Transferências assistidas não estão disponíveis em chamadas para endereços SIP, porque não há um número do ThunderPhone para mostrar como identificação de quem liga na segunda etapa. Com a Twilio, o TwiML acima conecta o agente, mas não processa transferências: adicione referUrl="https://YOUR_SERVER/sip-transfer" ao <Dial>, e faça esse webhook ler ReferTransferTarget e retornar TwiML que disca o destino da transferência (consulte o guia SIP REFER da Twilio).
• Mensagens de texto: o endereço SIP e o número discado não podem enviar mensagens de texto. O agente pode enviar mensagens de texto durante uma chamada para endereço SIP somente se tiver um número separado com suporte a SMS configurado para mensagens de texto; caso contrário, sua ferramenta de SMS ficará indisponível.
• Registro: o ThunderPhone não aceita SIP REGISTER. Envie chamadas para o endereço; não faça registro nele.

Preços#

As chamadas para endereços SIP são cobradas pela tarifa normal por minuto do agente. Não há cobrança de número de telefone, porque nenhum número do ThunderPhone transporta a chamada. Sua própria operadora cobra seu lado da chamada normalmente. Consulte Preços.

Teste#

1. Crie uma URI por chamada ou um endpoint conforme descrito acima.
2. Disque para ele a partir do seu sistema ou de qualquer softphone SIP (para um endpoint, informe o nome de usuário e a senha).
3. Após desligar, abra a chamada em Chamadas no painel ou busque-a com GET /v1/calls/{call_id}. Ela mostra quem ligou, o destino (consulte a ordem em "Passe o número discado") e a transcrição.

Detalhes da API: referência da API de endereços SIP.