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

# Estrutura dos payloads

> Exemplos reais dos payloads recebidos no seu webhook para cada tipo de mensagem

export const projectName = 'Hub Message';

## Envelope do evento

Toda requisição enviada ao seu webhook tem a seguinte estrutura de topo:

```json theme={null}
{
  "message": { ... },
  "messageEventType": "NEW_MESSAGE"
}
```

| Campo              | Tipo   | Descrição                                                                     |
| ------------------ | ------ | ----------------------------------------------------------------------------- |
| `message`          | object | Objeto completo da mensagem                                                   |
| `messageEventType` | string | Tipo do evento — atualmente `"NEW_MESSAGE"` para todos os eventos de mensagem |

## Campos comuns da mensagem

Todos os payloads compartilham os mesmos campos no objeto `message`, independente do tipo de conteúdo:

| Campo                  | Tipo    | Descrição                                                              |
| ---------------------- | ------- | ---------------------------------------------------------------------- |
| `_id`                  | string  | ID único da mensagem                                                   |
| `tenant`               | string  | ID do workspace                                                        |
| `tenant_owner`         | string  | E-mail do dono do workspace                                            |
| `channel_id`           | string  | ID do canal que recebeu/enviou a mensagem                              |
| `created_by`           | string  | Origem interna da mensagem                                             |
| `created`              | number  | Timestamp de criação (epoch ms)                                        |
| `metadata.from_api`    | boolean | `true` quando enviada via API                                          |
| `metadata.from_me`     | boolean | `true` quando enviada pelo negócio; `false` quando recebida do contato |
| `metadata.middleware`  | string  | Plataforma do canal (ex: `"META_WHATSAPP"`)                            |
| `metadata.forwarded`   | boolean | `true` se a mensagem foi encaminhada                                   |
| `sender.identifier`    | string  | Identificador de quem enviou                                           |
| `sender.name`          | string  | Nome de quem enviou                                                    |
| `recipient.identifier` | string  | Telefone do destinatário (DDI + DDD + número)                          |
| `contents`             | array   | Conteúdos textuais e interativos da mensagem                           |
| `attachments`          | array   | Anexos de mídia (imagem, áudio, vídeo, sticker)                        |
| `webhook_processed`    | boolean | Controle interno de processamento                                      |

## Tipos de conteúdo

O campo que diferencia o tipo de mensagem é o `@class` dentro de cada item de `contents` ou `attachments`, combinado com o campo `type`.

***

### TEXT — Mensagem de texto

O conteúdo fica em `contents[0]` com `type: "TEXT"`.

```json theme={null}
{
  "message": {
    "_id": "019E6F1A93FE78DCB54332F9FF0CCAE7",
    "tenant": "019DCEB3E93B7077B2447616B6DC8B91",
    "tenant_owner": "email@hubmessage.io",
    "channel_id": "019E4C54B1B375A28970B605CA9B03C3",
    "created_by": "BARLING",
    "created": 1779980473342,
    "metadata": {
      "@class": ".Metadata",
      "forwarded": false,
      "from_api": true,
      "from_me": true,
      "middleware": "META_WHATSAPP",
      "moment": 1779980473342
    },
    "sender": {
      "@class": ".Sender",
      "identifier": "BARLING_SYSTEM",
      "name": "Barling System"
    },
    "recipient": {
      "@class": ".Recipient",
      "identifier": "5544936181064",
      "name": "5544936181064"
    },
    "contents": [
      {
        "@class": ".TextContent",
        "identifier": "019E6F1A93FE78DCB542303FF18D389A",
        "internal_information": {},
        "message": "Olá! Tudo bem? Estamos com novidades incríveis esperando por você.",
        "state_items": [
          {
            "@class": ".StateItem",
            "identifier": "019E6F1A93FE78DCB5418E8D9D007FFB",
            "integration_message_ids": [],
            "moment": 1779980473342,
            "state": { "@class": ".Pending", "name": "PENDING" }
          }
        ],
        "type": "TEXT"
      }
    ],
    "attachments": [],
    "actions": [],
    "webhook_processed": false
  },
  "messageEventType": "NEW_MESSAGE"
}
```

***

### IMAGE — Imagem com legenda

O anexo fica em `attachments[0]` com `type: "IMAGE"`. O campo `caption` é opcional.

