> ## 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 da resposta

> Payload que a Jelou envia ao seu webhookUrl com as respostas do agente

## Descrição

Quando o agente gera uma bolha, a Jelou faz `POST` no seu `webhookUrl` com a mensagem formatada. Timeout de **20 segundos** e **uma única tentativa** (sem retry nem backoff).

## Envelope

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

| Campo     | Descrição                                                                     |
| --------- | ----------------------------------------------------------------------------- |
| `event`   | Sempre `"message"`.                                                           |
| `botId`   | Identificador do agente.                                                      |
| `userId`  | O `referenceId` que você enviou na interação de entrada.                      |
| `message` | Objeto conforme o tipo de bolha (tabela abaixo). Inclui `messageId` e `type`. |

## Headers da entrega

* `Content-Type: application/json`
* Auth conforme `credentials.auth` (se configurada):
  * `api_key` → header configurável (padrão `X-Api-Key`)
  * `bearer` → `Authorization: Bearer <value>`
  * `basic` → `value` é a string completa `username:password` antes do Base64; o header é `Authorization: Basic <base64(username:password)>`
* `X-Jelou-Signature: sha256=<hmac>` calculado sobre os bytes exatos do body HTTP bruto (sempre presente; a signing key é obrigatória). Verifique com esse raw body antes de fazer o parse como JSON; não serialize novamente o objeto parseado.

## Tipos de mensagem (`message`)

| Tipo de saída       | Origem típica                       | Campos                                                                      |
| ------------------- | ----------------------------------- | --------------------------------------------------------------------------- |
| `TEXT`              | Bolha de texto sem opções           | `messageId`, `type`, `text`                                                 |
| `BUTTONS`           | Texto com opções, ou bolha `BUTTON` | `messageId`, `type`, `text`, `title`, `options[]` (`title`, `description`)  |
| `QUICK_REPLY`       | Bolha `QUICK_REPLY`                 | `messageId`, `type`, `text`, `options[]` (`title`, `description`)           |
| `LIST`              | Bolha `LIST`                        | `messageId`, `type`, `text`, `button`, `options[]` (`title`, `description`) |
| `IMAGE` / `VIDEO`   | Mídia                               | `messageId`, `type`, `mediaUrl`, `caption`                                  |
| `DOCUMENT` / `FILE` | Arquivo                             | `messageId`, `type`, `mediaUrl`, `filename`, `caption`                      |
| `AUDIO`             | Áudio                               | `messageId`, `type`, `mediaUrl`                                             |
| `LOCATION`          | Localização                         | `messageId`, `type`, `coordinates`, `address`                               |
| `CONTACTS`          | Contatos                            | `messageId`, `type`, `contacts`                                             |

<Note>
  Um texto do fluxo com opções interativas costuma chegar como `type: "BUTTONS"`, não como `TEXT`. O tipo no wire de respostas rápidas é `QUICK_REPLY` (com underscore). O bloco **Sticker** não está disponível no builder para este canal.
</Note>

## Exemplos

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

  <Tab title="BUTTONS">
    ```json theme={null}
    {
      "event": "message",
      "botId": "BOT_ID",
      "userId": "user-123",
      "message": {
        "messageId": "msg-2",
        "type": "BUTTONS",
        "text": "Escolha uma opção",
        "title": "Menu",
        "options": [
          { "title": "Suporte", "description": "" },
          { "title": "Vendas", "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": "Comprovante"
      }
    }
    ```
  </Tab>
</Tabs>

<Warning>
  Seu endpoint deve responder 2xx em até 20 segundos. Se a entrega falhar, a Jelou não tenta novamente automaticamente nesta versão.
</Warning>