Skip to Content
Wazend

Events

Receive WhatsApp events in real time with Webhooks and WebSockets: payload structure, HMAC, retries and the full event list.

To notify your application about WhatsApp events, you can use Webhooks and WebSockets.

Webhooks

Webhooks let two applications communicate in real time: when an event occurs, Wazend sends an HTTP POST request to your URL.

Per-session webhooks

Configure per-session webhooks in the session configuration:

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

Retries

Available retry policies:

  • constant — same delay between attempts (2, 2, 2).
  • linear — linear backoff (2, 4, 6, 8).
  • exponential — exponential backoff with jitter.

Headers

Every webhook includes these headers:

  • X-Webhook-Request-Id — unique request ID.
  • X-Webhook-Timestamp — Unix timestamp in ms.
  • X-Webhook-Hmac — body authentication code (if you use HMAC).
  • X-Webhook-Hmac-Algorithm — algorithm used (sha512).

HMAC authentication

Set your secret key in config.hmac.key and verify the signature in the X-Webhook-Hmac header (algorithm sha512) against the request body.

Body
{
  "name": "S0001",
  "config": {
    "webhooks": [
      {
        "url": "https://tu-servidor.com/webhook",
        "events": ["message"],
        "hmac": { "key": "tu-clave-secreta" }
      }
    ]
  }
}

Always verify the signature

Validate the HMAC signature to protect your endpoint against malicious requests.

Examples

You can automate flows with n8n.

WebSockets

Use WebSockets to receive messages in real time.

# Listen to all sessions and events
websocat -E wss://latam-1.wazend.net/ws

# With API key
websocat -E wss://latam-1.wazend.net/ws?x-api-key=123

# Listen to specific events
websocat -E "wss://latam-1.wazend.net/ws?session=*&events=session.status&events=message"

# Listen to one session
websocat -E "wss://latam-1.wazend.net/ws?session=S0001&events=session.status"

Parameters:

  • session — session name or * for all.
  • events — event list or *.
  • x-api-key — your API key.

Payload structure

Event
{
  "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": {
    "...": "event-specific data"
  },
  "environment": {
    "tier": "CORE",
    "version": "2023.10.12"
  },
  "engine": "NOWEB"
}

Metadata

You can send custom metadata when creating or updating the session; it will be included as-is in the metadata field of every webhook event. This lets you route events to the right user without additional queries to your database.

Available events

Summary of all available events. Click on each event to go to its detail:

EventWhat it's for
session.statusSession status change (STOPPED, STARTING, SCAN_QR_CODE, WORKING, FAILED, PASSKEY).
engine.eventLow-level engine event for debugging (not included in events=*).
messageIncoming message (text, audio, files).
message.anyAll messages, including your own.
message.reactionReaction to a message.
message.ackMessage delivery, read or playback confirmation.
message.ack.groupConfirmation from a participant in a group.
message.waitingWaiting message ("Waiting for this message...").
message.editedEdited message.
message.revokedDeleted (revoked) message.
chat.archiveChat archived or unarchived.
group.v2.joinYou join or are added to a group.
group.v2.leaveYou leave or are removed from a group.
group.v2.participantsSomeone joins, leaves, is promoted or demoted.
group.v2.updateThe group information is updated.
presence.updatePresence update (online, offline, typing, recording).
poll.voteNew poll votes.
poll.vote.failedUndecryptable poll vote.
event.responseResponse to an event message (GOING, NOT_GOING, MAYBE).
event.response.failedUndecryptable event response.
label.upsertLabel created or updated.
label.deletedLabel deleted.
label.chat.addedLabel added to a chat.
label.chat.deletedLabel removed from a chat.
call.receivedIncoming call.
call.acceptedCall accepted (on another device).
call.rejectedCall rejected or ended.

session.status

Fires when the session status changes:

  • STOPPED the session is stopped.
  • STARTING the session is starting.
  • SCAN_QR_CODE scanning the QR or logging in by phone is required. It's emitted every time the QR changes; when you receive it, get the updated QR.
  • PASSKEY_REQUIRED WhatsApp asks for a passkey (WebAuthn); data contains the challenge to sign.
  • PASSKEY_CONFIRMATION_REQUIRED the user must verify a code; data contains the code.
  • WORKING the session works and is ready.
  • FAILED the session failed; try to restart, and if not, log out and start it again.
