--- title: "Realiza llamadas salientes (API)" description: "Inicia una llamada saliente impulsada por IA desde tu propio código: flujos de encuestas, seguimiento o confirmación." --- Las llamadas salientes te permiten proporcionar un número de destino y una configuración de agente a ThunderPhone para que la IA realice la llamada en tu nombre. Casos de uso habituales: - Confirmaciones de citas - Llamadas de seguimiento de encuestas - Seguimientos de "segundo intento" tras una llamada perdida - Notificaciones de tipo despacho ¿Llamas a una lista completa? La función [**Campañas**](/es/guides/outbound-campaigns) del dashboard (`/dashboard/campaigns`) recibe un CSV de contactos y gestiona por ti las ventanas de llamada según la zona horaria, la simultaneidad y la política de reintentos. Esta guía cubre llamadas programáticas individuales. ## Requisitos previos Usa un número que poseas mediante una [conexión VoIP](/api-reference/voip-connections), o solicita permiso para usar tus números de ThunderPhone para llamadas salientes desde la página Números de teléfono. Los números de ThunderPhone comienzan siendo solo para llamadas entrantes. ThunderPhone revisa cada solicitud manualmente; una vez aprobados, esos números pueden realizar llamadas hasta el límite diario aprobado (que se restablece a las 00:00 UTC) y ejecutar campañas, y tú puedes solicitar un límite mayor. Los números VoIP del cliente no tienen límite diario, por lo que los recomendamos para llamadas salientes. Consulta [Usa tus propios números](/es/guides/bring-your-own-numbers). Un prompt orientado a llamadas salientes suele comenzar con el agente identificándose y explicando su propósito: "Hola, habla Acme para confirmar su cita de mañana a las 3 p. m.…" Configura `outbound_speak_order` como `agent_first` (el valor predeterminado). Las llamadas salientes devuelven `402 Payment Required` si el saldo es ≤ `$0.00`. Recarga saldo o activa la recarga automática en **Organización → Configuración de facturación** en el panel. Tu clave `sk_live_` puede consultar el saldo con [`GET /v1/billing`](/api-reference/billing#get-billing-account), pero no puede recargar saldo ni cambiar la recarga automática. ## Realiza una llamada con un agente guardado La forma más sencilla: referencia un agente por ID: ```bash curl -X POST https://api.thunderphone.com/v1/call \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "from_number": "+15551234567", "to_number": "+14155552671", "agent_id": 12 }' ``` Respuesta: ```json { "call_id": 987654321, "status": "initiated" } ``` `status: "initiated"` solo significa que la solicitud fue aceptada: la llamada **aún no está conectada**. Consulta periódicamente [`GET /v1/calls/{call_id}`](/api-reference/calls#retrieve-a-call) para ver el estado en tiempo real (`in_progress` → `completed` / `failed`). ## Realiza una llamada con configuración en línea Si quieres un prompt puntual que no vale la pena guardar como agente, pasa `config` en su lugar. La estructura coincide con el esquema de respuesta del [webhook `call.incoming`](/es/webhooks/call-incoming): ```bash curl -X POST https://api.thunderphone.com/v1/call \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "from_number": "+15551234567", "to_number": "+14155552671", "config": { "prompt": "You are confirming Jane Doe appointment for 3pm tomorrow…", "voice": "john", "product": "spark" } }' ``` ## Sigue la llamada En paralelo, suscríbete al [webhook `telephony.complete`](/es/webhooks/events): la forma más rápida de saber que una llamada terminó. Si no puedes aceptar webhooks entrantes, consulta `GET /v1/calls/{call_id}` cada pocos segundos; el registro incluye `end_reason`, `duration_seconds` y la URL de la grabación cuando termina la llamada. Si tu agente está configurado para extraer datos estructurados después de la llamada, esos datos se entregan por separado una vez que finaliza el procesamiento. ### Pasa variables por llamada a un agente guardado Los agentes guardados pueden usar marcadores de posición como `{{name}}` o `{{name|there}}` en el texto del prompt. Cuando realizas una llamada saliente con `agent_id`, pasa `variables` con los valores para esa llamada: ```json { "from_number": "+[REDACTED_PHONE]", "to_number": "+[REDACTED_PHONE]", "agent_id": 12, "variables": { "name": "Jordan" } } ``` Usa valores de cadena con el nombre del marcador de posición como clave. Estas variables se aplican a los agentes guardados; el ejemplo de `config` en línea de esta guía no las usa. ## Modos de falla que conviene manejar | Error | Solución | |-------|-----| | `402 Payment Required` | Recarga el saldo o habilita la recarga automática | | `400` con `code: destination_not_allowed` | ThunderPhone no llama a ese número: números inválidos, números de emergencia, números con tarifa premium, códigos cortos o países sancionados. Desde números de ThunderPhone, solo números ordinarios de EE. UU. y Canadá (sin tarifa premium). `reason` indica cuál; consulta [destinos bloqueados](/api-reference/outbound-calls#blocked-destinations) | | `409` con `retryable: false` para un número de ThunderPhone | Sigue el `code`: solicita llamadas salientes en la página Números de teléfono, espera una revisión pendiente o usa otro número elegible | | `429` con `code: platform_outbound_daily_limit_reached` | La organización agotó las llamadas salientes de hoy desde números de ThunderPhone. Espera a `resets_at` (00:00 UTC), solicita un límite mayor en la página Números de teléfono o llama desde un número en tu propia conexión VoIP | | `429` con `code: concurrent_call_limit_reached` | La organización tiene tantas llamadas en curso como su [límite de llamadas simultáneas](/api-reference/introduction#call-limits) (20 de forma predeterminada, contando llamadas entrantes, salientes, web y de prueba). Vuelve a intentarlo después de los segundos indicados en el encabezado `Retry-After` o cuando termine una llamada; envía un correo a support@thunderphone.com para aumentar el límite | | `429` con `code: same_number_too_soon` | Llamaste al mismo `to_number` hace menos de 10 segundos. Vuelve a intentarlo después de los segundos indicados en el encabezado `Retry-After` | | `409` con `retryable: false` para un número VoIP del cliente | Corrige el estado indicado por `code`; ante errores de verificación, ejecuta [`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number) | | Conflicto de idempotencia `409` | Reutiliza la clave solo con la solicitud normalizada original o envía una clave nueva | | `404 from_number is not registered to this organization` | Confirma que `from_number` coincida con un número de teléfono activo en tu organización. Un número que ya está en aprovisionamiento, falló, está en proceso de liberación o fue liberado también devuelve esta respuesta | | `500` solo con un campo `detail` | No hay ningún troncal saliente configurado. Contacta con soporte; no es un problema de estado del número que puedas corregir | | `502 Bad Gateway` | Error transitorio de SIP / LiveKit; es seguro volver a intentarlo | Consulta la [referencia de llamadas salientes](/api-reference/outbound-calls#error-responses) para ver la lista completa y estable de códigos de elegibilidad, así como ambas formas de respuesta `409`. Si un número activo deja de ser elegible después de que se acepta la solicitud, pero antes de realizar la llamada, la verificación final devuelve la carga útil `409` no reintentable. ## Control del tiempo en espera Las llamadas salientes que se prolongan porque la persona que recibe la llamada tarda en responder (árboles de IVR, colas) se pueden limitar con `max_hold_seconds`: ```json { "from_number": "+15551234567", "to_number": "+14155552671", "agent_id": 12, "max_hold_seconds": 120 } ``` El agente cuelga si no se ha recibido audio humano en los últimos N segundos. El valor predeterminado es 900 segundos (15 minutos). --- ## Próximos pasos Todos los campos de solicitud y códigos de error. Envía llamadas salientes finalizadas a tu sistema en tiempo real. Recarga automática para que las llamadas salientes nunca fallen por saldo. Haz una prueba en seco de tu agente saliente antes de producción.