> ## Documentation Index
> Fetch the complete documentation index at: https://developer.zapsterapi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Eventos Disponíveis
> Lista de eventos suportados e exemplos
Estamos em processo de melhorias da nossa documentação, em breve estaremos incluindo mais eventos com seus devidos exemplos.
Alguns eventos dependem do tipo de conexão da instância. Instâncias com **API oficial (WABA)** emitem hoje apenas `message.received`, `message.flow_reply`, `message.sent`, `message.delivered`, `message.read` e `message.failed`; os demais eventos desta página são emitidos por instâncias **não oficiais** (conexão por QR Code). Na outra direção, `message.failed` e `message.flow_reply` existem apenas na API oficial. A API recusa a assinatura de qualquer evento indisponível para o tipo de conexão da instância, tanto na criação quanto na atualização do webhook: a resposta é um erro `400` com o código `unsupported_webhook_event`, que nomeia todos os eventos recusados e lista os eventos disponíveis para aquela instância. Cada evento com essa restrição traz o aviso na sua própria seção.
### `instance.connected`
A instância foi conectada com sucesso e está pronta para envio e recebimento de mensagens.
```json theme={null}
{
"created_at": "2024-03-14T23:33:13.623Z",
"data": {
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/..."
},
"id": "so9lv3u3pu81he8gumfa4", // ID da notificação
"type": "instance.connected"
}
```
### `instance.disconnected`
A instância foi desconectada com sucesso.
Algumas vezes a desconexão pode acontecer devido a falhas internas do Whatsapp, internamente temos estrategias de recuperação, nestes casos o evento `instance.connected` pode ser emitido alguns segundos depois do evento de desconexão.
```json theme={null}
{
"created_at": "2024-09-14T13:51:49.224Z",
"data": {
"name": "Account Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/...",
"reason": {
"code": "logout",
"message": "The instance has been logged out."
}
},
"id": "682jcucv557qt0yarqivh",
"type": "instance.disconnected"
}
```
### `instance.forbidden`
A conexão da instância foi rejeitada pelo WhatsApp. Isso pode indicar que o número foi bloqueado, mas o evento sozinho não é uma confirmação de bloqueio: é necessária verificação antes de assumir isso.
Depois do evento, a instância fica `disconnected` e um novo QR Code costuma ser gerado logo em seguida (o evento `instance.qrcode` normalmente é emitido na sequência). Ao receber esse evento, reconecte a instância lendo o novo QR Code; se ele voltar a acontecer com frequência, revise as práticas de envio do número.
Este evento se aplica apenas a instâncias **não oficiais** (conectadas via QR Code). Instâncias com **API oficial (WABA)** não emitem este evento.
```json theme={null}
{
"created_at": "2025-07-29T13:51:49.224Z",
"data": {
"name": "Account Name",
"id": "551112341234",
"phone_number": "551112341234",
"lid": "123456789012345",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/..."
},
"id": "682jcucv557qt0yarqivh",
"type": "instance.forbidden"
}
```
### `message.received`
Uma mensagem foi recebida na instância. Para detalhamento completo de como é o formato do objeto mensagem verifique na página [Estrutura dos eventos > Mensagem](./event-schemas/message)
```json theme={null}
{
"created_at": "2024-09-14T13:55:46.420Z",
"data": {
"content": {
"text": "Oi"
},
"id": "3AAB4DA4297176B74E38",
"recipient": {
"name": "Recipient Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/...",
"type": "chat"
},
"sender": {
"name": "Sender Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/..."
},
"sent_at": "2024-09-14T13:55:46.000Z",
"type": "text"
},
"id": "y66lhiw5la6z3r8f1urm0",
"type": "message.received"
}
```
```json theme={null}
{
"created_at": "2025-01-30T13:28:15.771Z",
"data": {
"content": {
"view_once": false,
"media": {
"url": "https://zapsterapi.s3.us-east-1.amazonaws.com/..."
},
"text": "My image caption"
},
"id": "3EB0AA6B4A8B13C4CA44E4",
"recipient": {
"name": "Recipient Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/...",
"type": "chat"
},
"sender": {
"name": "Sender Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/..."
},
"sent_at": "2025-01-30T13:28:15.000Z",
"type": "image"
},
"id": "sepu74f9o9c3y8gq0ikbl",
"type": "message.received"
}
```
```json theme={null}
{
"created_at": "2025-01-30T13:28:15.771Z",
"data": {
"content": {
"view_once": false,
"media": {
// URL para arquivo de áudio MP3
"url": "https://zapsterapi.s3.us-east-1.amazonaws.com/..."
},
"text": ""
},
"id": "3EB0AA6B4A8B13C4CA44E4",
"recipient": {
"name": "Recipient Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/...",
"type": "chat"
},
"sender": {
"name": "Sender Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/..."
},
"sent_at": "2025-01-30T13:28:15.000Z",
"type": "audio"
},
"id": "sepu74f9o9c3y8gq0ikbl",
"type": "message.received"
}
```
```json theme={null}
{
"created_at": "2025-01-30T13:31:56.534Z",
"data": {
"content": {
"location": {
"address": "São Paulo, SP",
"latitude": -9.123456789123456,
"longitude": -40.123456789123456,
"mode": "static",
"name": "Centro de Artes"
}
},
"id": "3A8A44190C6F468A1E90",
"recipient": {
"name": "Recipient Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/...",
"type": "chat"
},
"sender": {
"name": "Sender Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/..."
},
"sent_at": "2025-01-30T13:31:56.000Z",
"type": "location"
},
"id": "8qmaixneh95c4vb6xm89k",
"type": "message.received"
}
```
```json theme={null}
{
"created_at": "2025-01-30T13:36:41.856Z",
"data": {
"content": {
"media": {
"metadata": {
"animated": true
},
"url": "https://zapsterapi.s3.us-east-1.amazonaws.com/..."
}
},
"id": "3AB26376707099366558",
"recipient": {
"name": "Recipient Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/...",
"type": "chat"
},
"sender": {
"name": "Sender Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/..."
},
"sent_at": "2025-01-30T13:36:41.000Z",
"type": "sticker"
},
"id": "3niukssdl9ca2qktbv9u6",
"type": "message.received"
}
```
```json theme={null}
{
"created_at": "2025-01-30T13:39:37.156Z",
"data": {
"content": {
"view_once": false,
"media": {
"metadata": {
"duration": 1,
"playback": true
},
"url": "https://zapsterapi.s3.us-east-1.amazonaws.com/..."
},
"text": "My video/gif caption"
},
"id": "3AB703F9740E34B5E110",
"recipient": {
"name": "Recipient Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/...",
"type": "chat"
},
"sender": {
"name": "Sender Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/..."
},
"sent_at": "2025-01-30T13:39:36.000Z",
"type": "video"
},
"id": "jlmnxdp63p03wrv2ynepn",
"type": "message.received"
}
```
Observe a propriedade `data.content.quoted`, ela representa a citação ou marcação de quem está respondendo e tem o mesmo formato de uma `message.received`.
```json theme={null}
{
"created_at": "2025-02-02T21:18:28.437Z",
"data": {
"content": {
"view_once": false,
"quoted": {
"content": {
"text": "🙏"
},
"id": "3EB0E8FE1559DADE848EF5",
"recipient": {
"name": "Recipient Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/...",
"type": "chat"
},
"sender": {
"name": "Sender Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/..."
},
"type": "text"
},
"text": "My reply to quoted message"
},
"id": "3EB090C9F062EF62F1D924",
"recipient": {
"name": "Recipient Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/...",
"type": "chat"
},
"sender": {
"name": "Sender Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/..."
},
"sent_at": "2025-02-02T21:18:28.000Z",
"type": "text"
},
"id": "wy43uruj26ylse1cs38ps",
"type": "message.received"
}
```
Observe que o status respondido ficará dentro de `data.content.quoted` que terá o mesmo formato de uma `message.received`, a grande diferença aqui é que você verá uma nova propriedade `data.content.quoted.content.origin` sendo o seu valor igual à `status`.
Agora existe um evento dedicado [`status.reply`](#status-reply) para respostas a status. Ele é emitido **além** do `message.received` (que continua sendo disparado, sem quebra de compatibilidade) e traz um formato enxuto, com o essencial do status em `data.content.status`. Prefira assiná-lo se você só precisa reagir a respostas de status.
Em alguns casos você pode encontrar uma variação do payload contendo uma propriedade `background_color` para status que são postado em formato de texto, seu valor representará a cor do fundo (background), contendo no formato decimal, hexadecimal com e sem o canal alfa (transparência).
```json theme={null}
{
"background_color": {
"decimal": 4283864831,
"hex_argb": "#FF5696FF", // com o canal alfa
"hex_rgb": "#5696FF" // sem o canal alfa
}
}
```
```json theme={null}
{
"created_at": "2025-02-02T21:14:47.330Z",
"data": {
"content": {
"view_once": false,
"quoted": {
"content": {
"view_once": false,
"origin": "status",
"media": {
"url": "https://zapsterapi.s3.us-east-1.amazonaws.com/..."
},
"text": "My status caption"
},
"id": "E7531155884C68EAC1F3F1774E2CABD2",
"recipient": {
"name": "Recipient Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/...",
"type": "chat"
},
"sender": {
"name": "Sender Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/..."
},
"type": "image"
},
"text": "Answering to the posted status XYZ"
},
"id": "3EB02ADDF16B28F7CA3753",
"recipient": {
"name": "Recipient Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/...",
"type": "chat"
},
"sender": {
"name": "Sender Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/..."
},
"sent_at": "2025-02-02T21:14:46.000Z",
"type": "text"
},
"id": "p7ly4vp5jrlsw3yfm7pt2",
"type": "message.received"
}
```
Se a propriedade `waid` (ela pode ser ausente) estiver presente dentro de `data.content.contacts.phones` isso pode siginificar que o telefone / contato recebido tem um whatsapp válido.
```json theme={null}
{
"created_at": "2025-02-02T21:33:48.334Z",
"data": {
"content": {
"contacts": [
{
"vcard": "BEGIN:VCARD\nVERSION:3.0\nN:Test;Contato;;;\nFN:Contato Test\nTEL;type=CELL;waid=5511123451234:+55 11 12345-1234\nEND:VCARD",
"display_name": "Contato Test",
"first_name": "Contato",
"last_name": "Test",
"phones": [
{
"formatted_value": "+55 11 12345-1234",
"waid": "5511123451234"
}
]
}
]
},
"id": "3EB0B2B79F42613ACE4E",
"recipient": {
"name": "Recipient Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/...",
"type": "chat"
},
"sender": {
"name": "Sender Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/..."
},
"sent_at": "2025-02-02T21:33:47.000Z",
"type": "vcard"
},
"id": "u0hyeyfkiwfmjdwf937cs",
"type": "message.received"
}
```
As mensagens com botões poderão chegar com os tipos **text**, **image** ou **video** e sempre acompanhada da propriedade **buttons** em seu conteudo (`data.content`).
```json theme={null}
{
"created_at": "2025-03-08T13:18:10.215Z",
"data": {
"content": {
"buttons": [
{
"id": "2ec4cf13-6c5c-48b3-af42-cc572d22c2b2",
"label": "Sim",
"type": "reply"
},
{
"id": "ccebc70b-aefd-492f-a19c-94b1384964be",
"label": "Não",
"type": "reply"
}
],
"text": "Você gostaria de informar seu endereço agora?"
},
"id": "3EB0303793FBDDACB97101",
"recipient": {
"name": "Recipient Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/...",
"type": "chat"
},
"sender": {
"name": "Sender Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/..."
},
"sent_at": "2025-03-08T13:18:08.000Z",
"type": "text"
},
"id": "n0co5zard1myk7wx07cks",
"type": "message.received"
}
```
Assim como o exemplo acima, o tipo de mensagem chegará como **text**, **video** ou **image** porém a propriedade **button\_reply** (`data.button_reply`) mostrará qual botão o usuário pressionou.
```json theme={null}
{
"created_at": "2025-03-08T13:43:34.060Z",
"data": {
"content": {
"text": "Sim",
"button_reply": {
"label": "Sim",
"type": "reply",
"id": "2ec4cf13-6c5c-48b3-af42-cc572d22c2b2"
},
"quoted": {
"content": {
"buttons": [
{
"label": "Sim",
"type": "reply",
"id": "2ec4cf13-6c5c-48b3-af42-cc572d22c2b2"
},
{
"label": "Não",
"type": "reply",
"id": "ccebc70b-aefd-492f-a19c-94b1384964be"
}
],
"text": "Você gostaria de informar seu endereço agora?"
},
"id": "3EB0303793FBDDACB97101",
"recipient": {
"name": "Recipient Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/...",
"type": "chat"
},
"sender": {
"name": "Sender Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/..."
},
"sent_at": "2025-03-08T13:18:08.000Z",
"type": "text"
}
},
"id": "A09627FC7D6444122AFF8AB0AB59BA6A",
"recipient": {
"name": "Recipient Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/...",
"type": "chat"
},
"sender": {
"name": "Sender Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/..."
},
"sent_at": "2025-03-08T13:43:31.000Z",
"type": "text"
},
"id": "kckozfp7fpn4cfxfbsglu",
"type": "message.received"
}
```
```json theme={null}
{
"created_at": "2025-03-08T17:54:47.475Z",
"data": {
"content": {
"list_options": {
"button_label": "Abrir lista de opções",
"sections": [
{
"description": null,
"options": [
{
"description": "Descrição, opção 1",
"id": "1",
"title": "Opção 1"
},
{
"description": "Descrição, opção 2",
"id": "2",
"title": "Opção 2"
}
],
"title": "Opções disponíveis"
}
]
},
"text": "Selecione a opção que melhor encaixa para você!"
},
"id": "3EB0D33E50E19D78A5A789",
"recipient": {
"name": "Recipient Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/...",
"type": "chat"
},
"sender": {
"name": "Sender Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/..."
},
"sent_at": "2025-03-08T17:54:46.000Z",
"type": "text"
},
"id": "f7wjjrkpd1d1nyjl3n5kl",
"type": "message.received"
}
```
Assim como o exemplo acima, o tipo de mensagem chegará como **text** porém a propriedade **list\_reply** (`data.list_reply`) mostrará qual opção o usuário selecionou.
```json theme={null}
{
"created_at": "2025-03-08T18:15:09.450Z",
"data": {
"content": {
"list_reply": {
"title": "Opção 2",
"description": "Descrição, opção 2",
"id": "2"
},
"text": "Descrição, opção 2",
"quoted": {
"content": {
"list_options": {
"button_label": "Abrir lista de opções",
"sections": [
{
"description": null,
"options": [
{
"description": "Descrição, opção 1",
"id": "1",
"title": "Opção 1"
},
{
"description": "Descrição, opção 2",
"id": "2",
"title": "Opção 2"
}
],
"title": "Opções disponíveis"
}
]
},
"text": "Selecione a opção que melhor encaixa para você!"
}
"id": "3EB0D33E50E19D78A5A789",
"recipient": {
"name": "Recipient Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/...",
"type": "chat"
},
"sender": {
"name": "Sender Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/..."
},
"sent_at": "2025-03-08T17:54:46.000Z",
"type": "text"
}
},
"id": "3EB081D5F40D11F1C39815",
"recipient": {
"name": "Recipient Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/...",
"type": "chat"
},
"sender": {
"name": "Sender Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/..."
},
"sent_at": "2025-03-08T18:15:08.000Z",
"type": "text"
},
"id": "9sj082811g9xm1bja68fp",
"type": "message.received"
}
```
Disponível apenas em instâncias com **API oficial (WABA)**, já que WhatsApp Flows não existem no WhatsApp não oficial. A resposta do formulário fica namespaced em `data.content.flow_reply` (`flow_token`, `response` e `response_raw`) e `data.type` vem como `flow_reply`.
Agora existe um evento dedicado [`message.flow_reply`](#message-flow-reply) para respostas de Flow. Ele é emitido **além** do `message.received` (que continua sendo disparado, sem quebra de compatibilidade) e traz os mesmos campos na raiz de `data.content`. Prefira assiná-lo se você só precisa reagir a respostas de formulário.
```json theme={null}
{
"created_at": "2026-07-29T00:16:04.000Z",
"data": {
"content": {
"flow_reply": {
"flow_token": "pedido-8231",
"response": {
"tipo_ocorrencia": "manutencao_refrigeracao",
"descricao": "despressurização"
},
"response_raw": "{\"tipo_ocorrencia\":\"manutencao_refrigeracao\",\"descricao\":\"despressuriza\\u00e7\\u00e3o\",\"flow_token\":\"pedido-8231\"}"
},
"quoted": {
"id": "wamid.HBgMNTU4..."
}
},
"id": "wamid.HBgMNTU4NzgxMTcwMjYxFQIAEhgg...",
"recipient": {
"name": "Recipient Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/...",
"type": "chat"
},
"sender": {
"name": "Sender Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/..."
},
"sent_at": "2026-07-29T00:16:04.000Z",
"type": "flow_reply"
},
"id": "p7ly4vp5jrlsw3yfm7pt2",
"type": "message.received"
}
```
### `message.flow_reply`
Emitido quando alguém conclui um **WhatsApp Flow** (formulário nativo do WhatsApp) enviado pela sua instância. É um evento dedicado e assinável, pensado para quem precisa reagir só a respostas de formulário, sem inspecionar todas as `message.received`.
Este evento está disponível apenas em instâncias com **API oficial (WABA)**. WhatsApp Flows não existem no WhatsApp não oficial.
Este evento **não substitui** o `message.received`: uma resposta de Flow continua sendo disparada também como `message.received`, com o conteúdo namespaced em `data.content.flow_reply` (mesmos campos `flow_token`, `response` e `response_raw`) e `data.type` igual a `flow_reply`. O `message.flow_reply` é emitido **em adição**, trazendo esses mesmos campos direto na raiz de `data.content`, para quem só precisa assinar respostas de formulário.
O conteúdo da resposta fica em `data.content`:
* `flow_token`: o token que você definiu ao enviar o Flow, usado para correlacionar a resposta com o envio original. Pode vir `null` quando o Flow não devolve token. Evite colocar dados pessoais nesse token: diferente das respostas do formulário, ele não é tratado como dado sensível pela plataforma.
* `response`: as respostas do formulário já parseadas em objeto. As chaves são exatamente as definidas por você no Flow JSON, sem nenhuma transformação de chave ou valor. O `flow_token` não aparece dentro de `response`, ele já vem promovido para o campo de topo.
* `response_raw`: a string JSON original enviada pela Meta, sem nenhum tratamento. Está sempre presente, mesmo quando o parse deu certo, e serve para quem quer aplicar o próprio parser ou fazer auditoria byte a byte da submissão. Se o JSON vier malformado, `response` chega como `{}` e `response_raw` preserva a submissão original.
* `quoted` (quando presente): a mensagem de Flow original que foi respondida, no mesmo formato de citação usado em `message.received`.
```json theme={null}
{
"created_at": "2026-07-29T00:16:04.000Z",
"data": {
"content": {
"flow_token": "pedido-8231",
"response": {
"tipo_ocorrencia": "manutencao_refrigeracao",
"descricao": "despressurização"
},
"response_raw": "{\"tipo_ocorrencia\":\"manutencao_refrigeracao\",\"descricao\":\"despressuriza\\u00e7\\u00e3o\",\"flow_token\":\"pedido-8231\"}",
"quoted": {
"id": "wamid.HBgMNTU4..."
}
},
"id": "wamid.HBgMNTU4NzgxMTcwMjYxFQIAEhgg...",
"recipient": {
"name": "Recipient Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/...",
"type": "chat"
},
"sender": {
"name": "Sender Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/..."
},
"sent_at": "2026-07-29T00:16:04.000Z",
"type": "flow_reply"
},
"id": "p7ly4vp5jrlsw3yfm7pt2",
"type": "message.flow_reply"
}
```
### `message.sent`
Uma mensagem foi enviada da instância mensagem pode ter sido enviada através do Whatsapp ou através da API da Zapster.
Você consegue identificar facilmente a origem do envio olhando para a propriedade `data.origin` que tem 2 valores possíveis (`zapsterapi` ou `whatsapp`), que identificarão a origem do envio da mensagem.
Em números **oficiais (WABA)** com o recurso de **Coexistência** da Meta ativo, as mensagens que a equipe envia pelo próprio **WhatsApp Business App** (ou por um dispositivo vinculado) também chegam como `message.sent` com `data.origin` igual a `whatsapp`. Mensagens enviadas pela API têm `data.origin` igual a `zapsterapi`.
Para detalhamento completo de como é o formato do objeto mensagem verifique na página [Estrutura dos eventos > Mensagem](./event-schemas/message)
```json theme={null}
{
"created_at": "2024-09-14T13:55:46.420Z",
"data": {
"content": {
"text": "Oi"
},
"id": "3AAB4DA4297176B74E38",
"recipient": {
"name": "Recipient Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/...",
"type": "chat"
},
"sender": {
"name": "Sender Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/..."
},
"sent_at": "2024-09-14T13:55:46.000Z",
"origin": "zapsterapi",
"type": "text"
},
"id": "y66lhiw5la6z3r8f1urm0",
"type": "message.sent"
}
```
### `message.delivered`
Indica que a mensagem foi entregue ao destinatário.
```json theme={null}
{
"created_at": "2025-09-03T13:38:17.798Z",
"data": {
"content": {
"text": "ok"
},
"id": "3ADC5C4A6F9DABCDEF25",
"recipient": {
"name": "Recipient Name",
"id": "5511999999999",
"profile_picture": "https://zapsterapi...",
"type": "chat"
},
"sender": {
"name": "Sender Name",
"id": "5511999990000",
"profile_picture": "https://zapsterapi..."
},
"sent_at": "2025-09-03T13:38:17.000Z",
"type": "text"
},
"id": "YHSC28q7sD32zm0ier3BQ",
"type": "message.delivered"
}
```
### `message.read`
Indica que a mensagem foi lida pelo destinatário.
Nas configurações de privacidade da instância, se a confirmação de leitura estiver desativada, você não poderá ver nem exibir confirmações de leitura. Então o evento de webhook não irá disparar.
```json theme={null}
{
"created_at": "2025-09-03T14:36:46.585Z",
"data": {
"content": {
"text": "Message readed"
},
"id": "3920A9F9FAFEC78CBE1C26E6ABCDEF25",
"recipient": {
"id": "5511999999999",
"profile_picture": "https://zapsterapi.s3...",
"name": "Recipient Name",
"type": "chat"
},
"sender": {
"name": "Sender Name",
"id": "5511999999999",
"profile_picture": "https://zapsterapi.s3..."
},
"sent_at": "2025-09-03T14:07:17.000Z",
"type": "text"
},
"id": "Cj41hzsvNUEr6isfHBrHJ",
"type": "message.read"
}
```
### `message.failed`
O WhatsApp recusou a entrega da mensagem. O evento traz o motivo da recusa em `data.errors` e, quando a mensagem foi enviada pela Zapster, também o conteúdo original em `data.content`.
Este evento está disponível apenas em instâncias com **API oficial (WABA)**. O WhatsApp não oficial não devolve confirmação de falha de entrega, então a assinatura de `message.failed` é recusada ao criar ou atualizar um webhook de instância não oficial.
Cada item de `data.errors` traz `code` e `title` sempre preenchidos, e `message` e `details` quando a Meta os envia. Use o `code` para tratar a falha de forma programática (por exemplo, `131026` indica mensagem não entregue ao destinatário, e `131047` indica que a janela de atendimento expirou e um template é necessário) e o `details` para registrar a explicação completa.
```json theme={null}
{
"created_at": "2026-07-29T13:41:02.000Z",
"data": {
"content": {
"text": "Seu pedido saiu para entrega"
},
"errors": [
{
"code": 131026,
"title": "Message undeliverable",
"message": "Message Undeliverable",
"details": "Message could not be delivered to the recipient."
}
],
"id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjcxQ...",
"recipient": {
"bsuid": null,
"id": "5511999999999",
"name": "Recipient Name",
"phone_number": "5511999999999",
"profile_picture": null,
"type": "chat"
},
"sender": {
"bsuid": null,
"id": "5511999990000",
"name": null,
"phone_number": "5511999990000",
"profile_picture": "https://zapsterapi...",
"type": "chat"
},
"sent_at": "2026-07-29T13:41:00.000Z",
"type": "text"
},
"id": "kQ2s7bWfvJ1p0aTmz9xLr",
"type": "message.failed"
}
```
### `message.deleted`
Indica que uma mensagem foi apagada (para mim ou para todos) na conversa.
```json theme={null}
{
"created_at": "2025-09-03T14:15:05.588Z",
"data": {
"content": {
"text": "teste"
},
"id": "3A4B7D720682ABCDEF25",
"recipient": {
"approval_mode": "auto_approve",
"description": null,
"id": "120363402123456789",
"invite_code": null,
"invite_mode": "all_members",
"is_announcement": false,
"is_community": false,
"is_restricted": false,
"name": "Group Name",
"owner": {
"name": "Owner Name",
"id": "5511999999999",
"profile_picture": "https://zapsterapi.s3..."
},
"profile_picture": null,
"total_participants": 2,
"type": "group"
},
"sender": {
"name": "Sender Name",
"id": "5511999990000",
"profile_picture": "https://zapsterapi.s3..."
},
"sent_at": "2025-09-03T14:10:04.000Z",
"type": "text"
},
"id": "ToMoKaeAtAYhHLhhI6GNY",
"type": "message.deleted"
}
```
### `message.reaction`
Indica que uma reação (emoji) foi aplicada a uma mensagem.
```json theme={null}
{
"created_at": "2025-09-02T20:57:57.182Z",
"data": {
"id": "3EB0220A8B6B28ABCDEF25",
"reacted_at": "2025-09-02T23:35:05.000Z",
"reacted_by": {
"name": "Recipient Name",
"id": "5511999999999",
"profile_picture": "https://zapsterapi.s3..."
},
"reacted_message": {
"content": {
"text": "teste reaction"
},
"id": "3AC0C55193850CB8F36C",
"recipient": {
"name": "Recipient Name",
"id": "5511999999999",
"profile_picture": "https://zapsterapi.s3...",
"type": "chat"
},
"sender": {
"name": "Sender Name",
"id": "5511999990000",
"profile_picture": "https://zapsterapi.s3..."
},
"sent_at": "2025-09-02T23:34:58.000Z",
"type": "text"
},
"reaction": "😮"
},
"id": "l1j0pt4wofz904u0456sp",
"type": "message.reaction"
}
```
Reações a mensagens com mais de 72 horas o objeto reacted\_message não será enviado com todas informações, mas sim apenas com o ID da mensagem que foi reagida.
```json theme={null}
{
"created_at": "2025-09-02T17:28:39.272Z",
"data": {
"id": "3EB0353F4E0589D1AFC7BF",
"reacted_at": "2025-09-02T17:28:38.000Z",
"reacted_by": {
"name": "Reacted by Name",
"id": "551112341234",
"profile_picture": "..."
},
"reacted_message": {
"id": "3EB0308CD725A43924946B"
},
"reaction": "😂"
},
"id": "nmy2s3rq9yz5rysq692bw",
"type": "message.reaction"
}
```
### `message.pinned`
Indica que uma mensagem foi fixada na conversa/grupo.
```json theme={null}
{
"created_at": "2025-09-02T20:57:57.182Z",
"data": {
"author": {
"name": "Author Name",
"id": "5511999999999",
"profile_picture": "https://zapsterapi.s3..."
},
"message": {
"duration": 604800,
"content": {
"text": "Dia 19 meeting de boas vindas"
},
"id": "3A73212D3B60ABCDEF25",
"recipient": {
"approval_mode": "auto_approve",
"description": null,
"id": "120363420123456789",
"invite_code": null,
"invite_mode": "all_members",
"is_announcement": false,
"is_community": false,
"is_restricted": false,
"name": "Group Name",
"owner": {
"name": "Owner Name",
"id": "5511999999999",
"profile_picture": "https://zapsterapi.s3..."
},
"profile_picture": null,
"total_participants": 4,
"type": "group"
},
"sender": {
"name": "Sender Name",
"id": "5511999999999",
"profile_picture": "https://zapsterapi.s3..."
},
"sent_at": "2025-09-02T22:17:50.000Z",
"type": "text"
}
},
"id": "l1j0pt4wofz904u0456sp",
"type": "message.pinned"
}
```
### `message.unpinned`
Indica que uma mensagem foi desafixada.
```json theme={null}
{
"created_at": "2025-09-02T20:57:57.182Z",
"data": {
"author": {
"name": "Author Name",
"id": "5511999999999",
"profile_picture": "https://zapsterapi.s3..."
},
"message": {
"content": {
"text": "Meeting de boas vindas"
},
"id": "3A73212D3B60ABCDEF25",
"recipient": {
"approval_mode": "auto_approve",
"description": null,
"id": "120363420123456789",
"invite_code": null,
"invite_mode": "all_members",
"is_announcement": false,
"is_community": false,
"is_restricted": false,
"name": "Group name",
"owner": {
"name": "Owner Name",
"id": "5511999999999",
"profile_picture": "https://zapsterapi.s3..."
},
"profile_picture": null,
"total_participants": 4,
"type": "group"
},
"sender": {
"name": "Sender Name",
"id": "5511999999999",
"profile_picture": "https://zapsterapi.s3..."
},
"sent_at": "2025-09-02T22:17:50.000Z",
"type": "text"
}
},
"id": "l1j0pt4wofz904u0456sp",
"type": "message.unpinned"
}
```
### `instance.mentioned`
Indica que sua instância foi mencionada ("@...") em uma conversa/grupo.
```json theme={null}
{
"created_at": "2025-09-02T20:57:57.182Z",
"data": {
"author": {
"name": "Author Name",
"id": "5511999999999",
"profile_picture": "https://zapsterapi.s3..."
},
"mentioned_at": "2025-09-02T22:17:43.000Z",
"message": {
"content": {
"mentions": [
{
"name": "Mentioned Name",
"id": "5511999999999",
"profile_picture": "https://zapsterapi.s3..."
}
],
"text": "@5511999999999"
},
"id": "90C1979C3AA24B5FD8868523ABCDEF25",
"sent_at": "2025-09-02T22:17:43.000Z",
"type": "text"
},
"recipient": {
"approval_mode": "auto_approve",
"description": null,
"id": "120363420123456789",
"invite_code": null,
"invite_mode": "all_members",
"is_announcement": false,
"is_community": false,
"is_restricted": false,
"name": "Group Name",
"owner": {
"name": "Owner Name",
"id": "5511999999999",
"profile_picture": "https://zapsterapi.s3..."
},
"profile_picture": null,
"total_participants": 4,
"type": "group"
}
},
"id": "l1j0pt4wofz904u0456sp",
"type": "instance.mentioned"
}
```
### `status.reply`
Emitido quando alguém responde a um **status** publicado pela sua instância. É um evento dedicado e assinável, pensado para quem precisa automatizar em cima de respostas de status sem inspecionar todas as `message.received`.
Este evento **não substitui** o `message.received`: uma resposta a status continua sendo disparada também como `message.received` (com o status em `data.content.quoted`, no formato completo de mensagem). O `status.reply` é emitido **em adição**, com um formato enxuto e dedicado.
Diferente do `message.received`, o `status.reply` tem um formato **enxuto**: o status respondido vem em `data.content.status` (`id`, `type`, `text`, `media`, `background_color`) — sem o `data.content.quoted` redundante — e **não há `data.sender`**, porque nesse contexto ele seria sempre igual ao `data.recipient` (o contato que respondeu). A resposta em si fica no topo: `data.content.text`/`media`, `data.recipient`, `data.sent_at` e `data.type`.
Respostas de status podem conter **mídia** (imagem, vídeo, áudio, arquivo), assim como o próprio status respondido. A mídia da resposta vem em `data.content.media`; a mídia do status respondido em `data.content.status.media`. Status de texto trazem `data.content.status.background_color` com a cor de fundo nos formatos decimal e hexadecimal (com e sem canal alfa).
```json theme={null}
{
"created_at": "2025-02-02T21:14:47.330Z",
"data": {
"content": {
"text": "Amei! Quero aproveitar",
"status": {
"id": "E7531155884C68EAC1F3F1774E2CABD2",
"type": "text",
"text": "Promoção só hoje!",
"background_color": {
"decimal": 4283864831,
"hex_argb": "#FF5696FF",
"hex_rgb": "#5696FF"
}
}
},
"id": "3EB02ADDF16B28F7CA3753",
"recipient": {
"name": "Contact Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/...",
"lid": "137585536053271",
"phone_number": "551112341234",
"type": "chat"
},
"sent_at": "2025-02-02T21:14:46.000Z",
"type": "text"
},
"id": "p7ly4vp5jrlsw3yfm7pt2",
"type": "status.reply"
}
```
```json theme={null}
{
"created_at": "2025-02-02T21:14:47.330Z",
"data": {
"content": {
"text": "Que legal!",
"status": {
"id": "E7531155884C68EAC1F3F1774E2CABD2",
"type": "image",
"text": "My status caption",
"media": {
"url": "https://zapsterapi.s3.us-east-1.amazonaws.com/..."
}
}
},
"id": "3EB02ADDF16B28F7CA3753",
"recipient": {
"name": "Contact Name",
"id": "551112341234",
"profile_picture": "https://zapsterapi.s3.us-east-1.amazonaws.com/...",
"lid": "137585536053271",
"phone_number": "551112341234",
"type": "chat"
},
"sent_at": "2025-02-02T21:14:46.000Z",
"type": "text"
},
"id": "p7ly4vp5jrlsw3yfm7pt2",
"type": "status.reply"
}
```
### `instance.qrcode`
Notifica quando um novo QR Code é gerado/atualizado para a instância.
```json theme={null}
{
"created_at": "2025-09-02T20:57:57.182Z",
"data": {
"qrcode": "2@6t2v/gh1D+Ru+RnuEJf9hwjOEyar29s/1x6aWvfLvN38G/g..."
},
"id": "7jatr6a3hnn1qlxoz2ccc",
"type": "instance.qrcode"
}
```
### `group.created`
Indica que um novo grupo foi criado.
```json theme={null}
{
"id": "2711aqyqcy9ooavsvnu0e",
"data": {
"id": "120363420123456789",
"name": "Group Name",
"owner": {
"id": "5511999999999",
"name": "Owner Name",
"profile_picture": "https://zapsterapi.s3..."
},
"description": null,
"invite_code": "KlMCWzU3TakKghDpKFgVbr",
"invite_mode": "all_members",
"is_community": false,
"approval_mode": "requires_approval",
"is_restricted": false,
"is_announcement": false,
"profile_picture": null,
"total_participants": 4
},
"type": "group.created",
"created_at": "2025-09-02T21:52:34.409Z"
}
```
### `group.updated`
Indica que os dados do grupo foram atualizados (nome, foto, descrição, etc.).
```json theme={null}
{
"created_at": "2025-09-02T21:37:49.741Z",
"data": {
"approval_mode": "requires_approval",
"description": "Description of group",
"id": "120363020089898070",
"invite_code": "KxBnzvpAzFZsMnHJmj9EK5",
"invite_mode": "admins_only",
"is_announcement": false,
"is_community": false,
"is_restricted": false,
"name": "Group Name",
"owner": {
"name": "Owner Name",
"id": "5511999999999",
"profile_picture": "https://zapsterapi.s3..."
},
"profile_picture": "https://zapsterapi.s3...",
"total_participants": 3
},
"id": "l1j0pt4wofz904u0456sp",
"type": "group.updated"
}
```
### `group.participants_added`
Indica que um ou mais participantes foram adicionados ao grupo.
```json theme={null}
{
"created_at": "2025-09-02T20:57:57.182Z",
"data": {
"author": {
"name": "Author Name",
"id": "5511999999999",
"profile_picture": "https://zapsterapi.s3..."
},
"group": {
"approval_mode": "requires_approval",
"description": null,
"id": "120363020123456789",
"invite_code": "KxBnzvpAzFZsMnHJmj9EK5",
"invite_mode": "admins_only",
"is_announcement": false,
"is_community": false,
"is_restricted": false,
"name": "Group Name",
"owner": {
"name": "Owner Name",
"id": "5511999999999",
"profile_picture": "https://zapsterapi.s3..."
},
"profile_picture": "https://zapsterapi.s3...",
"total_participants": 3
},
"participants": [
{
"name": "Participants Name",
"id": "5511999999999",
"profile_picture": "https://zapsterapi.s3..."
}
]
},
"id": "l1j0pt4wofz904u0456sp",
"type": "group.participants_added"
}
```
### `group.participants_removed`
Indica que participantes foram removidos do grupo.
```json theme={null}
{
"created_at": "2025-09-02T20:57:57.182Z",
"data": {
"author": {
"name": "Author Name",
"id": "5511999999999",
"profile_picture": "https://zapsterapi.s3..."
},
"group": {
"approval_mode": "requires_approval",
"description": null,
"id": "120363020123456789",
"invite_code": "KxBnzvpAzFZsMnHJmj9EK5",
"invite_mode": "admins_only",
"is_announcement": false,
"is_community": false,
"is_restricted": false,
"name": "Group Name",
"owner": {
"name": "Owner Name",
"id": "5511999999999",
"profile_picture": "https://zapsterapi.s3..."
},
"profile_picture": "https://zapsterapi.s3...",
"total_participants": 3
},
"participants": [
{
"name": "Participant Name",
"id": "5511999999999",
"profile_picture": "https://zapsterapi.s3..."
}
]
},
"id": "l1j0pt4wofz904u0456sp",
"type": "group.participants_removed"
}
```
### `group.participants_promoted`
Indica que participantes foram promovidos a administradores.
```json theme={null}
{
"created_at": "2025-09-02T20:57:57.182Z",
"data": {
"author": {
"name": "Author Name",
"id": "5511999999999",
"profile_picture": "https://zapsterapi.s3..."
},
"group": {
"approval_mode": "requires_approval",
"description": null,
"id": "120363020123456789",
"invite_code": "KxBnzvpAzFZsMnHJmj9EK5",
"invite_mode": "admins_only",
"is_announcement": false,
"is_community": false,
"is_restricted": false,
"name": "Group Name",
"owner": {
"name": "Owner Name",
"id": "5511999999999",
"profile_picture": "https://zapsterapi.s3..."
},
"profile_picture": "https://zapsterapi.s3...",
"total_participants": 3
},
"participants": [
{
"name": "Participant Name",
"id": "5511999999999",
"profile_picture": "https://zapsterapi.s3..."
}
]
},
"id": "l1j0pt4wofz904u0456sp",
"type": "group.participants_promoted"
}
```
### `group.participants_demoted`
Indica que participantes foram rebaixados de administradores para membros.
```json theme={null}
{
"created_at": "2025-09-02T20:57:57.182Z",
"data": {
"author": {
"name": "Author Name",
"id": "5511999999999",
"profile_picture": "https://zapsterapi.s3..."
},
"group": {
"approval_mode": "requires_approval",
"description": null,
"id": "120363020123456789",
"invite_code": "KxBnzvpAzFZsMnHJmj9EK5",
"invite_mode": "admins_only",
"is_announcement": false,
"is_community": false,
"is_restricted": false,
"name": "Group Name",
"owner": {
"name": "Owner Name",
"id": "5511999999999",
"profile_picture": "https://zapsterapi.s3..."
},
"profile_picture": "https://zapsterapi.s3...",
"total_participants": 3
},
"participants": [
{
"name": "Participant Name",
"id": "5511999999999",
"profile_picture": "https://zapsterapi.s3..."
}
]
},
"id": "l1j0pt4wofz904u0456sp",
"type": "group.participants_demoted"
}
```