Blueticks

Webhook event reference

Every incoming-WhatsApp webhook event (the *_webhook events) and the fields in its payload.

This page lists the payload of every event whose name ends in _webhook. How to register an endpoint, verify signatures and handle retries is in Receiving webhooks.

The structured message.*, session.* and campaign.* events are not covered here.

How to read a payload

Every delivery is the same envelope. The fields below are the contents of data:

{
  "id": "evt_...",
  "type": "ack_changed_webhook",
  "created_at": "2026-04-23T16:42:00.000Z",
  "data": { "webhookType": "ack_changed_webhook", "...": "..." }
}
  • The envelope keys (created_at, idempotency_key) are snake_case. The keys inside data are camelCase, exactly as sent.
  • Each event below (except the two message events) repeats its own name in data.webhookType.
  • Chat, sender and group ids are WhatsApp ids as strings, for example 120363...@g.us for a group.
  • Fields marked optional are left out when Blueticks does not know the value. Blueticks does not fill them with a placeholder.
  • A field typed string | null is always present and can be null.

Shared building blocks

Contact details (every *Details object, and each item in the participants-style arrays):

FieldTypeNotes
idstring, optionalWhatsApp id of the person.
namestring, optionalDisplay text. It can fall back to a phone label, so don't use it as an identity.
mobilestring, optionalThe person's phone as +<digits>, whenever it is known. For a @c.us id it can be derived from the id.

Timestamps (on every event except the two message events):

FieldTypeNotes
timestampnumberWhen the event was emitted, in milliseconds.
whatsappTimestampnumber, optional, may be nullWhatsApp's own time of the event, in seconds. Left out when the engine doesn't have one.

Group fields (on every event that says "group fields" below):

FieldTypeNotes
chatIdstring, optionalThe group's chat id.
groupIdstring, optionalThe group's id.
groupNamestring, optionalThe group's subject. Absent when unknown. It is never replaced by the group id.
groupobject, optional{ id?, name? }.

Incoming messages

new_message_received_webhook

Someone sent a message to your account. This event is inbound-only.

new_message_received_from_me_webhook

A message sent from your own account. It's opt-in: subscribe to this event explicitly. new_message_received_webhook never carries your own messages. The payload is the same shape as the one below.

In both events data is the message itself, not a wrapper around it. There is no webhookType field in it.

