Formato de respuesta

Payload que Jelou envía a tu webhookUrl con las respuestas del agente

​

Descripción

Cuando el agente genera una burbuja, Jelou hace POST a tu webhookUrl con el mensaje formateado. La entrega tiene un límite total de 20 segundos que cubre hasta 3 intentos — ver Entrega y reintentos.

​

Envelope

{
  "event": "message",
  "botId": "BOT_ID",
  "userId": "user-123",
  "message": {
    "messageId": "msg-1",
    "type": "TEXT"
  }
}

Campo	Descripción
event	Siempre "message".
botId	Identificador del agente.
userId	El referenceId que enviaste en la interacción entrante.
message	Objeto según el tipo de burbuja (tabla abajo). Incluye messageId y type.

​

Headers de la entrega

• Content-Type: application/json
• Auth según credentials.auth (si está configurada):
  • api_key → header configurable (default X-Api-Key)
  • bearer → Authorization: Bearer <value>
  • basic → value es la cadena completa username:password antes de Base64; el header es Authorization: Basic <base64(username:password)>
• X-Jelou-Signature: sha256=<hmac> calculado sobre los bytes exactos del body HTTP crudo (siempre presente; la signing key es obligatoria). Verifica con ese raw body antes de parsearlo como JSON; no vuelvas a serializar el objeto parseado.

​

Tipos de mensaje (message)

Tipo saliente	Origen típico	Campos
TEXT	Burbuja de texto sin opciones	messageId, type, text
BUTTONS	Texto con opciones, o burbuja BUTTON	messageId, type, text, title, options[] (title, description)
QUICK_REPLY	Burbuja QUICK_REPLY	messageId, type, text, options[] (title, description)
LIST	Burbuja LIST	messageId, type, text, button, options[] (title, description)
IMAGE / VIDEO	Media	messageId, type, mediaUrl, caption
DOCUMENT / FILE	Archivo	messageId, type, mediaUrl, filename, caption
AUDIO	Audio	messageId, type, mediaUrl
LOCATION	Ubicación	messageId, type, coordinates, address
CONTACTS	Contactos	messageId, type, contacts

Un texto del flujo con opciones interactivas suele llegar como type: "BUTTONS", no como TEXT. El tipo en el wire de respuestas rápidas es QUICK_REPLY (con guion bajo). El bloque Sticker no está disponible en el builder para este canal.

​

Ejemplos

TEXT

{
  "event": "message",
  "botId": "BOT_ID",
  "userId": "user-123",
  "message": {
    "messageId": "msg-1",
    "type": "TEXT",
    "text": "¿En qué podemos ayudarte?"
  }
}

BUTTONS

{
  "event": "message",
  "botId": "BOT_ID",
  "userId": "user-123",
  "message": {
    "messageId": "msg-2",
    "type": "BUTTONS",
    "text": "Elige una opción",
    "title": "Menú",
    "options": [
      { "title": "Soporte", "description": "" },
      { "title": "Ventas", "description": "" }
    ]
  }
}

IMAGE

{
  "event": "message",
  "botId": "BOT_ID",
  "userId": "user-123",
  "message": {
    "messageId": "msg-3",
    "type": "IMAGE",
    "mediaUrl": "https://cdn.example.com/foto.jpg",
    "caption": "Comprobante"
  }
}

​

Entrega y reintentos

Tu endpoint debe responder 2xx. Jelou reintenta una entrega fallida hasta 3 intentos en total, todos dentro de un único límite total de 20 segundos — ese límite incluye cada intento y las esperas entre ellos, así que la entrega de un mensaje nunca tarda más de 20 segundos.

Tu respuesta	¿Se reintenta?
5xx	Sí
429	Sí, esperando exactamente el Retry-After que pidas. Si esa espera no cabe en el tiempo que queda, la entrega falla en vez de reintentar antes de tiempo
Conexión rechazada, socket reseteado	Sí
Fallo de DNS (el hostname no resuelve)	No — un webhookUrl que no resuelve es un error de configuración, no un blip
4xx distinto de 429	No — un request idéntico no puede cambiar la respuesta
Sin respuesta dentro del límite (timeout)	No
2xx	Entregado

El backoff entre intentos es exponencial con jitter (aproximadamente 300 ms y luego 600 ms).

Tienes que deduplicar. Cada intento del mismo mensaje lleva un body idéntico, un message.messageId idéntico y una X-Jelou-Signature idéntica. Trata message.messageId como clave de idempotencia: si ya lo procesaste, responde 2xx y no hagas nada más. Responder 5xx después de haber procesado un mensaje hará que Jelou lo entregue de nuevo.

Cada entrega lleva un header X-Jelou-Delivery-Attempt (1, 2, 3) que te dice de qué intento se trata — útil para logs.

Ese header no está autenticado: el HMAC cubre el body, así que quien replique un request capturado puede ponerle el valor que quiera. No lo uses como protección anti-replay. Verifica primero X-Jelou-Signature y después deduplica por el message.messageId autenticado.

Si todos los intentos fallan, el mensaje no se entrega y el turno se aborta; en esta versión no hay reentrega encolada.