> ## 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.

# Response format

> Payload Jelou sends to your webhookUrl with agent replies

## Description

When the agent produces a bubble, Jelou `POST`s to your `webhookUrl` with the formatted message. Timeout is **20 seconds** with a **single attempt** (no retry or backoff).

## Envelope

```json theme={null}
{
  "event": "message",
  "botId": "BOT_ID",
  "userId": "user-123",
  "message": {
    "messageId": "msg-1",
    "type": "TEXT"
  }
}
```

| Field     | Description                                                           |
| --------- | --------------------------------------------------------------------- |
| `event`   | Always `"message"`.                                                   |
| `botId`   | Agent identifier.                                                     |
| `userId`  | The `referenceId` you sent on the inbound interaction.                |
| `message` | Object by bubble type (table below). Includes `messageId` and `type`. |

## Delivery headers

* `Content-Type: application/json`
* Auth from `credentials.auth` (when configured):
  * `api_key` → configurable header (default `X-Api-Key`)
  * `bearer` → `Authorization: Bearer <value>`
  * `basic` → `value` is the full `username:password` string before Base64; the header is `Authorization: Basic <base64(username:password)>`
* `X-Jelou-Signature: sha256=<hmac>` computed over the exact raw HTTP body bytes (always present; the signing key is required). Verify against that raw body before parsing it as JSON; do not re-serialize the parsed object.

## Message types (`message`)

| Outbound type       | Typical source                        | Fields                                                                      |
| ------------------- | ------------------------------------- | --------------------------------------------------------------------------- |
| `TEXT`              | Text bubble without options           | `messageId`, `type`, `text`                                                 |
| `BUTTONS`           | Text with options, or `BUTTON` bubble | `messageId`, `type`, `text`, `title`, `options[]` (`title`, `description`)  |
| `QUICK_REPLY`       | `QUICK_REPLY` bubble                  | `messageId`, `type`, `text`, `options[]` (`title`, `description`)           |
| `LIST`              | `LIST` bubble                         | `messageId`, `type`, `text`, `button`, `options[]` (`title`, `description`) |
| `IMAGE` / `VIDEO`   | Media                                 | `messageId`, `type`, `mediaUrl`, `caption`                                  |
| `DOCUMENT` / `FILE` | File                                  | `messageId`, `type`, `mediaUrl`, `filename`, `caption`                      |
| `AUDIO`             | Audio                                 | `messageId`, `type`, `mediaUrl`                                             |
| `LOCATION`          | Location                              | `messageId`, `type`, `coordinates`, `address`                               |
| `CONTACTS`          | Contacts                              | `messageId`, `type`, `contacts`                                             |

<Note>
  Flow text with interactive options usually arrives as `type: "BUTTONS"`, not `TEXT`. The wire type for quick replies is `QUICK_REPLY` (underscore). The **Sticker** block is not available in the builder for this channel.
</Note>

## Examples

<Tabs>
  <Tab title="TEXT">
    ```json theme={null}
    {
      "event": "message",
      "botId": "BOT_ID",
      "userId": "user-123",
      "message": {
        "messageId": "msg-1",
        "type": "TEXT",
        "text": "How can we help you?"
      }
    }
    ```
  </Tab>

  <Tab title="BUTTONS">
    ```json theme={null}
    {
      "event": "message",
      "botId": "BOT_ID",
      "userId": "user-123",
      "message": {
        "messageId": "msg-2",
        "type": "BUTTONS",
        "text": "Pick an option",
        "title": "Menu",
        "options": [
          { "title": "Support", "description": "" },
          { "title": "Sales", "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/photo.jpg",
        "caption": "Receipt"
      }
    }
    ```
  </Tab>
</Tabs>

<Warning>
  Your endpoint must return 2xx within 20 seconds. If delivery fails, Jelou does not automatically retry in this version.
</Warning>