Event
{
  "event": "session.status",
  "session": "S0001",
  "payload": {
    "status": "WORKING",
    "statuses": [
      { "status": "STOPPED", "timestamp": 1700000001000 },
      { "status": "STARTING", "timestamp": 1700000002000 },
      { "status": "WORKING", "timestamp": 1700000003000 }
    ],
    "data": null
  }
}

status is the current status; statuses the last 3 statuses; data carries extra status info.

Example with PASSKEY_REQUIRED:

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

Example with PASSKEY_CONFIRMATION_REQUIRED:

Event
{
  "event": "session.status",
  "session": "S0001",
  "payload": {
    "status": "PASSKEY_CONFIRMATION_REQUIRED",
    "statuses": [],
    "data": { "code": "1234" }
  }
}

Example with Reachout Timelock (restriction on sending to new contacts, cause of error 463):

Event
{
  "event": "session.status",
  "session": "S0001",
  "payload": {
    "status": "WORKING",
    "statuses": [],
    "data": {
      "reachoutTimelock": {
        "enforcementType": "RESTRICT_ALL_COMPANIONS",
        "isActive": true,
        "timeEnforcementEnds": 1784477333
      }
    }
  }
}

Reachout Timelock

DO NOT restart, log out or re-pair: the restriction is lifted automatically. Pause sending to new contacts until timeEnforcementEnds. Read more in How to avoid a ban.

Example with Message Capping (per-cycle quota of new contacts, cause of error 475):

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

Message Capping

DO NOT restart, log out or re-pair: the quota doesn't reset. With cappingStatus CAPPED, pause sending to new contacts until cycleEnd. Read more in How to avoid a ban.

message

Incoming message (text/audio/files).

Event
{
  "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": "Hello!",
    "hasMedia": false,
    "ack": 1
  }
}
  • hasMedia — indicates whether the message has media.
  • media.url — URL to download the media.
  • source — app or api (when you send via API).
  • _data — internal engine data.

message.any

Fires on all messages, including your own. Same payload as message.

Event
{
  "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": "Hello!",
    "hasMedia": false,
    "ack": 1
  }
}

message.reaction

Reaction to a message. reaction.text is the emoji (empty if removed) and reaction.messageId the ID of the reacted message.

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

Message delivery/read confirmation:

  • ERROR, ack: -1 — an error occurred.
  • PENDING, ack: 0 — pending message.
  • SERVER, ack: 1 — sent to the server.
  • DEVICE, ack: 2 — sent to the device.
  • READ, ack: 3 — read.
  • PLAYED, ack: 4 — played.
