Skip to main content
Cuando una llamada telefónica entrante llega a un número sin un agente asignado, o una sesión de widget web comienza con una clave publicable en mode="webhook", ThunderPhone envía una solicitud bloqueante telephony.incoming / web.incoming a tu URL de webhook heredada y espera hasta 10 segundos una respuesta de configuración. Usa este intercambio para elegir dinámicamente un prompt, una voz y herramientas por llamada: consulta la guía de configuración dinámica de llamadas para conocer el patrón integral.
Los endpoints de webhook suscritos también reciben telephony.incoming / web.incoming — para cada llamada entrante y sesión web, con agente configurado o no — pero esas entregas son notificaciones que se envían sin esperar respuesta con un event_id, nunca bloqueantes. Solo el webhook heredado de URL única incluye el intercambio de configuración de esta página. Las estructuras de las notificaciones de endpoints están en el catálogo de eventos.
El intercambio bloqueante no tiene alternativa: si tu controlador devuelve un estado que no es 2xx, agota el tiempo de espera o devuelve una configuración que no supera la validación, la llamada se rechaza (la llamada telefónica no se conecta; la solicitud de sesión del widget falla con 502/422). Responde rápido: quien llama está oyendo el tono de espera mientras decides.

Carga útil de la solicitud

Para llamadas telefónicas (telephony.incoming):
Para las sesiones de widget web (web.incoming), data identifica la página donde está integrado en lugar de los números telefónicos:
Los widgets en modo webhook entregan esta solicitud a la propia webhook_url de la clave publicable cuando está configurada, y recurren a la URL de webhook de la organización en caso contrario. En ambos casos, se firma con el secret del webhook de la organización.

Esquema de respuesta

Devuelve un objeto JSON que describa la configuración del agente para esta llamada. prompt y voice son obligatorios; todo lo demás es opcional.
Las claves de nivel superior desconocidas se ignoran silenciosamente; un nombre de campo con error tipográfico no rechaza la configuración, simplemente no se aplica. El orden de habla y max_hold_seconds no se aceptan aquí; solo se pueden configurar en el Agente.
Como prompt y voice son obligatorios, devolver {} o cualquier respuesta que no supere la validación rechaza la llamada con 422; no hay un agente estático alternativo en esta ruta (un número o clave en modo webhook no tiene un agente asignado).

Controlador de ejemplo


Respuesta con herramientas de función

Adjunta herramientas para que la IA pueda llamar a tus APIs durante la conversación:
Las solicitudes al endpoint de herramientas se firman con el mismo secreto de webhook de la organización que firmó este intercambio. Consulta Herramientas de función para ver la estructura exacta y el formato de solicitud firmada.

Guía rápida de niveles de producto


Relacionado

telephony.complete / web.complete

El evento de finalización de llamada que no bloquea.

Herramientas de función

Esquema JSON completo para tools[] y el contrato de endpoint firmado.

Endpoints de webhook

Suscribe varias URL a telephony.incoming / web.incoming.

Configuración dinámica de llamadas

Patrones para prompts, herramientas y pruebas A/B por cada persona que llama.