Realiza llamadas salientes (API)

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

Requisitos previos#

1. Elige un número habilitado para llamadas salientes

   Usa un número que poseas mediante una conexión VoIP, 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.

2. Crea un agente

   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).

3. Mantén un saldo positivo

   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, 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:

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:

{ "call_id": 987654321, "status": "initiated" }

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:

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

{
  "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#

Consulta la referencia de llamadas salientes 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:

{
  "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#