> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Traga seus próprios números (VoIP, API)
> Conecte o Twilio ou o Telnyx — ou qualquer tronco SIP — e importe números de telefone da sua conta existente.
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.
```bash theme={null}
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 theme={null}
{
"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:
```bash theme={null}
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 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:
```bash theme={null}
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 theme={null}
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 `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).
```bash theme={null}
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](/pt/guides/handle-inbound-calls) e
[Realizar chamadas de saída](/pt/guides/place-outbound-calls).
## Rotação de credenciais
Quando uma chave do provedor for rotacionada, execute novamente o fluxo de testar e atualizar:
```bash theme={null}
# 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
Todos os campos nas respostas de conexão, evidência e importação.
Atribua agentes, transfira entre organizações, libere números.
Agora que o número é seu, comece a realizar chamadas de saída.