--- title: "Traga seus próprios números (VoIP, API)" description: "Conecte Twilio, Telnyx, SignalWire, Vonage, Plivo e qualquer outro tronco SIP via SIP, importe os números de telefone que você já possui e deixe os agentes de voz do ThunderPhone atenderem e fazerem chamadas com eles." --- Números aprovados do ThunderPhone podem fazer chamadas de saída e executar campanhas. Se preferir usar números próprios por meio do seu provedor de VoIP, este guia mostra o fluxo de conexão: **testar credenciais → criar conexão → importar números → verificar**. O painel tem uma versão guiada de todo esse fluxo em **Conexões → VoIP** (`/dashboard/voip-connections`): primeiro, um caminho para conectar números existentes (Twilio e Telnyx por chave de API; SignalWire, Vonage, Plivo e qualquer outro tronco pelo formulário manual de SIP com etapas específicas do provedor e um gerador de guia de configuração com IA) e, em seguida, uma configuração guiada que abre uma nova conta Telnyx. ## Provedores compatíveis | Provedor | ID de `provider` | Observações | |----------|---------------|-------| | Twilio | `twilio` | SID da conta + token de autenticação; uma conexão por conta ou subconta da Twilio (consulte [subcontas da Twilio](#twilio-subaccounts)) | | Telnyx | `telnyx` | Chave de API; onboarding guiado disponível (`setup_method: guided_telnyx`) | | SignalWire | `signalwire` | Sem conexão nativa com o provedor; conecte-o como `manual` com a predefinição SIP da SignalWire | | Vonage | `vonage` | Sem conexão nativa com o provedor; conecte-o como `manual` com a predefinição SIP da Vonage | | SIP manual | `manual` | Qualquer tronco SIP, incluindo SignalWire, Vonage e Plivo. Se você começar por um dos cartões desses provedores no dashboard, a conexão continuará sendo `manual` e armazenará a escolha em `sip_config.preset` (`signalwire`, `vonage` ou `plivo`) | ## 1. Teste as credenciais Antes de criar uma conexão VoIP persistente, teste as credenciais do provedor para confirmar que funcionam. Isso retorna um `verification_evidence_id` que você passa para a etapa de criação, para que as credenciais não sejam cobradas duas vezes pelos testes. ```bash curl -X POST https://api.thunderphone.com/v1/voip-connections/test \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "provider": "telnyx", "credentials": { "apiKey": "KEY...", "connectionId": "123456" }, "sip_config": { "domain": "acme.sip.telnyx.com" } }' ``` ```json Response { "status": "pass", "verification_evidence_id": "b9a2...", "suggested_connection_name": "Telnyx: Acme Main (+15550001234)", "checks": { "credentials_valid": true, "inbound_reachable": true, "outbound_authorized": true } } ``` Se alguma verificação falhar, o `status` da resposta será `fail` e `checks` mostrará qual etapa falhou. Corrija a configuração no lado do provedor (atribuição de tronco, lista de permissões de IP, autorização de saída) e tente novamente. ## 2. Crie a conexão Passe o `verification_evidence_id` que você acabou de receber: ```bash curl -X POST https://api.thunderphone.com/v1/voip-connections \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Acme Telnyx Main", "provider": "telnyx", "setup_method": "api_key", "credentials": { "apiKey": "KEY...", "connectionId": "123456" }, "sip_config": { "domain": "acme.sip.telnyx.com" }, "verification_evidence_id": "b9a2..." }' ``` A resposta é um [objeto VoipConnection](/api-reference/voip-connections#connection-object) com `status="connected"`. As credenciais e outros valores secretos da conexão são armazenados no servidor e nunca retornados em texto simples por GETs subsequentes — para fazer a rotação, execute um novo `test` e faça PATCH com a nova evidência. ### Subcontas do Twilio Uma conexão Twilio fica vinculada à única conta Twilio cujos Account SID e Auth Token ela contém. A Twilio mantém números de telefone e troncos SIP dentro de cada subconta, portanto uma conexão criada com a conta pai vê apenas os próprios números da conta pai, e uma conexão existente não pode ser alterada posteriormente para uma subconta diferente. Para acessar números mantidos em subcontas, crie uma conexão por subconta. O dashboard faz isso por você: ao conectar uma conta pai que possui subcontas ativas, a caixa de diálogo de configuração as lista, você marca as que deseja, e o ThunderPhone cria uma conexão (e um tronco SIP) em cada uma. O mesmo fluxo está disponível pela API: ```bash # Discover active subaccounts visible to the parent credentials curl -X POST https://api.thunderphone.com/v1/voip-connections/twilio/subaccounts \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"credentials": {"accountSid": "ACparent...", "authToken": "..."}}' ``` ```json Response { "discovery_id": "7c1e...", "parent": { "sid": "ACparent...", "friendly_name": "Acme" }, "subaccounts": [ { "sid": "ACsupport...", "friendly_name": "Acme Support", "already_connected": false, "connection_id": null }, { "sid": "ACsales...", "friendly_name": "Acme Sales", "already_connected": true, "connection_id": 5 } ] } ``` ```bash # Create a connection for each selected subaccount curl -X POST https://api.thunderphone.com/v1/voip-connections/twilio/subaccounts/connect \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"discovery_id": "7c1e...", "subaccount_sids": ["ACsupport..."]}' ``` A resposta contém uma linha por subconta com `status` `created`, `skipped` (já conectada) ou `failed`, além de um `error` sobre o qual você pode agir. As linhas são independentes, portanto, uma falha em uma subconta nunca bloqueia as demais, e um `discovery_id` permanece válido por 30 minutos, para que uma linha com falha possa simplesmente ser repetida. Os tokens das subcontas são lidos do Twilio no momento da descoberta e armazenados na nova conexão; eles nunca são retornados pela API. Cada nova conexão importa e verifica números exatamente como uma conexão criada manualmente. Adicione `"enable_transfers": true` para também ativar transferências de chamada no tronco SIP de cada nova conexão; uma falha nesse processo é informada em `test_result.transfer_enable_error` dessa conexão e não causa falha na linha. ## 3. Liste e importe números Inspecione os números visíveis para suas credenciais que ainda não estão em uma organização do ThunderPhone: ```bash curl https://api.thunderphone.com/v1/voip-connections/5/available-numbers \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" ``` Em seguida, importe os que desejar: ```bash curl -X POST https://api.thunderphone.com/v1/voip-connections/5/import-numbers \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"numbers": ["+15550001234", "+15550009999"]}' ``` Cada importação se torna um [recurso de número de telefone](/api-reference/phone-numbers) na sua organização com `number_type="voip"` e `status="provisioning"`. ## 4. Verifique cada número importado A importação registra o número como *disponível*; para realmente rotear chamadas por ele, é necessária uma verificação. Para conexões de provedores (Twilio, Telnyx), isso verifica novamente as credenciais do provedor e a acessibilidade SIP. Para uma conexão de **SIP manual**, primeiro é feita uma chamada de autoverificação em loop: o ThunderPhone realiza uma breve chamada de teste *a partir* do número, *por meio* do seu tronco SIP, *de volta para o mesmo número*. Se isso não verificar o caminho de entrada, ele recorre a uma breve chamada de teste *a partir* do número, *por meio* do seu tronco SIP, *para* um número do ThunderPhone. Esses testes verificam o nome de usuário, a senha, o transporte, o roteamento de saída e a entrega de entrada do tronco. Sua operadora cobra essas chamadas como qualquer outra. ```bash curl -X POST https://api.thunderphone.com/v1/phone-numbers/{id}/verify-voip \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" ``` Em caso de sucesso, `voip_verification_status` muda para `verified` e o número passa para `status="active"`. Um número na sua própria conta Telnyx continua recebendo chamadas de entrada quando a chamada de teste falha ou a saída ainda não está configurada: ele passa para `status="active"` com `voip_verification_status` definido como `unverified`, e a resposta informa o motivo. Em caso de falha, a resposta detalha o que falhou — para um tronco manual, essa é a resposta SIP da operadora, por exemplo *"rejeitou as credenciais do ThunderPhone (SIP 401)"* ou *"não foi possível rotear uma chamada (SIP 404)"* — corrija o problema (credenciais, IPs de origem permitidos, uma atribuição de tronco ausente no painel da operadora) e chame novamente. Para uma conexão SIP manual com lista de permissões, o teste de chamada recebida também falha se esses IPs de origem permitidos bloquearem uma chamada recebida real. ## 5. Atribua agentes e receba uma chamada Com o número verificado, atribua agentes de entrada / saída da mesma forma que para um número do ThunderPhone. Consulte [Gerenciar chamadas de entrada](/pt/guides/handle-inbound-calls) e [Realizar chamadas de saída](/pt/guides/place-outbound-calls). ## Rotação de credenciais Quando uma chave de provedor for rotacionada, execute novamente o fluxo de testar e atualizar: ```bash # 1. Test the new credentials curl -X POST https://api.thunderphone.com/v1/voip-connections/test ... # 2. PATCH the connection with the new evidence curl -X PATCH https://api.thunderphone.com/v1/voip-connections/{id} \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "credentials": { "apiKey": "NEW_KEY..." }, "verification_evidence_id": "fresh-evidence-id" }' ``` A conexão permanece no lugar — não é necessário importar os números novamente. --- ## Próximas etapas Todos os campos nas respostas de conexão, evidência e importação. Atribua agentes, transfira entre organizações, libere números. Agora que você tem o número, comece a realizar chamadas de saída.