```json theme={null}
{
  "message": {
    "_id": "019E6F1A9553705584AD73DBA1F995A1",
    "tenant": "019DCEB3E93B7077B2447616B6DC8B91",
    "tenant_owner": "email@hubmessage.io",
    "channel_id": "019E4C54B1B375A28970B605CA9B03C3",
    "created_by": "BARLING",
    "created": 1779980473683,
    "metadata": {
      "@class": ".Metadata",
      "forwarded": false,
      "from_api": true,
      "from_me": true,
      "middleware": "META_WHATSAPP",
      "moment": 1779980473683
    },
    "sender": {
      "@class": ".Sender",
      "identifier": "BARLING_SYSTEM",
      "name": "Barling System"
    },
    "recipient": {
      "@class": ".Recipient",
      "identifier": "5544936181064",
      "name": "5544936181064"
    },
    "contents": [],
    "attachments": [
      {
        "@class": ".ImageAttachment",
        "caption": "Confira nossa linha de produtos exclusivos!",
        "identifier": "019E6F1A9553705584AC33FB12CBAE6B",
        "internal_information": {},
        "state_items": [
          {
            "@class": ".StateItem",
            "identifier": "019E6F1A9553705584AB3D1D8510E8C3",
            "integration_message_ids": [],
            "moment": 1779980473683,
            "state": { "@class": ".Pending", "name": "PENDING" }
          }
        ],
        "thumbnail_url": "https://exemplo.com/imagem-thumb.png",
        "type": "IMAGE",
        "url": "https://exemplo.com/imagem.png"
      }
    ],
    "actions": [],
    "webhook_processed": false
  },
  "messageEventType": "NEW_MESSAGE"
}
```

***

### AUDIO — Mensagem de voz

O anexo fica em `attachments[0]` com `type: "AUDIO"`.

```json theme={null}
{
  "message": {
    "_id": "019E6F1A96A7748489ECA59E6DCD8D63",
    "tenant": "019DCEB3E93B7077B2447616B6DC8B91",
    "tenant_owner": "email@hubmessage.io",
    "channel_id": "019E4C54B1B375A28970B605CA9B03C3",
    "created_by": "BARLING",
    "created": 1779980474023,
    "metadata": {
      "@class": ".Metadata",
      "forwarded": false,
      "from_api": true,
      "from_me": true,
      "middleware": "META_WHATSAPP",
      "moment": 1779980474023
    },
    "sender": {
      "@class": ".Sender",
      "identifier": "BARLING_SYSTEM",
      "name": "Barling System"
    },
    "recipient": {
      "@class": ".Recipient",
      "identifier": "5544936181064",
      "name": "5544936181064"
    },
    "contents": [],
    "attachments": [
      {
        "@class": ".AudioAttachment",
        "identifier": "019E6F1A96A7748489EBB11ED108DB51",
        "internal_information": {},
        "state_items": [
          {
            "@class": ".StateItem",
            "identifier": "019E6F1A96A7748489EAC89D6BDBDD8A",
            "integration_message_ids": [],
            "moment": 1779980474023,
            "state": { "@class": ".Pending", "name": "PENDING" }
          }
        ],
        "type": "AUDIO",
        "url": "https://exemplo.com/audio.mp3"
      }
    ],
    "actions": [],
    "webhook_processed": false
  },
  "messageEventType": "NEW_MESSAGE"
}
```

***

### VIDEO — Vídeo com legenda

O anexo fica em `attachments[0]` com `type: "VIDEO"`. O campo `caption` é opcional.

```json theme={null}
{
  "message": {
    "_id": "019E6F1A97F57A7BAFA0AF6D2ED9EA55",
    "tenant": "019DCEB3E93B7077B2447616B6DC8B91",
    "tenant_owner": "email@hubmessage.io",
    "channel_id": "019E4C54B1B375A28970B605CA9B03C3",
    "created_by": "BARLING",
    "created": 1779980474357,
    "metadata": {
      "@class": ".Metadata",
      "forwarded": false,
      "from_api": true,
      "from_me": true,
      "middleware": "META_WHATSAPP",
      "moment": 1779980474357
    },
    "sender": {
      "@class": ".Sender",
      "identifier": "BARLING_SYSTEM",
      "name": "Barling System"
    },
    "recipient": {
      "@class": ".Recipient",
      "identifier": "5544936181064",
      "name": "5544936181064"
    },
    "contents": [],
    "attachments": [
      {
        "@class": ".VideoAttachment",
        "caption": "Assista e descubra como podemos te ajudar!",
        "identifier": "019E6F1A97F57A7BAF9F8945CDF9F269",
        "internal_information": {},
        "state_items": [
          {
            "@class": ".StateItem",
            "identifier": "019E6F1A97F57A7BAF9E16EF4D180B18",
            "integration_message_ids": [],
            "moment": 1779980474357,
            "state": { "@class": ".Pending", "name": "PENDING" }
          }
        ],
        "type": "VIDEO",
        "url": "https://exemplo.com/video.mp4"
      }
    ],
    "actions": [],
    "webhook_processed": false
  },
  "messageEventType": "NEW_MESSAGE"
}
```