Event
{
  "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

Confirmation from a participant in a group (includes the participant field).

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

Occurs when "Waiting for this message. This may take a while" appears on the phone.

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

Edited message. editedMessageId is the ID of the edited message and body the new text. The event id has the format false_chatId_messageId[_participant].

Event
{
  "event": "message.edited",
  "session": "S0001",
  "payload": {
    "id": "false_5215551234567@c.us_AAAAAAAAAAAAAAAA[_5215551234567@c.us]",
    "editedMessageId": "AAAAAAAAAAAAAAAA",
    "body": "Nuevo texto",
    "_data": {}
  }
}

message.revoked

Deleted (revoked) message. revokedMessageId is the ID of the deleted message and after.id the revocation event ID (format false_chatId_messageId[_participant]).

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

chat.archive

Chat archived or unarchived.

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

group.v2.join

You join or are added to a group.

Event
{
  "event": "group.v2.join",
  "session": "S0001",
  "payload": {
    "group": {
      "id": "5215551234567@g.us",
      "subject": "Grupo de trabajo",
      "description": "Group description",
      "invite": "https://chat.whatsapp.com/invitecode",
      "membersCanAddNewMember": true,
      "membersCanSendMessages": true,
      "newMembersApprovalRequired": true,
      "participants": [
        { "id": "5219999999999@c.us", "role": "participant" }
      ]
    },
    "timestamp": 789456123
  }
}

group.v2.leave

You leave or are removed from a group.

Event
{
  "event": "group.v2.leave",
  "session": "S0001",
  "payload": {
    "group": { "id": "5215551234567@g.us" },
    "timestamp": 789456123
  }
}

group.v2.participants

Someone joins, leaves, is promoted or demoted. type can be join, leave, promote or demote.

Event
{
  "event": "group.v2.participants",
  "session": "S0001",
  "payload": {
    "type": "join",
    "timestamp": 1666943582,
    "group": { "id": "5215551234567@g.us" },
    "participants": [
      { "id": "5219999999999@c.us", "role": "participant" }
    ],
    "_data": {}
  }
}

Possible roles: left, participant, admin and superadmin.

group.v2.update

The group information is updated.

Event
{
  "event": "group.v2.update",
  "session": "S0001",
  "payload": {
    "group": { "id": "5215551234567@g.us", "subject": "New group name" },
    "timestamp": 789456123,
    "_data": {}
  }
}

presence.update

Presence update. lastKnownPresence can be online, offline, typing, recording or paused. The payload.id field indicates the chat (direct or group) and participant the specific participant (in direct chats there is only one).

Event
{
  "event": "presence.update",
  "session": "S0001",
  "payload": {
    "id": "5215551234567@c.us",
    "presences": [
      {
        "participant": "5215551234567@c.us",
        "lastKnownPresence": "typing",
        "lastSeen": null
      }
    ]
  }
}

poll.vote

You receive new poll votes. Identify your own with poll.fromMe.

Event
{
  "event": "poll.vote",
  "session": "S0001",
  "payload": {
    "vote": {
      "id": "false_5215551234567@c.us_83ACBE602A05C79B234B54415E95EE8A",
      "to": "me",
      "from": "5215551234567@c.us",
      "fromMe": false,
      "selectedOptions": ["Great!"],
      "timestamp": 1692861427
    },
    "poll": {
      "id": "true_5215551234567@c.us_BAE5F2EF5C69001E",
      "to": "5215551234567@c.us",
      "from": "me",
      "fromMe": true
    }
  }
}

poll.vote.failed

Same as poll.vote but with an empty selectedOptions (the vote couldn't be decrypted).

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

Response to an event message. eventResponse.response can be GOING, NOT_GOING or MAYBE. Read more in Event messages.

Event
{
  "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 — information of the original event message (id, to, from, fromMe).
  • eventResponse.response — GOING, NOT_GOING or MAYBE.
  • eventResponse.timestampMs — Unix timestamp in ms of the response.
  • eventResponse.extraGuestCount — additional guests (0 or 1).
  • replyTo — info of the message being replied to (null if it's not a reply).

event.response.failed

The response couldn't be decrypted (with eventResponse: null). Resend the event message to get a new response. Read more in Event messages.

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

Label created or updated.

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

label.deleted

Label deleted.

Event
{
  "event": "label.deleted",
  "session": "S0001",
  "payload": {
    "id": "10",
    "name": "",
    "color": 14,
    "colorHex": "#00a0f2"
  }
}

label.chat.added

Label added to a chat (labelId + chatId). Right after scanning the QR, label can be null.

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

label.chat.deleted

Label removed from a chat (labelId + chatId).

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

call.received

Incoming call.

Event
{
  "event": "call.received",
  "session": "S0001",
  "payload": {
    "id": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
    "from": "5215551234567@c.us",
    "timestamp": 1721374000,
    "isVideo": false,
    "isGroup": false
  }
}

call.accepted

Call accepted (on another device).

Event
{
  "event": "call.accepted",
  "session": "S0001",
  "payload": {
    "id": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
    "from": "5215551234567@c.us",
    "timestamp": 1721374000,
    "isVideo": false,
    "isGroup": false,
    "_data": {}
  }
}

call.rejected

Call rejected or ended.

Event
{
  "event": "call.rejected",
  "session": "S0001",
  "payload": {
    "id": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
    "from": "5215551234567@c.us",
    "timestamp": 1721374000,
    "isVideo": false,
    "isGroup": false,
    "_data": {}
  }
}

In the WEBJS engine, call.rejected only fires when you reject the call through the API.

engine.event

Low-level engine event, for debugging and diagnostics. It's not included when subscribing with events=*; you must specify it explicitly.

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