Estrutura dos payloads

Envelope do evento

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

{
  "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

Mensagens de grupo (WhatsApp Web)

Em canais WhatsApp Web (metadata.middleware igual a "Z_API_WHATSAPP"), uma mensagem trocada em grupo traz a identificação do grupo em internal_information de cada item de contents e attachments:

Campo	Tipo	Descrição
`internal_information.group_id`	string	ID do grupo, no formato `120363430845284251-group`. Grupos antigos podem vir no formato `556592929755-1499690308`
`internal_information.group_name`	string	Nome do grupo
`internal_information.participant_lid`	string	LID de quem enviou a mensagem no grupo, quando a plataforma informa

Em mensagem recebida de grupo, sender.identifier é o telefone de quem escreveu, não o do grupo. Os dois campos de grupo aparecem também quando a mensagem é enviada ao grupo pelo próprio número (metadata.from_me: true). Mensagens individuais não têm group_id nem group_name.

"contents": [
  {
    "@class": ".TextContent",
    "internal_information": {
      "group_id": "120363430845284251-group",
      "group_name": "Equipe de vendas"
    },
    "message": "Bom dia, pessoal!",
    "type": "TEXT"
  }
]

Nos webhooks no formato Z-API, enviados aos canais da Compatibilidade Z-API, a mensagem recebida de grupo segue a estrutura da Z-API: phone e chatName identificam o grupo, participantPhone e participantLid identificam quem enviou, e o callback de status traz isGroup: true.

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

{
  "message": {
    "_id": "019E6F1A93FE78DCB54332F9FF0CCAE7",
    "tenant": "019DCEB3E93B7077B2447616B6DC8B91",
    "tenant_owner": "email@z-api.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.

{
  "message": {
    "_id": "019E6F1A9553705584AD73DBA1F995A1",
    "tenant": "019DCEB3E93B7077B2447616B6DC8B91",
    "tenant_owner": "email@z-api.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".

{
  "message": {
    "_id": "019E6F1A96A7748489ECA59E6DCD8D63",
    "tenant": "019DCEB3E93B7077B2447616B6DC8B91",
    "tenant_owner": "email@z-api.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.

{
  "message": {
    "_id": "019E6F1A97F57A7BAFA0AF6D2ED9EA55",
    "tenant": "019DCEB3E93B7077B2447616B6DC8B91",
    "tenant_owner": "email@z-api.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.

{
  "message": {
    "_id": "019E6F1A9A8D74A097E650D75365502A",
    "tenant": "019DCEB3E93B7077B2447616B6DC8B91",
    "tenant_owner": "email@z-api.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.

{
  "message": {
    "_id": "019E6F1A994975239E609D161623D3AD",
    "tenant": "019DCEB3E93B7077B2447616B6DC8B91",
    "tenant_owner": "email@z-api.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.

{
  "message": {
    "_id": "019E6F1A9D797F86B18E80700C3F22BD",
    "tenant": "019DCEB3E93B7077B2447616B6DC8B91",
    "tenant_owner": "email@z-api.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.

{
  "message": {
    "_id": "019E6F1A9DDA7B3B92E8EF5955A33D3A",
    "tenant": "019DCEB3E93B7077B2447616B6DC8B91",
    "tenant_owner": "email@z-api.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.

{
  "message": {
    "_id": "019E6F1A9BD8708EA5C67A9DBB071E68",
    "tenant": "019DCEB3E93B7077B2447616B6DC8B91",
    "tenant_owner": "email@z-api.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.omni.z-api.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": "Omni Z-API",
          "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`

Canais

Mensagens

Templates (WhatsApp)

Flows (WhatsApp)

Webhooks

Estrutura dos payloads

Envelope do evento

Campos comuns da mensagem

Mensagens de grupo (WhatsApp Web)

Tipos de conteúdo

TEXT — Mensagem de texto

IMAGE — Imagem com legenda

AUDIO — Mensagem de voz

VIDEO — Vídeo com legenda

STICKER — Figurinha

CONTACT_ARRAY — Contato(s)

INTERACTIVE_BUTTON — Botões de resposta rápida (texto)

INTERACTIVE_BUTTON — Botões de resposta rápida (com imagem)

INTERACTIVE_ACTION — Botões de ação (URL e ligar)

Resumo dos tipos

​Envelope do evento

​Campos comuns da mensagem

​Mensagens de grupo (WhatsApp Web)

​Tipos de conteúdo

​TEXT — Mensagem de texto

​IMAGE — Imagem com legenda

​AUDIO — Mensagem de voz

​VIDEO — Vídeo com legenda

​STICKER — Figurinha

​CONTACT_ARRAY — Contato(s)

​INTERACTIVE_BUTTON — Botões de resposta rápida (texto)

​INTERACTIVE_BUTTON — Botões de resposta rápida (com imagem)

​INTERACTIVE_ACTION — Botões de ação (URL e ligar)

​Resumo dos tipos

Envelope do evento

Campos comuns da mensagem

Mensagens de grupo (WhatsApp Web)

Tipos de conteúdo

TEXT — Mensagem de texto

IMAGE — Imagem com legenda

AUDIO — Mensagem de voz

VIDEO — Vídeo com legenda

STICKER — Figurinha

CONTACT_ARRAY — Contato(s)

INTERACTIVE_BUTTON — Botões de resposta rápida (texto)

INTERACTIVE_BUTTON — Botões de resposta rápida (com imagem)

INTERACTIVE_ACTION — Botões de ação (URL e ligar)

Resumo dos tipos