Developer cookbook

Realiza llamadas salientes (API)

Activa 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" después de una llamada perdida
• Notificaciones de tipo despacho

Requisitos previos#

1. Usa un número de VoIP

   Las llamadas salientes requieren que tengas el from_number mediante una conexión de VoIP. Los números de demostración son solo para llamadas entrantes. 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, le 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 mediante POST /v1/billing/top-up o activa 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":   "+14155550199",
    "agent_id":    12
  }'

Respuesta:

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

Realiza una llamada con configuración en línea#

Si quieres un prompt único 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":   "+14155550199",
    "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 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 una vez que termina la llamada.

Errores que vale la pena controlar#

Control del tiempo en espera#

Las llamadas salientes que se prolongan porque la persona que recibe la llamada tarda en responder (árboles IVR, colas) se pueden limitar con max_hold_seconds:

{
  "from_number": "+15551234567",
  "to_number":   "+14155550199",
  "agent_id":    12,
  "max_hold_seconds": 120
}

El agente cuelga si no ha recibido audio humano en los últimos N segundos. El valor predeterminado es 900 (15 minutos).

Próximos pasos#