***

### STICKER — Figurinha

O anexo fica em `attachments[0]` com `type: "STICKER"`. A URL aponta para um arquivo `.webp`.

```json theme={null}
{
  "message": {
    "_id": "019E6F1A9A8D74A097E650D75365502A",
    "tenant": "019DCEB3E93B7077B2447616B6DC8B91",
    "tenant_owner": "email@hubmessage.io",
    "channel_id": "019E4C54B1B375A28970B605CA9B03C3",
    "created_by": "BARLING",
    "created": 1779980475021,
    "metadata": {
      "@class": ".Metadata",
      "forwarded": false,
      "from_api": true,
      "from_me": true,
      "middleware": "META_WHATSAPP",
      "moment": 1779980475021
    },
    "sender": {
      "@class": ".Sender",
      "identifier": "BARLING_SYSTEM",
      "name": "Barling System"
    },
    "recipient": {
      "@class": ".Recipient",
      "identifier": "5544936181064",
      "name": "5544936181064"
    },
    "contents": [],
    "attachments": [
      {
        "@class": ".StickerAttachment",
        "identifier": "019E6F1A9A8D74A097E504E363C5809F",
        "state_items": [
          {
            "@class": ".StateItem",
            "identifier": "019E6F1A9A8D74A097E4782F3FA0D805",
            "integration_message_ids": [],
            "moment": 1779980475021,
            "state": { "@class": ".Pending", "name": "PENDING" }
          }
        ],
        "type": "STICKER",
        "url": "https://exemplo.com/sticker.webp"
      }
    ],
    "actions": [],
    "webhook_processed": false
  },
  "messageEventType": "NEW_MESSAGE"
}
```

***

### CONTACT\_ARRAY — Contato(s)

O conteúdo fica em `contents[0]` com `type: "CONTACT_ARRAY"`. O array `contacts` pode conter múltiplos contatos, cada um com `first_name`, `last_name`, `name` e `phones`.

```json theme={null}
{
  "message": {
    "_id": "019E6F1A994975239E609D161623D3AD",
    "tenant": "019DCEB3E93B7077B2447616B6DC8B91",
    "tenant_owner": "email@hubmessage.io",
    "channel_id": "019E4C54B1B375A28970B605CA9B03C3",
    "created_by": "BARLING",
    "created": 1779980474697,
    "metadata": {
      "@class": ".Metadata",
      "forwarded": false,
      "from_api": true,
      "from_me": true,
      "middleware": "META_WHATSAPP",
      "moment": 1779980474697
    },
    "sender": {
      "@class": ".Sender",
      "identifier": "BARLING_SYSTEM",
      "name": "Barling System"
    },
    "recipient": {
      "@class": ".Recipient",
      "identifier": "5544936181064",
      "name": "5544936181064"
    },
    "contents": [
      {
        "@class": ".ContactArrayContent",
        "contacts": [
          {
            "@class": ".ContactContent",
            "first_name": "Ryan",
            "identifier": "019E6F1A994975239E5E5BAF8C833D29",
            "last_name": "Andrade",
            "name": "Ryan Andrade",
            "phones": ["5544997294496"],
            "type": "CONTACT"
          }
        ],
        "identifier": "019E6F1A994975239E5FB79A31BFC0D8",
        "internal_information": {},
        "state_items": [
          {
            "@class": ".StateItem",
            "identifier": "019E6F1A994975239E5D8A8C150F9F59",
            "integration_message_ids": [],
            "moment": 1779980474697,
            "state": { "@class": ".Pending", "name": "PENDING" }
          }
        ],
        "type": "CONTACT_ARRAY"
      }
    ],
    "attachments": [],
    "actions": [],
    "webhook_processed": false
  },
  "messageEventType": "NEW_MESSAGE"
}
```

***

### INTERACTIVE\_BUTTON — Botões de resposta rápida (texto)

O conteúdo fica em `contents[0]` com `type: "INTERACTIVE_BUTTON"`. O campo `internal_information.mediaButtonType` indica o tipo de mídia anexada: `"TEXT"` quando não há mídia.

