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

<Note>
  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),
  além de fluxos de reconexão para logins de operadoras expirados e uma
  configuração guiada que abre uma nova conta Telnyx.
</Note>

## 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"`.

### Mantenha seu próprio roteamento de chamadas

No Twilio, a importação coloca o número no tronco SIP do ThunderPhone na sua
conta; no Telnyx, ela atribui o número à conexão SIP do ThunderPhone.
De qualquer forma, cada chamada vai direto para o seu agente.

Para rotear chamadas por conta própria (por exemplo, chamar uma pessoa primeiro e enviar
a chamada ao agente apenas se ela não atender), altere as configurações de voz do número
no seu provedor após a importação ou importe pela API com
`"call_routing": "customer"` para que o ThunderPhone não as altere.
O ThunderPhone nunca as altera de volta. Para que o agente atenda, envie a
chamada para o endereço SIP do número:

```xml
<Response>
  <Dial>
    <Sip>sip:+15550001234@sip.thunderphone.com</Sip>
  </Dial>
</Response>
```

O envio de mensagens de texto pelo número funciona da mesma forma em ambos os casos. O teste de
chamada recebida liga para o número, portanto ele chega a quem quer que seu roteamento envie as chamadas
primeiro.

### Mover um número entre conexões

Importar um número que já está em outra das suas conexões o move
para a nova, junto com seus agentes e histórico. Um número que uma conexão do Twilio ou
Telnyx envia para o ThunderPhone precisa ser removido dessa
conexão primeiro, pois seu provedor continuaria enviando chamadas para lá.

## 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. Se você usar IPs de relay do ThunderPhone na sua lista de permissões, inclua todos os IPs de relay que o ThunderPhone fornecer para sua configuração.

## 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 reimportar os números. No fluxo de reconexão do dashboard, você pode inserir com segurança a nova chave da operadora sem substituir todo o objeto de credenciais armazenado em texto simples.

---

## Próximas etapas

<CardGroup cols={2}>
  <Card title="Referência de conexões VoIP" icon="phone-volume" href="/api-reference/voip-connections">
    Todos os campos nas respostas de conexão, evidência e importação.
  </Card>
  <Card title="Referência de números de telefone" icon="phone" href="/api-reference/phone-numbers">
    Atribua agentes, transfira entre organizações, libere números.
  </Card>
  <Card title="Realizar chamadas de saída" icon="arrow-up-right" href="/pt/guides/place-outbound-calls">
    Agora que você tem o número, comece a realizar chamadas de saída.
  </Card>
</CardGroup>