FieldTypeNotes
idobjectThe message key: fromMe (boolean), remote (the chat, as { _serialized }), id (the bare message id), _serialized (the full key string), participant (the sender inside a group, as { _serialized }). Only fromMe is always present.
waMessageKeyobject, optionalThe same key with plain strings: fromMe, remote, id, _serialized, participant.
bodystringThe text. An empty string for media messages. For a poll it is the question.
captionstring | nullCaption on media.
filenamestring | nullFile name, for documents.
fromobject, optionalWhere the message came from. For a direct chat it is the sender, for a group it is the group. { _serialized, id? }. Blueticks adds mobile (+<digits>) when from.id is a @c.us id and no mobile is present.
toobject, optionalThe other side, { _serialized, user?, server? }. For an incoming message it is your own number.
authorobject, optionalThe sender inside a group ({ _serialized, ... }). Absent for an incoming direct message.
fromMebooleantrue for messages sent by the connected account.
tnumberWhatsApp time of the message, in Unix seconds.
typestringThe message kind, for example chat, image, video, audio, ptt, document, sticker, poll_creation, vcard, location, gp2, revoked, call_log. Deprecated: prefer waType.
waTypestring, optionalWhatsApp Web's own name for the type. Absent when the engine can't classify the message.
subtypestring | null, optionalFor example url for text with a link preview.
isGifboolean, optionalA GIF (type: "video").
notifyNamestring | null, optionalThe sender's own WhatsApp display name.
senderNamestring | null, optionalThe sender's name from the contact store. Group messages only, best effort.
isForwarded, isViewOnceboolean, optional
mimetypestring | null, optionalMedia MIME type.
durationinteger, optionalSeconds, for voice notes and audio.
sizenumber, optionalMedia size.
hasAttachedMediaboolean, optionaltrue when the message has media to download.
quotedMessageobject, optionalPresent on replies: waMessageKey (the quoted message's key), text, type, author (all but the key are optional).
quotedStanzaIDstring, optionalThe quoted message's bare id, on replies.
pollobject, optional{ question?, options?: [{ text? }] }, on poll messages.
contactsarray, optionalOn contact cards: { name, phones: string[], waId? } per card.
vcardFormattedName, vcardListoptionalOn contact cards: the display name and the raw cards ({ displayName?, vcard? }).
linkPreviewobject | null, optional{ title?, description?, matchedText?, canonicalUrl?, thumbnail? }.
interactiveobject, optionalMenu or button replies: kind, plus options ({ id, title, description?, section? }) for a menu, or selectedId, selectedTitle and quotedId for a click.
callobject, optionalOn call_log: direction (in/out), media (voice/video), outcome (answered/missed/rejected/unknown), durationSec?, isGroup.
reactionsarray, optional{ text, from?, fromMe?, t? } per live reaction.
recipients, templateParamsoptionalOn gp2 group-notice messages: the participants it names and its template parameters.
ackinteger | null, optionalDelivery state. See the scale under ack_changed_webhook.
mediaUrlstring | null, optionalUsually null. Set only when a download URL is attached inline.
isGrouptrue, optionalPresent, and always true, when the chat is a group.
mediaKey, directPath, filehash, encFilehash, mediaKeyTimestampoptionalMedia download handles.
isLivetrue, optionalA live location or live media.
protocolMessageKeyobject, optionalOn protocol messages (revoke, edit): the key of the message they target.
secretstring, optionalThe secret correlation token you set when you sent the message through the API. Only present when the message carries one.
receivedOnobject, optionalWhich of your numbers received it: phoneNumber (digits, no +), numberId?, engineId?.
sentByApiobject, optionalFor an inbound message that your account sent through the API from another of its numbers: idempotencyKey (string or null) and messageId. Only for accounts with more than one number.

Some fields are marked deprecated in the schema and are still sent for older consumers: hasMedia, links, quotedMsg, and the flat link-preview fields title, description, matchedText, canonicalUrl, thumbnail and richPreviewType (use linkPreview instead). Don't build on them.

Message activity

reply_to_my_message_webhook

Someone replied to a message you sent.

FieldTypeNotes
webhookTypestringreply_to_my_message_webhook.
replyMessageIdstring, optionalKey of the reply.
replyMessageBodystring | null, optional
replyMessageTypestring | null, optional
repliedBystring, optionalWho replied.
repliedByDetailscontact details, optional
quotedStanzaIDstring | null, optional
originalMessageobjectYour message: id?, body?, caption?, type?, from?, fromDetails?, and fromMe, which is always true.
group fields
timestamp, whatsappTimestamp

message_edited_webhook

A message was edited.

FieldTypeNotes
webhookTypestringmessage_edited_webhook.
messageIdstring, optional
group fields
from, fromDetails, author, authorDetailsoptionalThe sender.
fromMeboolean
editedFieldstringbody, caption or unknown.
previousValue, newValuestring, optional
body, caption, mimetype, filenamestring | null, optionalThe message content.
hasMediaboolean
messageTypestring | null, optional
timestamp, whatsappTimestamp

message_deleted_revoked_webhook

A message was deleted.

FieldTypeNotes
webhookTypestringmessage_deleted_revoked_webhook.
messageIdstring, optional
group fields
from, fromDetails, author, authorDetailsoptionalThe sender of the deleted message.
fromMeboolean
deletionReasonstringremoved or revoked.
deletionScopestringdelete_for_me or delete_for_everyone.
subtypestring | null, optional
deletedBy, deletedByDetails, deletedByNameoptionalWho deleted it.
messageobjecttype?, body?, caption?, hasMedia, mimetype?, filename?.
timestamp, whatsappTimestamp

message_reaction_webhook

An emoji reaction was added to a message.

FieldTypeNotes
webhookTypestringmessage_reaction_webhook.
messageIdstring, optionalThe reacted-to message.
messageBodystring | null, optional
group fields
messageFrom, messageFromDetailsoptionalThe author of the reacted-to message.
reactionCountnumber
reactorNamesstring[]
reactionobjectThe latest reaction: text?, from?, fromDetails?, fromName?, timestamp?.
reactionsarrayAll reactions, same item shape.
timestamp, whatsappTimestamp

poll_vote_webhook

Someone voted on a poll. This is the only event that carries idempotency_key (see Receiving webhooks).

FieldTypeNotes
webhookTypestringpoll_vote_webhook.
messageIdstring, optionalThe poll message.
group fields
pollNamestring | null, optionalThe poll question.
pollOptionsarray{ localId, name? } per option. localId is a number or a string.
voteCountnumber
votesarrayOne item per vote, shape below.
latestVoteobject, optionalThe vote that triggered the event, same shape as an item in votes.
timestamp, whatsappTimestamp

A vote has voter?, voterDetails?, voterName?, selectedOptions (an alias of selectedOptionLocalIds), selectedOptionLocalIds, selectedOptionDetails ({ localId, name? } items), selectedOptionNames and whatsappTimestamp? (seconds).

ack_changed_webhook

A message's delivery status changed.

FieldTypeNotes
webhookTypestringack_changed_webhook.
messageId, chatIdstring, optional
isGroupboolean
groupIdstring, optional
from, author, tostring, optional
body, caption, mimetype, filenamestring | null, optionalThe message content.
hasMediaboolean
textstring, optional
messageTypestring | null, optional
acknumberThe new state.
ackLabelstringThe state's name.
fromMeboolean
chatName, groupName, groupoptional
fromDetails, authorDetails, toDetailscontact details, optional
triggeredByobject, optionalThe recipient whose receipt changed the state, shape below.
triggeredByNamestring, optional
recipientsDelivered, recipientsRead, recipientsPlayedarrayRecipients, shape below.
timestamp, whatsappTimestamp

The ack scale is -1 error, 0 pending, 1 server, 2 device, 3 read, 4 played. ackLabel is error, pending, sent, delivered, read or played respectively, or unknown_<n> for any other value.

A recipient has id?, name?, details? (contact details), t? (the receipt time in seconds, when known) and status? (delivered, read, played or unknown).

Group activity

All group events share these fields, in addition to webhookType:

FieldTypeNotes
group fields
authorstring, optionalWho made the change.
authorDetailscontact details
participantscontact details[]The people the event names.
participantNamesstring[]
subtypestring | null, optional
timestamp, whatsappTimestamp

On top of that, each event adds the following. Every participant event has a list (…Participants, contact details), a parallel list of names (…ParticipantNames), and the first entry on its own (…Participant and …ParticipantName, both optional).

EventAdded fields
participant_joined_via_link_webhookjoinedParticipants, joinedParticipantNames, joinedParticipant?, joinedParticipantName?
participant_added_by_admin_webhookaddedParticipants, addedParticipantNames, addedParticipant?, addedParticipantName?
participant_left_group_webhookleftParticipants, leftParticipantNames, leftParticipant?, leftParticipantName?
participant_kicked_from_group_webhookkickedParticipants, kickedParticipantNames, kickedParticipant?, kickedParticipantName?
group_admin_changed_webhookadminAction (promoted_to_admin or demoted_from_admin), changedParticipants, changedParticipantNames, changedParticipant?, changedParticipantName?, promotedParticipants, demotedParticipants
group_name_changed_webhookbody (string | null, optional)
group_description_changed_webhookbody (string | null, optional)
group_message_pinned_webhookbody (string | null, optional), pinnedMessageId (optional), pinType (number | null, optional)

The same payload that new_message_received_webhook delivers is also what you get on the MQTT stream, if you use it.