```json theme={null}
{
  "message": {
    "_id": "019E6F1A9D797F86B18E80700C3F22BD",
    "tenant": "019DCEB3E93B7077B2447616B6DC8B91",
    "tenant_owner": "email@hubmessage.io",
    "channel_id": "019E4C54B1B375A28970B605CA9B03C3",
    "created_by": "BARLING",
    "created": 1779980475768,
    "metadata": {
      "@class": ".Metadata",
      "forwarded": false,
      "from_api": true,
      "from_me": true,
      "middleware": "META_WHATSAPP",
      "moment": 1779980475768
    },
    "sender": {
      "@class": ".Sender",
      "identifier": "BARLING_SYSTEM",
      "name": "Barling System"
    },
    "recipient": {
      "@class": ".Recipient",
      "identifier": "5544936181064",
      "name": "5544936181064"
    },
    "contents": [
      {
        "@class": ".InteractiveButtonContent",
        "buttons": [
          {
            "@class": "com.arkansas.littlerock.core.domain.content.ButtonContent",
            "id": "1",
            "identifier": "019E6F1A9D78704094E6BF55E8608F62",
            "title": "Ótimo",
            "type": "BUTTON"
          },
          {
            "@class": "com.arkansas.littlerock.core.domain.content.ButtonContent",
            "id": "2",
            "identifier": "019E6F1A9D78704094E7458F381C4760",
            "title": "Bom",
            "type": "BUTTON"
          },
          {
            "@class": "com.arkansas.littlerock.core.domain.content.ButtonContent",
            "id": "3",
            "identifier": "019E6F1A9D78704094E8F88F236F2BDB",
            "title": "Regular",
            "type": "BUTTON"
          }
        ],
        "identifier": "019E6F1A9D797F86B18D0DE8252112B4",
        "internal_information": { "mediaButtonType": "TEXT" },
        "message": "Oi! Como foi sua experiência com a gente?",
        "state_items": [
          {
            "@class": ".StateItem",
            "identifier": "019E6F1A9D78704094E5ED1463943EF7",
            "integration_message_ids": [],
            "moment": 1779980475768,
            "state": { "@class": ".Pending", "name": "PENDING" }
          }
        ],
        "type": "INTERACTIVE_BUTTON"
      }
    ],
    "attachments": [],
    "actions": [],
    "webhook_processed": false
  },
  "messageEventType": "NEW_MESSAGE"
}
```

***

### INTERACTIVE\_BUTTON — Botões de resposta rápida (com imagem)

Quando `internal_information.mediaButtonType` é `"IMAGE"`, o campo `thumbnail` contém a URL da imagem exibida acima dos botões.

```json theme={null}
{
  "message": {
    "_id": "019E6F1A9DDA7B3B92E8EF5955A33D3A",
    "tenant": "019DCEB3E93B7077B2447616B6DC8B91",
    "tenant_owner": "email@hubmessage.io",
    "channel_id": "019E4C54B1B375A28970B605CA9B03C3",
    "created_by": "BARLING",
    "created": 1779980475864,
    "metadata": {
      "@class": ".Metadata",
      "forwarded": false,
      "from_api": true,
      "from_me": true,
      "middleware": "META_WHATSAPP",
      "moment": 1779980475866
    },
    "sender": {
      "@class": ".Sender",
      "identifier": "BARLING_SYSTEM",
      "name": "Barling System"
    },
    "recipient": {
      "@class": ".Recipient",
      "identifier": "5544936181064",
      "name": "5544936181064"
    },
    "contents": [
      {
        "@class": ".InteractiveButtonContent",
        "buttons": [
          {
            "@class": "com.arkansas.littlerock.core.domain.content.ButtonContent",
            "id": "1",
            "identifier": "019E6F1A9DDA7B3B92E55FED919D3B46",
            "title": "Tenho interesse",
            "type": "BUTTON"
          },
          {
            "@class": "com.arkansas.littlerock.core.domain.content.ButtonContent",
            "id": "2",
            "identifier": "019E6F1A9DDA7B3B92E65ED03B1AA85C",
            "title": "Não, obrigado",
            "type": "BUTTON"
          }
        ],
        "identifier": "019E6F1A9DDA7B3B92E70CADB0034C76",
        "internal_information": { "mediaButtonType": "IMAGE" },
        "message": "Oferta especial só para você! Aproveite antes que acabe.",
        "state_items": [
          {
            "@class": ".StateItem",
            "identifier": "019E6F1A9DDA7B3B92E43ADD4BB2FCE6",
            "integration_message_ids": [],
            "moment": 1779980475866,
            "state": { "@class": ".Pending", "name": "PENDING" }
          }
        ],
        "thumbnail": "https://exemplo.com/imagem.png",
        "type": "INTERACTIVE_BUTTON"
      }
    ],
    "attachments": [],
    "actions": [],
    "webhook_processed": false
  },
  "messageEventType": "NEW_MESSAGE"
}
```

