Eventos Disponíveis

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.

Exemplo

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

Exemplo

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

Exemplo

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

Exemplo: Mensagem de texto

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

Exemplo: Mensagem com imagem

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

Exemplo: Mensagem com áudio

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

Exemplo: Mensagem de localização

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

Exemplo: Mensagem com Sticker

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

Exemplo: Mensagem com GIF ou Vídeo

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

Exemplo: Mensagem "quoted" (ou resposta) para outra mensagem

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.

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

Exemplo: Mensagem resposta à um status

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

{
  "background_color": {
    "decimal": 4283864831,
    "hex_argb": "#FF5696FF", // com o canal alfa
    "hex_rgb": "#5696FF" // sem o canal alfa
  }
}

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

Exemplo: Mensagem com vcard (contatos)

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.

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

Exemplo: Mensagem com botões

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

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

Exemplo: Mensagem resposta à botões

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.

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

Exemplo: Mensagem com lista de opções

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

Exemplo: Mensagem resposta à lista de opções

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.

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

Exemplo: Resposta de um WhatsApp Flow

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

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

Exemplo

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

Exemplo: Mensagem de texto

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

Exemplo

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

Ative ou desative a confirmação de leitura

Exemplo

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

Exemplo

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

Exemplo

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

Exemplo

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

Exemplo

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

Exemplo

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

Exemplo

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

Exemplo

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

Exemplo: Resposta a um status de texto

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

Exemplo: Resposta a um status de mídia (imagem)

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

Exemplo

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

Exemplo

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

Exemplo

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

Exemplo

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

Exemplo

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

Exemplo

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

Exemplo

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

Introdução

Conceitos

Webhooks

Integrações

Guias

Número 555 da Meta

`instance.connected`

`instance.disconnected`

`instance.forbidden`

`message.received`

`message.flow_reply`

`message.sent`

`message.delivered`

`message.read`

`message.failed`

`message.deleted`

`message.reaction`

`message.pinned`

`message.unpinned`

`instance.mentioned`

`status.reply`

`instance.qrcode`

`group.created`

`group.updated`

`group.participants_added`

`group.participants_removed`

`group.participants_promoted`

`group.participants_demoted`

​instance.connected

​instance.disconnected

​instance.forbidden

​message.received

​message.flow_reply

​message.sent

​message.delivered

​message.read

​message.failed

​message.deleted

​message.reaction

​message.pinned

​message.unpinned

​instance.mentioned

​status.reply

​instance.qrcode

​group.created

​group.updated

​group.participants_added

​group.participants_removed

​group.participants_promoted

​group.participants_demoted

`instance.connected`

`instance.disconnected`

`instance.forbidden`

`message.received`

`message.flow_reply`

`message.sent`

`message.delivered`

`message.read`

`message.failed`

`message.deleted`

`message.reaction`

`message.pinned`

`message.unpinned`

`instance.mentioned`

`status.reply`

`instance.qrcode`

`group.created`

`group.updated`

`group.participants_added`

`group.participants_removed`

`group.participants_promoted`

`group.participants_demoted`