--- title: "Conéctate por SIP (sin número de teléfono)" description: "Envía llamadas a un agente de voz de ThunderPhone directamente desde tu PBX, operador o aplicación SIP, con una URI SIP de un solo uso por llamada o una dirección SIP permanente." --- Si tu propio sistema ya gestiona números de teléfono (una PBX, una plataforma de centro de contacto o una cuenta de operador donde rotas números), puedes enviar llamadas a un agente de ThunderPhone mediante SIP estándar. No importas ni compras un número en ThunderPhone. Tu sistema marca una dirección SIP y el agente responde. Hay dos tipos de dirección SIP: | | **URI SIP por llamada** | **Endpoint SIP** | |---|---|---| | Tiene este aspecto | `sip:c-@sip.thunderphone.com` | `sip:agent--@sip.thunderphone.com` | | Se crea con | `POST /v1/calls/register-sip`, una vez por llamada | `POST /v1/sip-endpoints`, una vez | | Autenticación | El token de un solo uso en la dirección | Nombre de usuario y contraseña de resumen SIP (y, opcionalmente, una lista de permitidos de IP de origen) | | Ideal para | Apps que ya llaman a una API antes de transferir una llamada; variables por llamada | PBX y operadores que simplemente deben "apuntar un troncal" a ThunderPhone | | Válido durante | 5 minutos, una llamada | Hasta que lo elimines | Ambos tipos se enrutan a un agente de tu organización y ambos aparecen en el historial de llamadas como cualquier otra llamada entrante. ## URI SIP por llamada ### 1. Registra la llamada ```bash curl -X POST https://api.thunderphone.com/v1/calls/register-sip \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "agent_id": 12, "to_number": "+14155550142", "variables": {"customer_name": "Ada"} }' ``` ```json { "call_id": 862197007562, "sip_uri": "sip:c-1790372992.Qm3xT8vLk2PzR7nYw4HbJa.uF6sD1gK9eW2cX5vB8nM0q@sip.thunderphone.com", "expires_at": "2026-09-25T21:49:52Z", "agent_id": 12, "to_number": "+14155550142" } ``` - `to_number` (opcional) es el número que quien llama marcó de tu lado. Se almacena como el destino de la llamada en el historial de llamadas, y el agente lo ve como su propio número. - `variables` (opcional) completa los `{{placeholders}}` en el prompt del agente, de la misma forma que para las [llamadas salientes](/es/guides/call-variables). - `call_id` es el ID que tendrá la llamada en el historial de llamadas (`GET /v1/calls/{call_id}`) cuando se conecte. ### 2. Marca el URI Envía la llamada a `sip_uri` en un plazo de 5 minutos. El URI funciona para una sola llamada: una vez que una llamada lo ha usado, queda consumido, incluso si esa llamada termina rápidamente. Con Twilio, por ejemplo, devuelve este TwiML para la llamada que quieres transferir: ```xml sip:c-1790372992.Qm3xT8vLk2PzR7nYw4HbJa.uF6sD1gK9eW2cX5vB8nM0q@sip.thunderphone.com;transport=tcp ``` Desde una PBX, marca el URI como destino SIP. No se necesita nombre de usuario ni contraseña; el token es la credencial, así que trata el URI como una contraseña hasta que se haya usado. ## Punto de conexión SIP (dirección permanente) ### 1. Crea el punto de conexión ```bash curl -X POST https://api.thunderphone.com/v1/sip-endpoints \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"agent_id": 12, "name": "Main PBX"}' ``` ```json { "id": 7, "name": "Main PBX", "agent_id": 12, "sip_uri": "sip:agent-12-jhxmginwjx@sip.thunderphone.com", "username": "tp409667538f83", "password": "8mJ0…", "allowed_source_cidrs": [], "status": "active", "created_at": "2026-09-25T21:46:18Z" } ``` La `password` se devuelve solo una vez, cuando se crea el punto de conexión. Guárdala de inmediato en la configuración de tu PBX o proveedor. Si la pierdes, rótala con `POST /v1/sip-endpoints/{id}/rotate-password`. ### 2. Configura tu sistema para usarlo Configura un troncal o destino SIP con: | Configuración | Valor | |---|---| | URI SIP | el `sip_uri` del punto de conexión | | Nombre de usuario / contraseña | `username` / `password` (autenticación digest; ThunderPhone desafía cada llamada) | | Transporte | TCP en el puerto 5060 o TLS en el puerto 5061 (recomendado), o UDP en el puerto 5060 | | Códecs | G.711 (PCMU/PCMA) o G.722 | Prefiere TCP o TLS. UDP funciona desde direcciones públicas y desde la mayoría de los NAT, pero detrás de un NAT "simétrico" (uno que usa un puerto nuevo para cada destino), las desconexiones y transferencias del agente podrían no llegar a tu sistema. Una lista de permitidos de IP de origen (a continuación) también requiere TCP o TLS. Mediante TLS, la señalización SIP permanece cifrada incluso después de `sip.thunderphone.com`, hasta los servidores que gestionan la llamada. Estas configuraciones de transporte y códec también se aplican a las URI por llamada. Dos detalles de red son importantes para ambos tipos de dirección: - **Sigue Record-Route.** Después del primer INVITE, el resto de la señalización de la llamada (ACK, desconexión, transferencias) se dirige al servidor específico de ThunderPhone que respondió, cuyo nombre aparece en el encabezado `Record-Route` (`sip-1.thunderphone.com` o `sip-2.thunderphone.com`, o su dirección IP). Si restringes el SIP saliente, permite esos hosts además de `sip.thunderphone.com`: `172.170.39.202` (`sip`), `13.86.104.121` (`sip-1`) y `20.80.98.90` (`sip-2`). - **El audio va a otro lugar.** `sip.thunderphone.com` transporta solo señalización. Permite el tráfico multimedia (RTP) hacia las direcciones y puertos de la respuesta SDP. Cada llamada a la dirección llega al agente del punto de conexión, sin importar qué número marque quien llama en tu lado. Nunca importas números, por lo que rotarlos en tu lado no requiere ningún cambio en ThunderPhone. ### Pasa el número marcado (opcional) Para registrar cuál de tus números marcó quien llama, envíalo en el INVITE en un encabezado `X-Original-To` (por ejemplo, `X-Original-To: +14155550142`) o en un encabezado estándar `Diversion`. ThunderPhone lo almacena como el destino de la llamada. El destino se elige en este orden: el `to_number` proporcionado al registrar una URI por llamada, luego un número en `X-Original-To`, luego uno en `Diversion`. Si ninguno proporciona un número, se muestra como `sip:agent-12-jhxmginwjx` (la dirección del punto de conexión) para un punto de conexión, o como `sip:call` para una URI por llamada. Con Twilio puedes agregar el encabezado a la URI SIP: `sip:agent-12-jhxmginwjx@sip.thunderphone.com;transport=tcp?X-Original-To=%2B14155550142`. ### Restringe las IP de origen (opcional) Configura `allowed_source_cidrs` para aceptar llamadas solo desde tus propias direcciones de señalización, además del nombre de usuario y la contraseña: ```bash curl -X PATCH https://api.thunderphone.com/v1/sip-endpoints/7 \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"allowed_source_cidrs": ["203.0.113.0/28"]}' ``` Las llamadas desde cualquier otra dirección se rechazan antes de llegar al agente. Usa las direcciones desde las que tu sistema envía señalización SIP (para un proveedor como Twilio, sus rangos de IP de señalización publicados), no tus direcciones multimedia. La lista de permitidos se verifica solo para llamadas mediante TCP o TLS. Una dirección de origen UDP puede falsificarse, por lo que un punto de conexión con una lista de permitidos rechaza todas las llamadas que lleguen mediante UDP. Envía las llamadas con `;transport=tcp` (puerto 5060) o mediante TLS (puerto 5061). ## Lo que ven quienes llaman y tu sistema - **ID de quien llama:** la parte de usuario del encabezado `From` se almacena como quien llama. Un número telefónico (dígitos, opcionalmente con `+`, espacios, guiones, puntos o paréntesis) se normaliza a E.164; cualquier otro valor, como un nombre de usuario SIP, se conserva tal como se envió. Se conservan como máximo 32 caracteres, y la ausencia de quien llama se almacena como `anonymous`. - **Llamadas rechazadas:** una URI por llamada desconocida o vencida recibe SIP `404 Not Found`. Una URI por llamada ya utilizada, un punto de conexión deshabilitado o una fuente fuera de la lista de permitidos (incluida cualquier llamada UDP a un punto de conexión con una lista de permitidos) se desconecta antes de que se inicie el agente: tu sistema puede ver que la llamada falla, o que se conecta y termina de inmediato. Estos rechazos no crean una entrada en el historial de llamadas. Si tu organización se queda sin crédito o ha alcanzado su límite de gasto, la llamada se rechaza y aparece en el historial de llamadas como una llamada fallida sin cargo. Para volver a intentar un intento por llamada, registra una URI nueva. - **Transferencias:** las transferencias en frío del agente funcionan (ThunderPhone envía un SIP `REFER`, que tu sistema debe aceptar). Las transferencias asistidas no están disponibles en llamadas a direcciones SIP, porque no hay un número de ThunderPhone que mostrar como ID de quien llama para el segundo tramo. Con Twilio, el TwiML anterior conecta al agente, pero no gestiona las transferencias: agrega `referUrl="https://YOUR_SERVER/sip-transfer"` al ``, y haz que ese webhook lea `ReferTransferTarget` y devuelva TwiML que marque el destino de la transferencia (consulta la [guía SIP REFER de Twilio](https://www.twilio.com/docs/voice/api/refer-to-twilio)). - **Mensajes de texto:** la dirección SIP y el número marcado no pueden enviar mensajes de texto. El agente puede enviar mensajes de texto durante una llamada a una dirección SIP solo si tiene un número independiente con capacidad de SMS configurado para mensajes de texto; de lo contrario, su herramienta de SMS no está disponible. - **Registro:** ThunderPhone no acepta SIP `REGISTER`. Envía llamadas a la dirección; no te registres en ella. ## Precios Las llamadas a direcciones SIP se facturan a la tarifa normal por minuto del agente. No hay cargo por número telefónico, porque ningún número de ThunderPhone gestiona la llamada. Tu propio operador factura su parte de la llamada como de costumbre. Consulta [Precios](/es/guides/pricing). ## Pruébalo 1. Crea una URI por llamada o un punto de conexión como se indicó arriba. 2. Márcalo desde tu sistema o desde cualquier softphone SIP (para un punto de conexión, ingresa el nombre de usuario y la contraseña). 3. Después de colgar, abre la llamada en **Llamadas** en el panel, o recupérala con `GET /v1/calls/{call_id}`. Muestra a quien llama, el destino (consulta el orden en «Pasa el número marcado») y la transcripción. Detalles de la API: [referencia de la API de direcciones SIP](/api-reference/sip-addresses).