***

### INTERACTIVE\_ACTION — Botões de ação (URL e ligar)

O conteúdo fica em `contents[0]` com `type: "INTERACTIVE_ACTION"`. Cada botão em `buttons` tem um `type` próprio: `"URL"` ou `"CALL"`. Os campos `header` e `footer` são opcionais.

```json theme={null}
{
  "message": {
    "_id": "019E6F1A9BD8708EA5C67A9DBB071E68",
    "tenant": "019DCEB3E93B7077B2447616B6DC8B91",
    "tenant_owner": "email@hubmessage.io",
    "channel_id": "019E4C54B1B375A28970B605CA9B03C3",
    "created_by": "BARLING",
    "created": 1779980475352,
    "metadata": {
      "@class": ".Metadata",
      "forwarded": false,
      "from_api": true,
      "from_me": true,
      "middleware": "META_WHATSAPP",
      "moment": 1779980475352
    },
    "sender": {
      "@class": ".Sender",
      "identifier": "BARLING_SYSTEM",
      "name": "Barling System"
    },
    "recipient": {
      "@class": ".Recipient",
      "identifier": "5544936181064",
      "name": "5544936181064"
    },
    "contents": [
      {
        "@class": ".InteractiveActionContent",
        "action": {
          "@class": ".ActionContent",
          "identifier": "019E6F1A9BD8708EA5C4EFD19090B043",
          "type": "BUTTON"
        },
        "buttons": [
          {
            "@class": ".ButtonActionContent",
            "id": "1",
            "identifier": "019E6F1A9BD8708EA5C05038542872ED",
            "title": "Visite nosso site",
            "type": "URL",
            "url": "https://www.hubmessage.io"
          },
          {
            "@class": ".ButtonActionContent",
            "id": "2",
            "identifier": "019E6F1A9BD8708EA5C1D19DAE30D4D0",
            "phone": "5544997294496",
            "title": "Fale conosco",
            "type": "CALL"
          }
        ],
        "footer": {
          "@class": ".FooterContent",
          "identifier": "019E6F1A9BD8708EA5C315998956AE77",
          "message": "Escolha uma opção",
          "type": "BUTTON"
        },
        "header": {
          "@class": ".HeaderContent",
          "identifier": "019E6F1A9BD8708EA5C2D3033640052B",
          "message": "Hub Message",
          "type": "BUTTON"
        },
        "identifier": "019E6F1A9BD8708EA5C5ACAB2DFBD176",
        "internal_information": {},
        "message": "Como podemos te ajudar?",
        "state_items": [
          {
            "@class": ".StateItem",
            "identifier": "019E6F1A9BD8708EA5BF766A2E8F53A3",
            "integration_message_ids": [],
            "moment": 1779980475352,
            "state": { "@class": ".Pending", "name": "PENDING" }
          }
        ],
        "type": "INTERACTIVE_ACTION"
      }
    ],
    "attachments": [],
    "actions": [],
    "webhook_processed": false
  },
  "messageEventType": "NEW_MESSAGE"
}
```

***

## Resumo dos tipos

| `type`               | Localização      | Campo chave                                                          |
| -------------------- | ---------------- | -------------------------------------------------------------------- |
| `TEXT`               | `contents[0]`    | `message`                                                            |
| `IMAGE`              | `attachments[0]` | `url`, `caption` (opcional), `thumbnail_url`                         |
| `AUDIO`              | `attachments[0]` | `url`                                                                |
| `VIDEO`              | `attachments[0]` | `url`, `caption` (opcional)                                          |
| `STICKER`            | `attachments[0]` | `url` (`.webp`)                                                      |
| `CONTACT_ARRAY`      | `contents[0]`    | `contacts[]` com `name`, `phones`                                    |
| `INTERACTIVE_BUTTON` | `contents[0]`    | `message`, `buttons[]`, `thumbnail` (se `mediaButtonType: "IMAGE"`)  |
| `INTERACTIVE_ACTION` | `contents[0]`    | `message`, `buttons[]` com `type: "URL"\|"CALL"`, `header`, `footer` |