Cómo funciona
- Suscríbete al evento
telephony.incoming(teléfono) oweb.incoming(widget). Ambos son webhooks bloqueantes: ThunderPhone espera hasta 10 segundos tu respuesta antes de continuar la llamada. - ThunderPhone te envía
{call_id, from_number, to_number}(las sesiones del widget incluyen campos específicos del widget en lugar de números; consulta el esquema de solicitud). - Tu servidor responde con una configuración de agente (prompt, voz, producto, herramientas). ThunderPhone usa esa configuración para la llamada.
- Si devuelves
{}, se agota el tiempo de espera o ocurre un error, se usa como alternativa el agente asignado estáticamente. Una opción predeterminada segura.
Funciona de forma idéntica para llamadas telefónicas (
telephony.incoming) y sesiones
del widget (web.incoming), ya sea que se entreguen a un endpoint de webhook
o al webhook heredado de una sola URL.1. Configura el destino del webhook
- Llamadas telefónicas
- Widget web
Para números de teléfono, suscribe tu endpoint a La respuesta incluye un
telephony.incoming:secret de un solo uso; guárdalo, lo usarás
para verificar la firma.2. Implementa el controlador
Tres reglas generales:- Verifica la firma en cada solicitud (consulta Verificar firmas de webhooks). No omitas esto en desarrollo; hazlo bien una vez y reutilízalo.
- Responde rápido. Diez segundos es el límite estricto, y cada segundo es silencio para quien llama. Haz consultas a la base de datos si lo necesitas, pero no llames LLM posteriores de forma síncrona; si quieres generar prompts dinámicos, precalcúlalos y almacénalos en caché.
- Usa una alternativa limpia. Cualquier estado inesperado debe devolver
{}para que el agente asignado estáticamente gestione la llamada.
3. Esquema de respuesta
El cuerpo de la respuesta coincide exactamente con el esquema de respuesta de llamadas entrantes. Los campos más usados:El orden de habla por llamada y
max_hold_seconds no están disponibles en la
respuesta del webhook. Configúralos en el
Agente al que haces referencia.Patrones
Contexto de usuario con sesión iniciada
En los widgets en modo webhook, la página del visitante ya sabe quién es. Llama a tu webhook con un parámetro de cadena de consulta que el SDK del widget reenvía (?customer_id=123) y busca al cliente del lado del servidor.
Lanzamiento de prompts A/B
Antes de implementar esto manualmente, ten en cuenta que ThunderPhone cuenta con una función nativa de Experimentos (/dashboard/experiments y la pestaña A/B del generador de agentes) que
define variantes, divide el tráfico y compara los resultados por variante,
sin necesidad de webhook.
Si de todos modos necesitas control desde el webhook: aplica hash a call_id → grupo;
usa el prompt A para 0..49 y el prompt B para 50..99. Registra el
grupo que elegiste en tu propia base de datos y luego correlaciónalo con la calificación
de la llamada completada.
Enrutamiento según la hora
Horario comercial → agente de “soporte en vivo”; fuera de horario → agente de “tomar un mensaje”. Cambio simple segúnnew Date().getUTCHours() en tu controlador.
Próximos pasos
Referencia del webhook de llamadas entrantes
Esquemas exactos de solicitud y respuesta, incluida cada clave de configuración.
Verifica las firmas de webhook
Configura correctamente el HMAC una vez; reutilízalo en todas partes.
Crea una integración de herramientas
Combina el enrutamiento dinámico con herramientas por agente.
Semántica de entrega
Reintentos, orden, tiempos de espera.