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

Números de demonstração são adequados para prototipagem, mas o tráfego de produção deve usar números que você possui por meio do seu próprio provedor de VoIP. Este guia apresenta o fluxo em três etapas: 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): uma configuração guiada da Telnyx que orienta a criação de conta e as chaves de API, uma opção para conectar uma conta existente e um formulário SIP manual com um gerador de guia de configuração com IA.

Provedores compatíveis

Provedor	ID `provider`	Observações
Twilio	`twilio`	Chave de API + segredo
Telnyx	`telnyx`	Chave de API; integração guiada disponível (`setup_method: guided_telnyx`)
SignalWire	`signalwire`	Em breve — conecte via SIP manual hoje
Vonage	`vonage`	Em breve — conecte via SIP manual hoje
SIP manual	`manual`	Qualquer tronco SIP — use sua própria configuração

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

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

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 do lado do provedor (atribuição de tronco, lista de IPs permitidos, autorização de chamadas 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 são armazenadas no servidor e nunca retornadas em texto simples por solicitações GET subsequentes — para fazer a rotação, execute um novo test e faça PATCH com a nova evidência.

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 source="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 de ida e volta (verificação de discagem de entrada + teste de autorização de saída).

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 entra em status="active". Em caso de falha, a resposta informa o que falhou — corrija (geralmente uma atribuição de tronco ausente no painel do provedor) e chame novamente.

5. Atribua agentes e faça uma chamada

Com o número verificado, atribua agentes de entrada / saída da mesma forma que para um número de demonstração. Consulte Gerenciar chamadas de entrada e Realizar chamadas de saída.

Rotação de credenciais

Quando uma chave do 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 reimportar os números.

Próximas etapas

Referência de conexões VoIP

Todos os campos nas respostas de conexão, evidência e importação.

Referência de números de telefone

Atribua agentes, transfira entre organizações, libere números.

Realizar chamadas de saída

Agora que o número é seu, comece a realizar chamadas de saída.

Getting Started

Using the dashboard

Connect tools & data

Analyze & improve

Team & account

Developer cookbook

Operations

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

Provedores compatíveis

1. Teste as credenciais

2. Crie a conexão

3. Liste e importe números

4. Verifique cada número importado

5. Atribua agentes e faça uma chamada

Rotação de credenciais

Próximas etapas

Referência de conexões VoIP

Referência de números de telefone

Realizar chamadas de saída

​Provedores compatíveis

​1. Teste as credenciais

​2. Crie a conexão

​3. Liste e importe números

​4. Verifique cada número importado

​5. Atribua agentes e faça uma chamada

​Rotação de credenciais

​Próximas etapas

Referência de conexões VoIP

Referência de números de telefone

Realizar chamadas de saída

Provedores compatíveis

1. Teste as credenciais

2. Crie a conexão

3. Liste e importe números

4. Verifique cada número importado

5. Atribua agentes e faça uma chamada

Rotação de credenciais

Próximas etapas