Eventos
Receba eventos de WhatsApp em tempo real com Webhooks e WebSockets: estrutura do payload, HMAC, novas tentativas e lista completa de eventos.
Para notificar sua aplicação sobre eventos de WhatsApp, você pode usar Webhooks e WebSockets.
Webhooks
Os webhooks permitem que duas aplicações se comuniquem em tempo real: quando ocorre um evento, a Wazend envia uma requisição HTTP POST para sua URL.
Webhooks por sessão
Configure os webhooks por sessão na configuração da sessão:
{
"name": "S0001",
"config": {
"webhooks": [
{
"url": "https://tu-servidor.com/webhook",
"events": ["message"],
"hmac": { "key": "tu-clave-secreta" },
"retries": {
"policy": "constant",
"delaySeconds": 2,
"attempts": 15
},
"customHeaders": [
{ "name": "X-Mi-Header", "value": "Valor" }
]
}
]
}
}Novas tentativas
Políticas de nova tentativa disponíveis:
constant— mesmo atraso entre tentativas (2, 2, 2).linear— retrocesso linear (2, 4, 6, 8).exponential— retrocesso exponencial com jitter.
Headers
Cada webhook inclui estes headers:
X-Webhook-Request-Id— ID único da requisição.X-Webhook-Timestamp— timestamp Unix em ms.X-Webhook-Hmac— código de autenticação do corpo (se você usar HMAC).X-Webhook-Hmac-Algorithm— algoritmo usado (sha512).
Autenticação HMAC
Defina sua chave secreta em config.hmac.key e verifique a assinatura no header X-Webhook-Hmac (algoritmo sha512) contra o corpo da requisição.
{
"name": "S0001",
"config": {
"webhooks": [
{
"url": "https://tu-servidor.com/webhook",
"events": ["message"],
"hmac": { "key": "tu-clave-secreta" }
}
]
}
}Verifique sempre a assinatura
Valide a assinatura HMAC para proteger seu endpoint contra requisições maliciosas.
Exemplos
Você pode automatizar fluxos com n8n.
WebSockets
Use WebSockets para receber mensagens em tempo real.
# Ouvir todas as sessões e eventos
websocat -E wss://latam-1.wazend.net/ws
# Com API key
websocat -E wss://latam-1.wazend.net/ws?x-api-key=123
# Ouvir eventos específicos
websocat -E "wss://latam-1.wazend.net/ws?session=*&events=session.status&events=message"
# Ouvir uma sessão específica
websocat -E "wss://latam-1.wazend.net/ws?session=S0001&events=session.status"Parâmetros:
session— nome da sessão ou*para todas.events— lista de eventos ou*.x-api-key— sua API key.
Estrutura do payload
{
"id": "evt_1111111111111111111111111111",
"timestamp": 1741249702485,
"event": "message",
"session": "S0001",
"metadata": {
"user.id": "123",
"user.email": "cliente@ejemplo.com"
},
"me": {
"id": "5215551234567@c.us",
"pushName": "Mi Nombre"
},
"payload": {
"...": "dados específicos do evento"
},
"environment": {
"tier": "CORE",
"version": "2023.10.12"
},
"engine": "NOWEB"
}Metadados
Você pode enviar metadata personalizado ao criar ou atualizar a sessão; ele será incluído tal como está no campo metadata de cada evento de webhook. Isso permite rotear eventos para o usuário correto sem consultas adicionais ao seu banco de dados.
Eventos disponíveis
Resumo de todos os eventos disponíveis. Clique em cada evento para ir ao seu detalhe:
| Evento | Para que serve |
|---|---|
| session.status | Mudança de estado da sessão (STOPPED, STARTING, SCAN_QR_CODE, WORKING, FAILED, PASSKEY). |
| engine.event | Evento de baixo nível do motor para depuração (não incluído em events=*). |
| message | Mensagem recebida (texto, áudio, arquivos). |
| message.any | Todas as mensagens, incluindo as suas. |
| message.reaction | Reação a uma mensagem. |
| message.ack | Confirmação de entrega, leitura ou reprodução da mensagem. |
| message.ack.group | Confirmação de um participante num grupo. |
| message.waiting | Mensagem em espera («Esperando esta mensagem...»). |
| message.edited | Mensagem editada. |
| message.revoked | Mensagem excluída (revogada). |
| chat.archive | Chat arquivado ou desarquivado. |
| group.v2.join | Você entra ou é adicionado a um grupo. |
| group.v2.leave | Você sai ou é removido de um grupo. |
| group.v2.participants | Alguém entra, sai, é promovido ou rebaixado. |
| group.v2.update | As informações do grupo são atualizadas. |
| presence.update | Atualização de presença (online, offline, digitando, gravando). |
| poll.vote | Novos votos de enquete. |
| poll.vote.failed | Voto de enquete não decifrável. |
| event.response | Resposta a uma mensagem de evento (GOING, NOT_GOING, MAYBE). |
| event.response.failed | Resposta de evento não decifrável. |
| label.upsert | Etiqueta criada ou atualizada. |
| label.deleted | Etiqueta excluída. |
| label.chat.added | Etiqueta adicionada a um chat. |
| label.chat.deleted | Etiqueta removida de um chat. |
| call.received | Chamada recebida. |
| call.accepted | Chamada aceita (em outro dispositivo). |
| call.rejected | Chamada rejeitada ou encerrada. |
session.status
É disparado quando o estado da sessão muda:
STOPPEDa sessão está parada.STARTINGa sessão está iniciando.SCAN_QR_CODEé necessário escanear o QR ou iniciar por telefone. É emitido sempre que o QR muda; ao recebê-lo, obtenha o QR atualizado.PASSKEY_REQUIREDo WhatsApp pede uma passkey (WebAuthn);datacontém o desafio a assinar.PASSKEY_CONFIRMATION_REQUIREDo usuário deve verificar um código;datacontém o código.WORKINGa sessão funciona e está pronta.FAILEDa sessão falhou; tente reiniciar e, se não, feche a sessão e inicie-a novamente.
{
"event": "session.status",
"session": "S0001",
"payload": {
"status": "WORKING",
"statuses": [
{ "status": "STOPPED", "timestamp": 1700000001000 },
{ "status": "STARTING", "timestamp": 1700000002000 },
{ "status": "WORKING", "timestamp": 1700000003000 }
],
"data": null
}
}status é o estado atual; statuses os últimos 3 estados; data leva informações extras do estado.
Exemplo com PASSKEY_REQUIRED:
{
"event": "session.status",
"session": "S0001",
"payload": {
"status": "PASSKEY_REQUIRED",
"statuses": [],
"data": {
"challenge": "9WVUYm9AsQ...",
"timeout": 60000,
"rpId": "web.whatsapp.com",
"allowCredentials": [
{ "id": "AX8bTgH2...", "type": "public-key", "transports": ["internal", "hybrid"] }
],
"userVerification": "required"
}
}
}Exemplo com PASSKEY_CONFIRMATION_REQUIRED:
{
"event": "session.status",
"session": "S0001",
"payload": {
"status": "PASSKEY_CONFIRMATION_REQUIRED",
"statuses": [],
"data": { "code": "1234" }
}
}Exemplo com Bloqueio de contatos (restrição de envio para contatos novos, causa do erro 463):
{
"event": "session.status",
"session": "S0001",
"payload": {
"status": "WORKING",
"statuses": [],
"data": {
"reachoutTimelock": {
"enforcementType": "RESTRICT_ALL_COMPANIONS",
"isActive": true,
"timeEnforcementEnds": 1784477333
}
}
}
}Bloqueio de contatos
NÃO reinicie, feche a sessão nem emparelhe novamente: a restrição é suspensa automaticamente. Pause o envio para contatos novos até timeEnforcementEnds. Leia mais em Como evitar bloqueio.
Exemplo com Limite de mensagens (cota por ciclo de contatos novos, causa do erro 475):
{
"event": "session.status",
"session": "S0001",
"payload": {
"status": "WORKING",
"statuses": [],
"data": {
"messageCapping": {
"cappingStatus": "FIRST_WARNING",
"totalQuota": 1000,
"usedQuota": 640,
"cycleStart": 1782874800,
"cycleEnd": 1785553199,
"mvStatus": "NOT_ELIGIBLE",
"oteStatus": "NOT_ELIGIBLE"
}
}
}
}Limite de mensagens
NÃO reinicie, feche a sessão nem emparelhe novamente: a cota não é reiniciada. Com cappingStatus CAPPED, pause o envio para contatos novos até cycleEnd. Leia mais em Como evitar bloqueio.
message
Mensagem recebida (texto/áudio/arquivos).
{
"event": "message",
"session": "S0001",
"payload": {
"id": "true_5215551234567@c.us_AAAAAAAAAAAAAAAA",
"timestamp": 1667561485,
"from": "5215551234567@c.us",
"fromMe": true,
"source": "app",
"to": "5215551234567@c.us",
"body": "Olá!",
"hasMedia": false,
"ack": 1
}
}hasMedia— indica se a mensagem tem mídia.media.url— URL para baixar a mídia.source—appouapi(quando você envia via API)._data— dados internos do motor.
message.any
É disparado em todas as mensagens, incluindo as suas. Mesmo payload que message.
{
"event": "message.any",
"session": "S0001",
"payload": {
"id": "true_5215551234567@c.us_AAAAAAAAAAAAAAAA",
"timestamp": 1667561485,
"from": "5215551234567@c.us",
"fromMe": true,
"source": "api",
"to": "5215551234567@c.us",
"body": "Olá!",
"hasMedia": false,
"ack": 1
}
}message.reaction
Reação a uma mensagem. reaction.text é o emoji (vazio se foi removido) e reaction.messageId o ID da mensagem reagida.
{
"event": "message.reaction",
"session": "S0001",
"payload": {
"id": "false_5215551234567@c.us_11111111111111111111111111111111",
"from": "5215551234567@c.us",
"fromMe": false,
"reaction": {
"text": "🙏",
"messageId": "true_5215551234567@c.us_11111111111111111111111111111111"
}
}
}message.ack
Confirmação de entrega/leitura da mensagem:
ERROR, ack: -1— ocorreu um erro.PENDING, ack: 0— mensagem pendente.SERVER, ack: 1— enviado ao servidor.DEVICE, ack: 2— enviado ao dispositivo.READ, ack: 3— lido.PLAYED, ack: 4— reproduzido.
{
"event": "message.ack",
"session": "S0001",
"payload": {
"id": "true_5215551234567@c.us_4CC5EDD64BC22EBA6D639F2AF571346C",
"from": "5215551234567@c.us",
"fromMe": true,
"ack": 3,
"ackName": "READ"
}
}message.ack.group
Confirmação de um participante num grupo (inclui o campo participant).
{
"event": "message.ack",
"session": "S0001",
"payload": {
"id": "true_5215551234567@g.us_4CC5EDD64BC22EBA6D639F2AF571346C_9999@lid",
"from": "5215551234567@g.us",
"participant": "9999@lid",
"fromMe": true,
"ack": 3,
"ackName": "READ"
}
}message.waiting
Ocorre quando aparece «Esperando esta mensagem. Pode demorar um pouco» no telefone.
{
"event": "message.waiting",
"session": "S0001",
"payload": {
"id": "true_5215551234567@c.us_AAAAAAAAAAAAAAAA",
"timestamp": 1667561485,
"from": "5215551234567@c.us",
"fromMe": true,
"to": "5215551234567@c.us",
"_data": {}
}
}message.edited
Mensagem editada. editedMessageId é o ID da mensagem editada e body o novo texto. O id do evento tem o formato false_chatId_messageId[_participant].
{
"event": "message.edited",
"session": "S0001",
"payload": {
"id": "false_5215551234567@c.us_AAAAAAAAAAAAAAAA[_5215551234567@c.us]",
"editedMessageId": "AAAAAAAAAAAAAAAA",
"body": "Nuevo texto",
"_data": {}
}
}message.revoked
Mensagem excluída (revogada). revokedMessageId é o ID da mensagem excluída e after.id o do evento de revogação (formato false_chatId_messageId[_participant]).
{
"event": "message.revoked",
"session": "S0001",
"payload": {
"after": {
"id": "false_5215551234567@c.us_AAAAAAAAAAAAAAAA",
"_data": {}
},
"revokedMessageId": "AAAAAAAAAAAAAAAA",
"before": null
}
}chat.archive
Chat arquivado ou desarquivado.
{
"event": "chat.archive",
"session": "S0001",
"payload": {
"id": "5215551234567@c.us",
"timestamp": 1667561485,
"archived": true
}
}group.v2.join
Você entra ou é adicionado a um grupo.
{
"event": "group.v2.join",
"session": "S0001",
"payload": {
"group": {
"id": "5215551234567@g.us",
"subject": "Grupo de trabajo",
"description": "Descrição do grupo",
"invite": "https://chat.whatsapp.com/invitecode",
"membersCanAddNewMember": true,
"membersCanSendMessages": true,
"newMembersApprovalRequired": true,
"participants": [
{ "id": "5219999999999@c.us", "role": "participant" }
]
},
"timestamp": 789456123
}
}group.v2.leave
Você sai ou é removido de um grupo.
{
"event": "group.v2.leave",
"session": "S0001",
"payload": {
"group": { "id": "5215551234567@g.us" },
"timestamp": 789456123
}
}group.v2.participants
Alguém entra, sai, é promovido ou rebaixado. type pode ser join, leave, promote ou demote.
{
"event": "group.v2.participants",
"session": "S0001",
"payload": {
"type": "join",
"timestamp": 1666943582,
"group": { "id": "5215551234567@g.us" },
"participants": [
{ "id": "5219999999999@c.us", "role": "participant" }
],
"_data": {}
}
}Funções possíveis: left, participant, admin e superadmin.
group.v2.update
As informações do grupo são atualizadas.
{
"event": "group.v2.update",
"session": "S0001",
"payload": {
"group": { "id": "5215551234567@g.us", "subject": "Novo nome do grupo" },
"timestamp": 789456123,
"_data": {}
}
}presence.update
Atualização de presença. lastKnownPresence pode ser online, offline, typing, recording ou paused. O campo payload.id indica o chat (direto ou grupo) e participant o participante específico (em chats diretos há apenas um).
{
"event": "presence.update",
"session": "S0001",
"payload": {
"id": "5215551234567@c.us",
"presences": [
{
"participant": "5215551234567@c.us",
"lastKnownPresence": "typing",
"lastSeen": null
}
]
}
}poll.vote
Você recebe novos votos de enquetes. Identifique os seus com poll.fromMe.
{
"event": "poll.vote",
"session": "S0001",
"payload": {
"vote": {
"id": "false_5215551234567@c.us_83ACBE602A05C79B234B54415E95EE8A",
"to": "me",
"from": "5215551234567@c.us",
"fromMe": false,
"selectedOptions": ["Ótimo!"],
"timestamp": 1692861427
},
"poll": {
"id": "true_5215551234567@c.us_BAE5F2EF5C69001E",
"to": "5215551234567@c.us",
"from": "me",
"fromMe": true
}
}
}poll.vote.failed
Igual a poll.vote mas com selectedOptions vazio (não foi possível decifrar o voto).
{
"event": "poll.vote.failed",
"session": "S0001",
"payload": {
"vote": {
"id": "false_5215551234567@c.us_2E8C4CDA89EDE3BC0BC7F605364B8451",
"to": "me",
"from": "5215551234567@c.us",
"fromMe": false,
"selectedOptions": [],
"timestamp": 1692956972
},
"poll": {
"id": "true_5215551234567@c.us_BAE595F4E0A2042C",
"to": "5215551234567@c.us",
"from": "me",
"fromMe": true
}
}
}event.response
Resposta a uma mensagem de evento. eventResponse.response pode ser GOING, NOT_GOING ou MAYBE. Leia mais em Mensagens de evento.
{
"id": "evt_00000000000000000000001",
"session": "S0001",
"event": "event.response",
"payload": {
"id": "false_5215551234567@c.us_58BBBBBBBBBBBBBBBBBBBBBBBB",
"timestamp": 1747707858,
"from": "5215551234567@c.us",
"participant": null,
"fromMe": false,
"eventCreationKey": {
"id": "false_5215551234567@c.us_3EBAAAAAAAAAAAAAAAAAAAAAAAAAA",
"to": "me",
"from": "5215551234567@c.us",
"fromMe": false
},
"eventResponse": {
"response": "GOING",
"timestampMs": 1747707858429,
"extraGuestCount": 0
},
"source": "app",
"ack": null,
"ackName": "UNKNOWN",
"replyTo": null,
"_data": {}
}
}eventCreationKey— informações da mensagem de evento original (id,to,from,fromMe).eventResponse.response—GOING,NOT_GOINGouMAYBE.eventResponse.timestampMs— timestamp Unix em ms da resposta.eventResponse.extraGuestCount— convidados adicionais (0 ou 1).replyTo— informações da mensagem à qual se responde (nullse não for uma resposta).
event.response.failed
Não foi possível decifrar a resposta (com eventResponse: null). Reenvie a mensagem de evento para obter uma nova resposta. Leia mais em Mensagens de evento.
{
"id": "evt_00000000000000000000001",
"session": "S0001",
"event": "event.response.failed",
"payload": {
"id": "false_5215551234567@c.us_58BBBBBBBBBBBBBBBBBBBBBBBB",
"timestamp": 1747707858,
"from": "5215551234567@c.us",
"participant": null,
"fromMe": false,
"eventCreationKey": {
"id": "false_5215551234567@c.us_3EBAAAAAAAAAAAAAAAAAAAAAAAAAA",
"to": "me",
"from": "5215551234567@c.us",
"fromMe": false
},
"eventResponse": null,
"source": "app",
"ack": null,
"ackName": "UNKNOWN",
"replyTo": null,
"_data": {}
}
}label.upsert
Etiqueta criada ou atualizada.
{
"event": "label.upsert",
"session": "S0001",
"payload": {
"id": "10",
"name": "Cliente VIP",
"color": 14,
"colorHex": "#00a0f2"
}
}label.deleted
Etiqueta excluída.
{
"event": "label.deleted",
"session": "S0001",
"payload": {
"id": "10",
"name": "",
"color": 14,
"colorHex": "#00a0f2"
}
}label.chat.added
Etiqueta adicionada a um chat (labelId + chatId). Logo após escanear o QR, label pode ser null.
{
"event": "label.chat.added",
"session": "S0001",
"payload": {
"labelId": "6",
"chatId": "5215551234567@c.us",
"label": null
}
}label.chat.deleted
Etiqueta removida de um chat (labelId + chatId).
{
"event": "label.chat.deleted",
"session": "S0001",
"payload": {
"labelId": "6",
"chatId": "5215551234567@c.us",
"label": null
}
}call.received
Chamada recebida.
{
"event": "call.received",
"session": "S0001",
"payload": {
"id": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
"from": "5215551234567@c.us",
"timestamp": 1721374000,
"isVideo": false,
"isGroup": false
}
}call.accepted
Chamada aceita (em outro dispositivo).
{
"event": "call.accepted",
"session": "S0001",
"payload": {
"id": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
"from": "5215551234567@c.us",
"timestamp": 1721374000,
"isVideo": false,
"isGroup": false,
"_data": {}
}
}call.rejected
Chamada rejeitada ou encerrada.
{
"event": "call.rejected",
"session": "S0001",
"payload": {
"id": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
"from": "5215551234567@c.us",
"timestamp": 1721374000,
"isVideo": false,
"isGroup": false,
"_data": {}
}
}No motor WEBJS, call.rejected só é disparado quando você rejeita a chamada mediante a API.
engine.event
Evento de baixo nível do motor, para depuração e diagnóstico. Não é incluído ao se inscrever com events=*; você deve especificá-lo explicitamente.
{
"event": "engine.event",
"session": "S0001",
"engine": "NOWEB",
"payload": {
"event": "messages.upsert",
"data": {}
}
}