Traga seus próprios números (VoIP, API)

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.

Provedores compatíveis#

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.

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" }
  }'

{
  "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:

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 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:

# 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": "..."}}'

{
  "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 }
  ]
}

# 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:

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:

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 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.

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 e Realizar chamadas de saída.

Rotação de credenciais#

Quando uma chave de provedor for rotacionada, execute novamente o fluxo de testar e atualizar:

# 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#