Skip to Content
Wazend

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:

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

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

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

EventoPara que serve
session.statusMudança de estado da sessão (STOPPED, STARTING, SCAN_QR_CODE, WORKING, FAILED, PASSKEY).
engine.eventEvento de baixo nível do motor para depuração (não incluído em events=*).
messageMensagem recebida (texto, áudio, arquivos).
message.anyTodas as mensagens, incluindo as suas.
message.reactionReação a uma mensagem.
message.ackConfirmação de entrega, leitura ou reprodução da mensagem.
message.ack.groupConfirmação de um participante num grupo.
message.waitingMensagem em espera («Esperando esta mensagem...»).
message.editedMensagem editada.
message.revokedMensagem excluída (revogada).
chat.archiveChat arquivado ou desarquivado.
group.v2.joinVocê entra ou é adicionado a um grupo.
group.v2.leaveVocê sai ou é removido de um grupo.
group.v2.participantsAlguém entra, sai, é promovido ou rebaixado.
group.v2.updateAs informações do grupo são atualizadas.
presence.updateAtualização de presença (online, offline, digitando, gravando).
poll.voteNovos votos de enquete.
poll.vote.failedVoto de enquete não decifrável.
event.responseResposta a uma mensagem de evento (GOING, NOT_GOING, MAYBE).
event.response.failedResposta de evento não decifrável.
label.upsertEtiqueta criada ou atualizada.
label.deletedEtiqueta excluída.
label.chat.addedEtiqueta adicionada a um chat.
label.chat.deletedEtiqueta removida de um chat.
call.receivedChamada recebida.
call.acceptedChamada aceita (em outro dispositivo).
call.rejectedChamada rejeitada ou encerrada.

session.status

É disparado quando o estado da sessão muda:

  • STOPPED a sessão está parada.
  • STARTING a 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_REQUIRED o WhatsApp pede uma passkey (WebAuthn); data contém o desafio a assinar.
  • PASSKEY_CONFIRMATION_REQUIRED o usuário deve verificar um código; data contém o código.
  • WORKING a sessão funciona e está pronta.
  • FAILED a sessão falhou; tente reiniciar e, se não, feche a sessão e inicie-a novamente.
Evento
{
  "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:

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

Evento
{
  "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):

Evento
{
  "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):

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

Evento
{
  "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 — app ou api (quando você envia via API).
  • _data — dados internos do motor.

message.any

É disparado em todas as mensagens, incluindo as suas. Mesmo payload que message.

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

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

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

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

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

Evento
{
  "event": "message.revoked",
  "session": "S0001",
  "payload": {
    "after": {
      "id": "false_5215551234567@c.us_AAAAAAAAAAAAAAAA",
      "_data": {}
    },
    "revokedMessageId": "AAAAAAAAAAAAAAAA",
    "before": null
  }
}

chat.archive

Chat arquivado ou desarquivado.

Evento
{
  "event": "chat.archive",
  "session": "S0001",
  "payload": {
    "id": "5215551234567@c.us",
    "timestamp": 1667561485,
    "archived": true
  }
}

group.v2.join

Você entra ou é adicionado a um grupo.

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

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

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

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

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

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

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

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_GOING ou MAYBE.
  • eventResponse.timestampMs — timestamp Unix em ms da resposta.
  • eventResponse.extraGuestCount — convidados adicionais (0 ou 1).
  • replyTo — informações da mensagem à qual se responde (null se 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.

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.

Evento
{
  "event": "label.upsert",
  "session": "S0001",
  "payload": {
    "id": "10",
    "name": "Cliente VIP",
    "color": 14,
    "colorHex": "#00a0f2"
  }
}

label.deleted

Etiqueta excluída.

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

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

Evento
{
  "event": "label.chat.deleted",
  "session": "S0001",
  "payload": {
    "labelId": "6",
    "chatId": "5215551234567@c.us",
    "label": null
  }
}

call.received

Chamada recebida.

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

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

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

Evento
{
  "event": "engine.event",
  "session": "S0001",
  "engine": "NOWEB",
  "payload": {
    "event": "messages.upsert",
    "data": {}
  }
}