Usa tus propios números (VoIP, API)

Conecta Twilio, Telnyx, SignalWire, Vonage, Plivo y cualquier otro troncal SIP mediante SIP, importa los números de teléfono que ya tienes y permite que los agentes de ThunderPhone respondan y hagan llamadas con ellos.

Los números aprobados de ThunderPhone pueden realizar llamadas salientes y ejecutar campañas. Si prefieres usar números propios a través de tu propio proveedor de VoIP, esta guía te acompaña por el flujo de conexión: probar credenciales → crear conexión → importar números → verificar.

Proveedores compatibles#

1. Probar credenciales#

Antes de crear una conexión de VoIP persistente, verifica las credenciales del proveedor para confirmar que funcionan. Esto devuelve un verification_evidence_id que pasas al paso de creación para que las credenciales no se cobren dos veces durante 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" }
  }'

{
  "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. Crea 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 del lado del servidor y nunca se devuelven en texto sin formato en solicitudes GET posteriores; para rotarlas, ejecuta un test nuevo y usa PATCH con la nueva evidencia.

Subcuentas de Twilio#

Una conexión de Twilio está vinculada a la única cuenta de Twilio cuyas Account SID y Auth Token contiene. Twilio mantiene los números de teléfono y los troncales SIP dentro de cada subcuenta, por lo que una conexión creada con la cuenta principal solo ve los números propios de la cuenta principal, y una conexión existente no se puede cambiar posteriormente a una subcuenta diferente.

Para acceder a números de subcuentas, crea una conexión por subcuenta. El dashboard lo hace por ti: cuando conectas una cuenta principal que tiene subcuentas activas, el diálogo de configuración las muestra, tú seleccionas las que quieres y ThunderPhone crea una conexión (y un trunk SIP) en cada una. El mismo flujo está disponible mediante la 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..."]}'

La respuesta incluye una fila por cada subcuenta con un status de created, skipped (ya conectada) o failed, además de un error sobre el que puedes actuar. Las filas son independientes, por lo que un error en una subcuenta nunca bloquea las demás, y un discovery_id sigue siendo válido durante 30 minutos, por lo que puedes simplemente volver a intentar una fila que falló. Los tokens de las subcuentas se leen de Twilio durante el descubrimiento y se almacenan en la nueva conexión; nunca se devuelven mediante la API. Luego, cada nueva conexión importa y verifica números exactamente igual que una conexión que creaste manualmente. Agrega "enable_transfers": true para activar también las transferencias de llamadas en el troncal SIP de cada nueva conexión; un error en ese proceso se informa en el test_result.transfer_enable_error de esa conexión y no hace fallar la fila.

3. Lista e importa 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 de teléfono en tu organización con number_type="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 verificación. Para las conexiones de proveedores (Twilio, Telnyx), esto vuelve a comprobar las credenciales del proveedor y la conectividad SIP. Para una conexión SIP manual, primero intenta una autollamada de bucle: ThunderPhone realiza una breve llamada de prueba desde el número, a través de tu troncal SIP, de vuelta al mismo número. Si eso no verifica la ruta entrante, recurre a una breve llamada de prueba desde el número, a través de tu troncal SIP, hacia un número de ThunderPhone. Estas pruebas verifican el nombre de usuario, la contraseña, el transporte, el enrutamiento saliente y la entrega entrante de la troncal. Tu operador factura estas llamadas como cualquier otra.

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

Cuando tiene éxito, voip_verification_status cambia a verified y el número pasa a status="active". Un número de su propia cuenta de Telnyx sigue recibiendo llamadas entrantes cuando falla su llamada de prueba o las llamadas salientes aún no están configuradas: pasa a status="active" con voip_verification_status establecido en unverified, y la respuesta indica el motivo. Cuando falla, la respuesta detalla qué falló —para un troncal manual, es la respuesta SIP del operador, por ejemplo "rechazó las credenciales de ThunderPhone (SIP 401)" o "no se pudo enrutar una llamada (SIP 404)"—; corríjalo (credenciales, IP de origen permitidas, una asignación de troncal faltante en el panel del proveedor) y vuelva a intentarlo.

Para una conexión SIP manual incluida en una lista de permitidos, la prueba de llamadas entrantes también falla si esas IP de origen permitidas bloquearían una llamada entrante real.

5. Asigna agentes y realiza una llamada#

Una vez verificado el número, asigna agentes de entrada o salida de la misma forma que con un número de ThunderPhone. Consulta Gestionar llamadas entrantes y Realizar llamadas salientes.

Rotación de credenciales#

Cuando se rota una clave del proveedor, vuelve a ejecutar el flujo de probar y actualizar:

# 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 activa; no necesitas volver a importar los números.

Próximos pasos#