Webhook durante la llamada
Con un webhook durante la llamada le das al asistente una «herramienta»: en cuanto quien llama pregunta algo que está en tu sistema, el asistente llama a tu endpoint e incorpora la respuesta a la conversación. Este artículo explica cómo configurar esa herramienta y qué datos se envían.
¿Cuándo se llama?
El asistente decide por su cuenta si necesita la herramienta, según lo que escribas en ¿Cuándo debe usar esto el asistente?. Por ejemplo: «Cuando quien llama pregunta por el estado de un pedido y menciona un número de pedido». Primero reúne los parámetros que marcaste como obligatorios (y los pide si quien llama aún no los ha dicho) y después hace la petición. En cuanto llega la respuesta, la conversación continúa.
Una misma conversación puede llamar a la herramienta varias veces, por ejemplo si quien llama menciona dos números de pedido. La herramienta funciona en todos los canales, así que también en SMS, WhatsApp y chat web.
Configuración
Para esto necesitas el rol Editor o Administrador.
- Abre el asistente en Asistentes, ve a la pestaña Tareas y despliega la tarjeta Acciones. Haz clic en Añadir nuevo y elige Petición HTTP.
- En Nombre, ponle a la acción un nombre claro (por ejemplo «Consultar estado del pedido») y en Cuándo, elige Durante la conversación.
- Elige el Método e introduce la URL de tu endpoint. Si tu sistema lo necesita, rellena también Cabeceras o una Clave de autorización.
- Deja vacía la Plantilla del cuerpo para enviar la petición predeterminada que ves más abajo, o crea tu propio cuerpo con
{{orderNumber}}. - En Parámetros que rellena el asistente, añade tus parámetros con Añadir variable: para cada uno, un nombre, un tipo y una descripción que le indique al modelo de IA qué debe rellenar.
- Rellena una Pista sobre la respuesta.
- Abajo del todo, rellena ¿Cuándo debe usar esto el asistente?.
Los cambios se guardan automáticamente en cuanto la acción tiene un nombre y una dirección web válida. En Probar, la petición solo se envía de verdad si Ejecutar las acciones de verdad está activado. Si no, el asistente recibe una respuesta simulada.
| Ajuste | Significado | Valor predeterminado |
|---|---|---|
| ¿Cuándo debe usar esto el asistente? | Cuándo usa el asistente la herramienta. Escríbelo como una frase para el modelo de IA. | Vacío: el asistente se guía entonces solo por el nombre de la acción |
| Parámetros que rellena el asistente | Los datos que el asistente saca de la conversación y envía. Para cada parámetro: nombre (letras, cifras y guiones bajos, con una letra como primer carácter), tipo (string, number, boolean), descripción y si es obligatorio. | Ninguno |
| Pista sobre la respuesta | Indicación para el modelo de IA sobre qué contiene tu respuesta y cómo usarla, por ejemplo «Di el estado y la fecha de entrega prevista con palabras sencillas. No menciones nombres internos de campos». | Vacía |
En una llamada, el asistente puede decir en pocas palabras que lo está comprobando mientras se ejecuta la petición.
Ejemplo de parámetro:
| Nombre | Tipo | Descripción |
|---|---|---|
orderNumber | string | El número de pedido que menciona quien llama, por ejemplo A-2231. Siempre una letra, un guion y cuatro cifras. |
Una buena descripción evita que el asistente confunda un código postal o un número de teléfono con un número de pedido.
La petición
De forma predeterminada enviamos un POST con JSON. Cada petición con cuerpo lleva la cabecera X-Yarla-Signature (consulta Webhooks). Una petición GET no lleva cuerpo y no se firma. En ese caso, pon los parámetros en la URL, por ejemplo https://api.ejemplo.es/pedidos/{{orderNumber}}.
Con la Plantilla del cuerpo vacía, los parámetros van como campos sueltos en un objeto JSON:
{ "orderNumber": "A-2231" }También pueden llegar datos que ya forman parte de la conversación, como campos del mismo nivel: por ejemplo, las variables de una campaña o de una llamada por API, el nombre en una llamada que inicias desde un contacto o el nombre de perfil de WhatsApp de un contacto desconocido. Ignora los campos que no reconozcas. Un parámetro que no es obligatorio y que el asistente no conoce llega como null o no aparece.
En tu propio cuerpo usas los parámetros como variables:
{ "reference": "{{orderNumber}}" }Sin variables integradas
Las variables integradas como {{personNumber}} y {{conversationId}} quedan vacías durante la conversación. En la mayoría de las llamadas tampoco recibes lo que se buscó antes de la llamada, así que no cuentes con ello. Si quieres comprobar que el pedido es de este cliente, crea un parámetro para el número de quien llama, por ejemplo callerNumber con la descripción «El número de teléfono de quien llama». En el chat web, el asistente solo conoce ese número si el visitante lo menciona.
La respuesta
Responde con un estado del rango 2xx, por ejemplo 200, y con JSON o texto sin formato. La respuesta se entrega tal cual al modelo de IA como resultado de la herramienta; el asistente la expresa con sus propias palabras.
{ "status": "shipped", "eta": "2026-09-14", "carrier": "PostNL" }El texto sin formato también funciona:
El pedido A-2231 se envió el 12 de septiembre con PostNL y se entregará el 14 de septiembre.- Que sea breve. El asistente recibe 6.000 caracteres como máximo; el resto se pierde. Envía solo lo que el asistente necesita, no registros completos de tu base de datos.
- Usa valores legibles. Una fecha como
2026-09-14se pronuncia bien; una marca de tiempo Unix, no. - ¿No has encontrado nada? Responde con
200y un mensaje claro, como{ "found": false, "message": "No hay ningún pedido con el número A-2231" }. Así el asistente puede decirlo con amabilidad y pedir otro número. - Reserva los estados de error para errores reales de tu sistema.
Gestión de errores
Con un estado fuera de 2xx, el asistente solo recibe el código de estado, no el contenido de tu respuesta. En ese caso no se inventa nada: dice que no lo sabe y ofrece que el equipo se ponga en contacto.
Esperamos 6 segundos a tu endpoint, y no puedes cambiar ese tiempo. Si tu endpoint no responde a tiempo o no se puede acceder a él, en una conversación de texto el asistente sabe que la consulta ha fallado. En la mayoría de las llamadas no recibe ningún resultado, así que no sabe que la petición ha fallado. Por eso, procura que tu endpoint responda con margen. No reintentamos la petición.
El código de estado y la respuesta de una llamada a la herramienta durante la conversación no se muestran en el panel. En la Bandeja, en Detalles técnicos de la conversación, Qué hicieron las acciones solo muestra las acciones posteriores a la conversación. Así que lleva tu propio registro en tu endpoint.
Añade en la Pista sobre la respuesta o en la pestaña Instrucciones qué debe hacer el asistente si la consulta falla, por ejemplo: «Si la consulta no funciona, ofrece que un compañero devuelva la llamada».
Ejemplo de conversación
Quien llama: Quiero saber dónde está mi pedido, el número es A-2231.
→ POST a tu endpoint: { "orderNumber": "A-2231" }
← { "status": "shipped", "eta": "2026-09-14", "carrier": "PostNL" }
Asistente: Tu pedido A-2231 se ha enviado con PostNL y se entregará el
14 de septiembre. ¿Puedo ayudarte en algo más?Alternativa: Google Sheets
Si los datos están en una hoja de cálculo, no necesitas un endpoint propio: con la acción de Google Sheets el asistente consulta una fila durante la conversación. Un webhook es mejor opción cuando los datos están en un CRM, una tienda online o tu propia base de datos, o cuando primero hay que calcular algo.