Skip to main content
De forma predeterminada, cada número de teléfono y clave publicable tiene asignado un agente estático. Cuando necesites personalización por quien llama o por visitante — enrutamiento VIP, contexto de usuarios con sesión iniciada, pruebas A/B de prompts — cambia al modo webhook y deja que tu servidor decida.

Cómo funciona

  1. Suscríbete al evento telephony.incoming (teléfono) o web.incoming (widget). Ambos son webhooks bloqueantes: ThunderPhone espera hasta 10 segundos tu respuesta antes de continuar la llamada.
  2. 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).
  3. Tu servidor responde con una configuración de agente (prompt, voz, producto, herramientas). ThunderPhone usa esa configuración para la llamada.
  4. 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

Para números de teléfono, suscribe tu endpoint a telephony.incoming:
La respuesta incluye un 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ún new 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.