Usa tus propios números (VoIP, API)

Los números de demostración son adecuados para crear prototipos, pero el tráfico de producción debe usar números que posees a través de tu propio proveedor de VoIP. Esta guía te muestra el flujo de tres pasos: probar credenciales → crear conexión → importar números → verificar.

El panel tiene un recorrido guiado de todo este flujo en Conexiones → VoIP (/dashboard/voip-connections): una configuración guiada de Telnyx que te acompaña en la creación de la cuenta y las claves de API, una ruta para conectar una cuenta existente y un formulario manual de SIP con un generador de guías de configuración con IA.

Proveedores compatibles

Proveedor	ID de `provider`	Notas
Twilio	`twilio`	Clave de API + secreto
Telnyx	`telnyx`	Clave de API; incorporación guiada disponible (`setup_method: guided_telnyx`)
SignalWire	`signalwire`	Próximamente — conéctate mediante SIP manual hoy
Vonage	`vonage`	Próximamente — conéctate mediante SIP manual hoy
SIP manual	`manual`	Cualquier troncal SIP — usa tu propia configuración

1. Probar las credenciales

Antes de crear una conexión VoIP persistente, prueba las credenciales del proveedor para confirmar que funcionan. Esto devuelve un verification_evidence_id que pasas al paso de creación para que no se cobren dos veces las credenciales por las pruebas.

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

Si alguna verificación falla, el status de la respuesta será fail y checks mostrará qué paso falló. Corrige la configuración del proveedor (asignación de troncal, lista de IP permitidas, autorización de llamadas salientes) y vuelve a intentarlo.

2. Crear la conexión

Pasa el verification_evidence_id que acabas de obtener:

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

La respuesta es un objeto VoipConnection con status="connected". Las credenciales se almacenan en el servidor y nunca se devuelven en texto sin formato mediante solicitudes GET posteriores; para rotarlas, ejecuta un nuevo test y PATCH con la nueva evidencia.

3. Listar e importar números

Revisa los números visibles para tus credenciales que aún no estén en una organización de ThunderPhone:

curl https://api.thunderphone.com/v1/voip-connections/5/available-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Luego importa los que quieras:

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 importación se convierte en un recurso de número telefónico en tu organización con source="voip" y status="provisioning".

4. Verifica cada número importado

La importación registra el número como disponible; para enrutar llamadas a través de él se necesita una verificación de ida y vuelta (comprobación de marcado entrante + sondeo de autorización saliente).

curl -X POST https://api.thunderphone.com/v1/phone-numbers/{id}/verify-voip \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Si se realiza correctamente, voip_verification_status cambia a verified y el número pasa a tener status="active". Si falla, la respuesta especifica qué falló; corrígelo (a menudo es una asignación de troncal faltante en el panel del proveedor) y vuelve a llamar.

5. Asigna agentes y atiende una llamada

Con el número verificado, asigna agentes entrantes/salientes de la misma forma que con un número de demostración. Consulta Gestionar llamadas entrantes y Realizar llamadas salientes.

Rotación de credenciales

Cuando se rota una clave de proveedor, vuelve a ejecutar el flujo de prueba y actualización:

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

La conexión se mantiene; no es necesario volver a importar los números.

Próximos pasos

Referencia de conexiones VoIP

Todos los campos de las respuestas de conexión, evidencia e importación.

Referencia de números telefónicos

Asigna agentes, transfiere entre organizaciones y libera números.

Realizar llamadas salientes

Ahora que eres propietario del número, comienza a realizar llamadas salientes.

Getting Started

Using the dashboard

Connect tools & data

Analyze & improve

Team & account

Developer cookbook

Operations

Usa tus propios números (VoIP, API)

Proveedores compatibles

1. Probar las credenciales

2. Crear la conexión

3. Listar e importar números

4. Verifica cada número importado

5. Asigna agentes y atiende una llamada

Rotación de credenciales

Próximos pasos

Referencia de conexiones VoIP

Referencia de números telefónicos

Realizar llamadas salientes

​Proveedores compatibles

​1. Probar las credenciales

​2. Crear la conexión

​3. Listar e importar números

​4. Verifica cada número importado

​5. Asigna agentes y atiende una llamada

​Rotación de credenciales

​Próximos pasos

Referencia de conexiones VoIP

Referencia de números telefónicos

Realizar llamadas salientes

Proveedores compatibles

1. Probar las credenciales

2. Crear la conexión

3. Listar e importar números

4. Verifica cada número importado

5. Asigna agentes y atiende una llamada

Rotación de credenciales

Próximos pasos