> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jelou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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. Timeout de **20 segundos** y **un solo intento** (sin retry ni backoff).

## Envelope

```json theme={null}
{
  "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`                                             |

<Note>
  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.
</Note>

## Ejemplos

<Tabs>
  <Tab title="TEXT">
    ```json theme={null}
    {
      "event": "message",
      "botId": "BOT_ID",
      "userId": "user-123",
      "message": {
        "messageId": "msg-1",
        "type": "TEXT",
        "text": "¿En qué podemos ayudarte?"
      }
    }
    ```
  </Tab>

  <Tab title="BUTTONS">
    ```json theme={null}
    {
      "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": "" }
        ]
      }
    }
    ```
  </Tab>

  <Tab title="IMAGE">
    ```json theme={null}
    {
      "event": "message",
      "botId": "BOT_ID",
      "userId": "user-123",
      "message": {
        "messageId": "msg-3",
        "type": "IMAGE",
        "mediaUrl": "https://cdn.example.com/foto.jpg",
        "caption": "Comprobante"
      }
    }
    ```
  </Tab>
</Tabs>

<Warning>
  Tu endpoint debe responder 2xx dentro de 20 segundos. Si falla la entrega, Jelou no reintenta automáticamente en esta versión.
</Warning>