--- title: "Conecte-se via SIP (sem número de telefone)" description: "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: | | **URI SIP por chamada** | **Endpoint SIP** | |---|---|---| | Tem esta aparência | `sip:c-@sip.thunderphone.com` | `sip:agent--@sip.thunderphone.com` | | Criado com | `POST /v1/calls/register-sip`, uma vez por chamada | `POST /v1/sip-endpoints`, uma vez | | Autenticação | O token de uso único no endereço | Nome de usuário + senha de SIP digest (e, opcionalmente, uma lista de permissões de IPs de origem) | | Ideal para | Aplicativos que já chamam uma API antes de transferir uma chamada; variáveis por chamada | PABXs e operadoras que devem apenas "apontar um tronco" para o ThunderPhone | | Válido por | 5 minutos, uma chamada | Até você excluí-lo | 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 ```bash 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"} }' ``` ```json { "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](/pt/guides/call-variables). - `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: ```xml sip:c-1790372992.Qm3xT8vLk2PzR7nYw4HbJa.uF6sD1gK9eW2cX5vB8nM0q@sip.thunderphone.com;transport=tcp ``` 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 ```bash 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"}' ``` ```json { "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" } ``` A `password` é retornada apenas uma vez, quando o endpoint é criado. Armazene-a imediatamente na configuração do seu PABX ou da sua operadora. Se perdê-la, altere-a com `POST /v1/sip-endpoints/{id}/rotate-password`. ### 2. Aponte seu sistema para ele Configure um tronco SIP ou destino com: | Configuração | Valor | |---|---| | URI SIP | o `sip_uri` do endpoint | | Nome de usuário / senha | `username` / `password` (autenticação digest; o ThunderPhone desafia cada chamada) | | Transporte | TCP na porta 5060 ou TLS na porta 5061 (recomendado), ou UDP na porta 5060 | | Codecs | G.711 (PCMU/PCMA) ou G.722 | Prefira TCP ou TLS. O UDP funciona a partir de endereços públicos e da maioria dos NATs, mas atrás de um NAT "simétrico" (que usa uma nova porta para cada destino), os desligamentos e transferências do agente podem não chegar ao seu sistema. Uma lista de permissão por IP de origem (abaixo) também exige TCP ou TLS. Com TLS, a sinalização SIP permanece criptografada além de `sip.thunderphone.com`, até os servidores que processam a chamada. 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: ```bash 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. A lista de permissão é verificada apenas para chamadas por TCP ou TLS. Um endereço de origem UDP pode ser falsificado, portanto um endpoint com uma lista de permissão recusa todas as chamadas que chegam por UDP. Envie chamadas para ele com `;transport=tcp` (porta 5060) ou por TLS (porta 5061). ## 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 ``, e faça esse webhook ler `ReferTransferTarget` e retornar TwiML que disca o destino da transferência (consulte o [guia SIP REFER da Twilio](https://www.twilio.com/docs/voice/api/refer-to-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](/pt/guides/pricing). ## 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](/api-reference/sip-addresses).