--- title: "Usa tus propios números (VoIP, API)" description: "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**. El panel tiene una versión guiada de todo este flujo en **Conexiones → VoIP** (`/dashboard/voip-connections`): primero, una ruta para conectar una cuenta existente (Twilio y Telnyx mediante clave de API; SignalWire, Vonage, Plivo y cualquier otro troncal mediante el formulario SIP manual con pasos específicos del proveedor y un generador de guías de configuración con IA), y después, una configuración guiada que abre una nueva cuenta de Telnyx. ## Proveedores compatibles | Proveedor | ID de `provider` | Notas | |----------|---------------|-------| | Twilio | `twilio` | SID de cuenta + token de autenticación; una conexión por cuenta o subcuenta de Twilio (consulta [subcuentas de Twilio](#twilio-subaccounts)) | | Telnyx | `telnyx` | Clave de API; incorporación guiada disponible (`setup_method: guided_telnyx`) | | SignalWire | `signalwire` | Sin conexión nativa de proveedor; conéctalo como `manual` con el ajuste preestablecido de SIP de SignalWire | | Vonage | `vonage` | Sin conexión nativa de proveedor; conéctalo como `manual` con el ajuste preestablecido de SIP de Vonage | | SIP manual | `manual` | Cualquier troncal SIP, incluidos SignalWire, Vonage y Plivo. Si comienzas desde una de esas tarjetas de proveedor en el dashboard, la conexión sigue siendo `manual` y guarda la elección en `sip_config.preset` (`signalwire`, `vonage` o `plivo`) | ## 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. ```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 } } ``` 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: ```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..." }' ``` La respuesta es un [objeto VoipConnection](/api-reference/voip-connections#connection-object) 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: ```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..."]}' ``` 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: ```bash curl https://api.thunderphone.com/v1/voip-connections/5/available-numbers \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" ``` Luego importa los que quieras: ```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 importación se convierte en un [recurso de número de teléfono](/api-reference/phone-numbers) 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. ```bash 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](/es/guides/handle-inbound-calls) y [Realizar llamadas salientes](/es/guides/place-outbound-calls). ## Rotación de credenciales Cuando se rota una clave del proveedor, vuelve a ejecutar el flujo de probar y actualizar: ```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" }' ``` La conexión se mantiene activa; no necesitas volver a importar los números. --- ## Próximos pasos Todos los campos de las respuestas de conexión, evidencia e importación. Asigna agentes, transfiere entre organizaciones y libera números. Ahora que tienes el número, comienza a realizar llamadas salientes.