GOWA - WhatsApp REST API with support for UI, Multi Account, Webhooks, and MCP, and Chatwoot. Built with Golang for efficient memory use.
Webhook Payload Documentation
This document provides comprehensive documentation for the webhook payload structure used by the Go WhatsApp Web Multidevice application.
Overview
The webhook system sends HTTP POST requests to configured URLs whenever WhatsApp events occur. Each webhook request includes event data in JSON format and security headers for verification.
Available Webhook Events
The following events can be received via webhook:
| Event | Description |
|---|---|
message |
Text, media, contact, location, and other message types |
message.reaction |
Emoji reactions to messages |
message.revoked |
Deleted/revoked messages |
message.edited |
Edited messages |
message.ack |
Delivery and read receipts |
message.deleted |
Messages deleted for the user |
chat_presence |
Typing and recording indicators from contacts |
presence |
Online/offline status of subscribed contacts |
group.participants |
Group member join/leave/promote/demote events |
group.info |
Group name (subject) changed |
group.joined |
You were added to a group |
label.edit |
WhatsApp label metadata changed |
label.association |
Label applied to or removed from a chat |
newsletter.joined |
You subscribed to a newsletter/channel |
newsletter.left |
You unsubscribed from a newsletter |
newsletter.message |
Live counter updates of a subscribed newsletter |
newsletter.mute |
Newsletter mute setting changed |
call.offer |
Incoming call received |
device.logged_out |
The device was logged out, with WhatsApp's reason |
device.temporary_ban |
WhatsApp temporarily banned the account |
device.reachout_timelock |
WhatsApp restricted the account from starting new chats |
Event Filtering
You can configure which events are forwarded to your webhook using the WHATSAPP_WEBHOOK_EVENTS environment variable or
--webhook-events CLI flag.
Configuration Examples
Environment Variable:
# Only receive message and read receipt events
WHATSAPP_WEBHOOK_EVENTS=message,message.ack
# Receive all message-related events
WHATSAPP_WEBHOOK_EVENTS=message,message.reaction,message.revoked,message.edited,message.ack,message.deleted
# Receive only group events
WHATSAPP_WEBHOOK_EVENTS=group.participants,group.info,group.joined
# Receive label events
WHATSAPP_WEBHOOK_EVENTS=label.edit,label.association
# Receive newsletter events
WHATSAPP_WEBHOOK_EVENTS=newsletter.joined,newsletter.left,newsletter.message,newsletter.mute
# Receive call events
WHATSAPP_WEBHOOK_EVENTS=call.offer
# Receive device events
WHATSAPP_WEBHOOK_EVENTS=device.logged_out,device.temporary_ban,device.reachout_timelock
# Receive all group and newsletter events
WHATSAPP_WEBHOOK_EVENTS=group.participants,group.info,group.joined,newsletter.joined,newsletter.left,newsletter.message
CLI Flag:
# Only receive message events
./whatsapp rest --webhook="https://yourapp.com/webhook" --webhook-events="message"
# Receive message and group events
./whatsapp rest --webhook="https://yourapp.com/webhook" --webhook-events="message,group.participants"
Behavior:
- If
WHATSAPP_WEBHOOK_EVENTSis empty or not set, all events are forwarded (default behavior) - If configured, only the specified events are forwarded to webhooks
- Event names are case-insensitive
Ignoring chats/JIDs
In addition to filtering by event type above, you can skip events by conversation or sender JID —
for example, to mute all group traffic from the webhook. This is independent of WHATSAPP_WEBHOOK_EVENTS
(the two filters compose: an event is forwarded only if its type is allowed and its JID is not ignored).
Environment Variable:
# Drop all group messages/receipts (any chat_id ending in @g.us)
[email protected]
# Drop all groups plus one specific 1:1 chat
[email protected],[email protected]
CLI Flag:
./whatsapp rest --webhook="https://yourapp.com/webhook" --webhook-ignore-jids="@g.us"
Behavior:
- Matches the event's
chat_id,from,chat_lidorfrom_lidagainst the list (so an@lidpattern matches LID-migrated events, whose@lidJID lives in the*_lidfields). - An
@-prefixed entry is an address-space wildcard (@g.us,@s.whatsapp.net,@lid); any other entry is an exact JID match. - Empty/unset (default) forwards everything.
- Independent from the Chatwoot integration, which keeps its own
CHATWOOT_IGNORE_JIDS. WHATSAPP_WEBHOOK_DEVICE_MERGE_GLOBAL=true(--webhook-device-merge-global) changes what a per-devicewebhook_urlmeans: instead of replacing the globalWHATSAPP_WEBHOOKtargets it is added to them. The device URL is signed with the device'swebhook_secretand filtered by itswebhook_events; the global URLs keep the global secret andWHATSAPP_WEBHOOK_EVENTS. The ignore-JID rules above apply to both. A global URL that equals the device URL is delivered once. Defaultfalsekeeps the replace behaviour.@g.usis the recommended way to mute groups (it matches the groupchat_id). The@s.whatsapp.netwildcard matches the sender too, so it also suppresses group messages (whosefromis the participant's@s.whatsapp.netJID) — use exact JIDs if you only want to mute specific 1:1 chats.- Note: a few events carry the group JID elsewhere or omit
chat_id—call.offerputs the group ingroup_jid(notchat_id),message.deletedonly includeschat_idwhen the original message is found locally, andgroup.participants/group.info/group.joinedhave nofrom. The@g.uswildcard still covers ordinary group messages and receipts (which is the common case for muting groups).
Security
HMAC Signature Verification
All webhook requests include an HMAC SHA256 signature for security verification:
- Header:
X-Hub-Signature-256 - Format:
sha256={signature} - Algorithm: HMAC SHA256
- Secret: set
WHATSAPP_WEBHOOK_SECRETor--webhook-secretto a private value. The old published defaultsecretis not a signing key. When the secret is unset, the process generates a random key that changes on restart and logs a warning.
Verification Example (Node.js)
const crypto = require('crypto');
function verifyWebhookSignature(payload, signature, secret) {
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(payload, 'utf8')
.digest('hex');
const receivedSignature = signature.replace('sha256=', '');
return crypto.timingSafeEqual(
Buffer.from(expectedSignature, 'hex'),
Buffer.from(receivedSignature, 'hex')
);
}
Verification Example (Python)
import hmac
import hashlib
def verify_webhook_signature(payload, signature, secret):
expected_signature = hmac.new(
secret.encode('utf-8'),
payload,
hashlib.sha256
).hexdigest()
received_signature = signature.replace('sha256=', '')
return hmac.compare_digest(expected_signature, received_signature)
Payload Structure
All webhook payloads follow a consistent top-level structure:
{
"event": "message",
"device_id": "[email protected]",
"session_id": "org_2",
"payload": {
// Event-specific fields
}
}
Top-Level Fields
| Field | Type | Description |
|---|---|---|
event |
string | Event type: message, message.reaction, message.revoked, message.edited, message.ack, message.deleted, chat_presence, presence, group.participants, group.info, group.joined, label.edit, label.association, newsletter.joined, newsletter.left, newsletter.message, newsletter.mute, call.offer, device.logged_out, device.temporary_ban, device.reachout_timelock |
device_id |
string | JID of the device that received this event (e.g., [email protected]) |
session_id |
string | ID of the emitting slot. Device events always set this field; auto-created slots may use a WhatsApp JID. Other events may omit it when the JID cannot be mapped to a session. |
payload |
object | Event-specific payload data |
Common Payload Fields
Fields commonly found inside the payload object:
| Field | Type | Description |
|---|---|---|
id |
string | Message ID |
chat_id |
string | Chat JID (e.g., [email protected] or [email protected] for groups) |
from |
string | Full JID of the sender (e.g., [email protected]) |
from_lid |
string | LID (Linked ID) of the sender if available |
sender_display_name |
string | Dynamic human-readable sender label. Present only when from is a non-empty string; see Sender Display Name Resolution. |
from_name |
string | Legacy message-event push name of the sender. It remains available for compatibility and is not replaced by sender_display_name. |
timestamp |
string | RFC3339 formatted timestamp (e.g., 2023-10-15T10:30:00Z) |
is_from_me |
boolean | Whether the message was sent by the current user |
is_business |
boolean | true when an incoming message carries the sender's verified-name certificate. Omitted otherwise. A missing field does not establish whether the sender is a business. GET /user/info can provide additional upstream account metadata, but does not guarantee a definitive business classification. |
verified_name |
string | Business name from the upstream verified-name certificate. Present only with is_business and when the name is non-empty. |
verified_level |
string | Raw verification level reported with the certificate, as sent by WhatsApp. GOWA does not interpret this value or guarantee that it identifies an official badge. Present only with is_business and when WhatsApp sends it. |
Sender Display Name Resolution
sender_display_name is added only when payload.from is a non-empty string. It is omitted when from is missing,
empty, or not a singular string. Resolution is best-effort and never prevents a webhook from being delivered: a contact
lookup failure falls through the remaining applicable precedence candidates (including a live event push name when
available), then deterministically to the JID user part, or to the original from value when it cannot be parsed.
For another sender, the resolver prefers the saved contact full name, then the live WhatsApp push name supplied by the
event (when available), the stored contact push name, the contact business name, and the JID user part. For the active
account, it prefers the stored account push name, account JID user part, account JID, sender JID user part, and raw
sender JID. The label is resolved at webhook-build time, so a saved-contact rename can change labels on later events.
from_name remains the legacy message-event push name; it is a separate compatibility field and does not use this
resolution order.
Message Events
Text Message
{
"event": "message",
"device_id": "[email protected]",
"payload": {
"id": "3EB0C127D7BACC83D6A1",
"chat_id": "[email protected]",
"from": "[email protected]",
"from_lid": "251556368777322@lid",
"sender_display_name": "Saved Contact",
"from_name": "John Doe",
"timestamp": "2023-10-15T10:30:00Z",
"is_from_me": false,
"body": "Hello, how are you?"
}
}
Reply Message
{
"event": "message",
"device_id": "[email protected]",
"payload": {
"id": "3EB0C127D7BACC83D6A2",
"chat_id": "[email protected]",
"from": "[email protected]",
"sender_display_name": "Saved Contact",
"from_name": "John Doe",
"timestamp": "2023-10-15T10:35:00Z",
"is_from_me": false,
"body": "I'm doing great, thanks!",
"replied_to_id": "3EB0C127D7BACC83D6A1",
"quoted_body": "Hello, how are you?"
}
}
Reaction Message
{
"event": "message.reaction",
"device_id": "[email protected]",
"payload": {
"id": "88760C69D1F35FEB239102699AE9XXXX",
"chat_id": "[email protected]",
"from": "[email protected]",
"sender_display_name": "Saved Contact",
"from_name": "John Doe",
"timestamp": "2023-10-15T10:40:00Z",
"is_from_me": false,
"reaction": "👍",
"reacted_message_id": "3EB0C127D7BACC83D6A1"
}
}
Poll Messages
Poll creations, votes, edits, and added options keep the normal message event name. The structured poll object lets
existing WHATSAPP_WEBHOOK_EVENTS=message subscriptions receive poll interactions without another event allow-list.
Option hashes are lowercase hexadecimal SHA-256 hashes of the exact option names.
Poll creation:
{
"event": "message",
"device_id": "[email protected]",
"payload": {
"id": "POLL-1",
"chat_id": "[email protected]",
"body": "Poll: Lunch?",
"poll": {
"type": "creation",
"poll_id": "POLL-1",
"question": "Lunch?",
"options": [
{"name": "Pizza", "hash": "f12958816a49adfa2c6c8de8dd2144c163e92c5e375de964d533187c7d236c36"},
{"name": "Sushi", "hash": "670bd9ced0c6bc3fab9bcce97185cdb5a6c6008f0bb7a33c5e432b7faa0e27ed"}
],
"selectable_options_count": 1,
"version": "v3"
}
}
}
Resolved vote:
{
"event": "message",
"device_id": "[email protected]",
"payload": {
"id": "VOTE-1",
"chat_id": "[email protected]",
"body": "Poll vote: Sushi",
"poll": {
"type": "vote",
"poll_id": "POLL-1",
"question": "Lunch?",
"options": [
{"name": "Pizza", "hash": "f12958816a49adfa2c6c8de8dd2144c163e92c5e375de964d533187c7d236c36"},
{"name": "Sushi", "hash": "670bd9ced0c6bc3fab9bcce97185cdb5a6c6008f0bb7a33c5e432b7faa0e27ed"}
],
"selected_options": ["Sushi"],
"selected_option_hashes": ["670bd9ced0c6bc3fab9bcce97185cdb5a6c6008f0bb7a33c5e432b7faa0e27ed"],
"resolution_status": "resolved"
}
}
}
Clearing all choices is distinct from a resolution failure. Both arrays are present and empty:
{
"body": "Poll vote cleared",
"poll": {
"type": "vote",
"poll_id": "POLL-1",
"selected_options": [],
"selected_option_hashes": [],
"resolution_status": "resolved"
}
}
Resolution statuses:
| Status | Meaning |
|---|---|
resolved |
The vote decrypted and every selected hash matched a stored option. |
partially_resolved |
The vote decrypted, but one or more hashes did not match the stored definition. All hashes and the matched names are returned. |
definition_missing |
The vote decrypted, but the original poll definition was unavailable. Hashes are returned and names are empty. |
decrypt_failed |
The original WhatsApp message secret was missing or authentication failed. Known poll details are returned, but selection fields are omitted. |
Poll edits replace the stored definition and use "type": "edit". Add-option messages use "type": "add_option",
return the current full options list when known, and add an added_option object:
{
"body": "Poll option added: Ramen",
"poll": {
"type": "add_option",
"poll_id": "POLL-1",
"question": "Lunch?",
"options": [
{"name": "Pizza", "hash": "f12958816a49adfa2c6c8de8dd2144c163e92c5e375de964d533187c7d236c36"},
{"name": "Sushi", "hash": "670bd9ced0c6bc3fab9bcce97185cdb5a6c6008f0bb7a33c5e432b7faa0e27ed"},
{"name": "Ramen", "hash": "8930b1916b28f31f1e9c067cecce8301a2653982e8696f5b78d30229c3e0e988"}
],
"added_option": {"name": "Ramen", "hash": "8930b1916b28f31f1e9c067cecce8301a2653982e8696f5b78d30229c3e0e988"}
}
}
Poll definitions are persisted per device and chat from live messages, sent polls, and recent/bootstrap history sync, so
votes can normally be resolved after a restart. Decryption still depends on WhatsApp having delivered the original
message secret. Older/incomplete history and some upstream LID migration cases may therefore produce decrypt_failed;
the webhook is still delivered with a safe degraded payload.
Receipt Events
Receipt events are triggered when messages receive acknowledgments such as delivery confirmations and read receipts.
These events use the message.ack event type and provide information about message status changes.
Message Delivered
Triggered when a message is successfully delivered to the recipient's device.
{
"event": "message.ack",
"device_id": "[email protected]",
"timestamp": "2025-07-18T22:44:20Z",
"payload": {
"ids": [
"3EB00106E8BE0F407E88EC"
],
"chat_id": "[email protected]",
"from": "[email protected]",
"from_lid": "251556368777322@lid",
"sender_display_name": "Saved Contact",
"receipt_type": "delivered",
"receipt_type_description": "means the message was delivered to the device (but the user might not have noticed)."
}
}
Message Read
Triggered when a message is read by the recipient (they opened the chat and saw the message).
{
"event": "message.ack",
"device_id": "[email protected]",
"timestamp": "2025-07-18T22:44:44Z",
"payload": {
"ids": [
"3EB00106E8BE0F407E88EC"
],
"chat_id": "[email protected]",
"from": "[email protected]",
"sender_display_name": "Saved Contact",
"receipt_type": "read",
"receipt_type_description": "the user opened the chat and saw the message."
}
}
By default, contact receipts are forwarded from each user's primary device only, so a contact with several linked devices does not produce
duplicate events. Read receipts generated by the current account itself ("read", or "read-self" when read receipts
are disabled in privacy settings) are forwarded from any of its devices, so opening a chat on WhatsApp Web, Desktop or
another linked device is reported just like opening it on the phone. For these, payload.from is the account's own JID
(without the device suffix) and payload.ids are the IDs of the incoming messages that were read.
Set WHATSAPP_WEBHOOK_ALL_DEVICE_RECEIPTS=true or --webhook-all-device-receipts=true to also forward
contacts' linked-device receipts, including when their primary phone is offline. The flag overrides the environment
setting, including an explicit --webhook-all-device-receipts=false. This opt-in can produce duplicate or out-of-order
acknowledgements for the same message. Consumers should apply updates idempotently per account, chat and message ID,
and never downgrade a message from read to delivered when an older acknowledgement arrives. The payload continues
to use canonical message IDs and sender JIDs without device suffixes.
Receipt Event Fields
| Field | Type | Description |
|---|---|---|
event |
string | Always "message.ack" for receipt events |
device_id |
string | JID of the device that received this event |
timestamp |
string | RFC3339 formatted timestamp when the receipt was received |
payload.ids |
array | Array of message IDs that received the acknowledgment |
payload.chat_id |
string | Chat identifier (group or individual chat). A LID chat whose phone number is known is reported as that phone JID, as on message events |
payload.chat_lid |
string | Original LID chat identifier when WhatsApp supplied a LID before normalization, or a 1:1 chat's LID taken from recipient_alt |
payload.from |
string | JID of the user who triggered the receipt |
payload.from_lid |
string | LID of the user (if available) |
payload.sender_alt |
string | The user's other address (phone or LID), when WhatsApp supplied one |
payload.recipient_alt |
string | The recipient's other address (phone or LID) in a 1:1 chat, when WhatsApp supplied one |
payload.sender_display_name |
string | Dynamic sender label when payload.from is non-empty |
payload.receipt_type |
string | Type of receipt: "delivered", "read", etc. |
payload.receipt_type_description |
string | Human-readable description of the receipt type |
Chat Presence Events
Chat presence events are triggered when a contact starts or stops typing (or recording audio) in a chat.
These events use the chat_presence event type and are useful for implementing message batching strategies.
Note: WhatsApp only sends chat presence updates when the client is marked as online. GOWA defaults to
unavailable on connection, but the daily presence pulse periodically marks connected devices as available
and then returns them to unavailable.
User Typing
Triggered when a user starts typing a text message.
{
"event": "chat_presence",
"device_id": "[email protected]",
"timestamp": "2026-01-22T12:00:00Z",
"payload": {
"from": "[email protected]",
"sender_display_name": "Saved Contact",
"chat_id": "[email protected]",
"state": "composing",
"media": "",
"is_group": false
}
}
User Stopped Typing
Triggered when a user stops typing (pauses or clears the input field).
{
"event": "chat_presence",
"device_id": "[email protected]",
"timestamp": "2026-01-22T12:00:05Z",
"payload": {
"from": "[email protected]",
"sender_display_name": "Saved Contact",
"chat_id": "[email protected]",
"state": "paused",
"media": "",
"is_group": false
}
}
User Recording Audio
Triggered when a user starts recording a voice message.
{
"event": "chat_presence",
"device_id": "[email protected]",
"timestamp": "2026-01-22T12:01:00Z",
"payload": {
"from": "[email protected]",
"sender_display_name": "Saved Contact",
"chat_id": "[email protected]",
"state": "composing",
"media": "audio",
"is_group": false
}
}
Group Typing
Triggered when a user starts typing in a group chat.
{
"event": "chat_presence",
"device_id": "[email protected]",
"timestamp": "2026-01-22T12:02:00Z",
"payload": {
"from": "[email protected]",
"from_lid": "251556368777322@lid",
"sender_display_name": "Saved Contact",
"chat_id": "[email protected]",
"state": "composing",
"media": "",
"is_group": true
}
}
Chat Presence Event Fields
| Field | Type | Description |
|---|---|---|
event |
string | Always "chat_presence" for typing events |
device_id |
string | JID of the device that received this event |
timestamp |
string | RFC3339 formatted timestamp when the event was processed |
payload.from |
string | JID of the user who is typing (e.g., [email protected]) |
payload.from_lid |
string | LID of the user (if available, typically in group chats) |
payload.sender_display_name |
string | Dynamic sender label when payload.from is non-empty |
payload.chat_id |
string | Chat identifier (individual or group) |
payload.state |
string | Typing state: "composing" (typing) or "paused" (stopped) |
payload.media |
string | Media type: "" (text message) or "audio" (voice recording) |
payload.is_group |
boolean | Whether this is a group chat |
Presence Events
Presence events are triggered when a subscribed contact goes online or offline. Unlike chat presence
(typing), these require an explicit per-user subscription: call POST /user/presence/subscribe with
the contact's phone number first.
WhatsApp only delivers contact presence updates while your device is marked as available (online). For continuous tracking, set both options below:
WHATSAPP_PRESENCE_ON_CONNECT=available
WHATSAPP_PRESENCE_PULSE_ENABLED=false
The presence pulse is enabled by default. It marks the device unavailable after each pulse (default: five minutes), which stops contact presence updates until the device becomes available again. Disabling the pulse keeps it from overriding the available-on-connect setting.
Note: marking the device as available tells WhatsApp someone is actively using WhatsApp on the linked device, which suppresses push notifications on your phone while the server runs. If phone notifications matter, run the tracker on a secondary account or accept the trade-off.
{
"event": "presence",
"device_id": "[email protected]",
"timestamp": "2026-01-22T12:05:00Z",
"payload": {
"from": "[email protected]",
"state": "unavailable",
"last_seen": "2026-01-22T12:04:35Z"
}
}
{
"event": "presence",
"device_id": "[email protected]",
"timestamp": "2026-01-22T12:10:00Z",
"payload": {
"from": "[email protected]",
"state": "available"
}
}
Presence Event Fields
| Field | Type | Description |
|---|---|---|
event |
string | Always "presence" for online/offline events |
device_id |
string | JID of the device that received this event |
timestamp |
string | RFC3339 formatted timestamp when the event was processed |
payload.from |
string | JID of the user whose presence changed (e.g., [email protected]) |
payload.from_lid |
string | LID of the user (if applicable) |
payload.state |
string | Presence state: "available" (online) or "unavailable" (offline) |
payload.last_seen |
string | RFC3339 last-seen timestamp; omitted when the user hides last seen |
Note: payload.last_seen reflects the contact's own last-seen privacy setting. When it is
hidden from you, the field is omitted on offline events.
Label Events
Label events are triggered when WhatsApp label metadata changes or a label is applied to or removed from a chat. These
events come from WhatsApp app-state sync and are forwarded as label.edit or label.association.
Label Edit
Triggered when a WhatsApp label is created, renamed, reordered, activated/deactivated, or deleted.
{
"event": "label.edit",
"device_id": "[email protected]",
"timestamp": "2026-01-22T12:03:00Z",
"payload": {
"label_id": "9",
"name": "Important",
"color": 2,
"predefined_id": "1",
"deleted": false,
"order_index": 1,
"is_active": true,
"type": "CUSTOM",
"is_immutable": false,
"mute_end_time_ms": 0
}
}
Label Association
Triggered when a chat-level label is applied to or removed from a chat.
{
"event": "label.association",
"device_id": "[email protected]",
"timestamp": "2026-01-22T12:04:00Z",
"payload": {
"label_id": "9",
"labeled": true,
"chat_id": "[email protected]"
}
}
Label Event Fields
| Field | Type | Description |
|---|---|---|
event |
string | "label.edit" for label metadata changes, or "label.association" for chat labels |
device_id |
string | JID of the device that received this event |
timestamp |
string | RFC3339 formatted timestamp from the app-state event, or processing time fallback |
payload.label_id |
string | WhatsApp label identifier |
payload.name |
string | Label display name (only when included by WhatsApp on label.edit) |
payload.color |
number | Label color value (only when included by WhatsApp on label.edit) |
payload.predefined_id |
string | Predefined label identifier (only when included by WhatsApp on label.edit) |
payload.deleted |
boolean | Whether the label was deleted (only when included by WhatsApp on label.edit) |
payload.order_index |
number | Label ordering value (only when included by WhatsApp on label.edit) |
payload.is_active |
boolean | Whether the label is active (only when included by WhatsApp on label.edit) |
payload.type |
string | WhatsApp label type (only when included by WhatsApp on label.edit) |
payload.is_immutable |
boolean | Whether the label is immutable (only when included by WhatsApp on label.edit) |
payload.mute_end_time_ms |
number | Label mute end time in milliseconds (only when included by WhatsApp on label.edit) |
payload.labeled |
boolean | Whether the label was applied (true) or removed (false) on label.association |
payload.chat_id |
string | Chat JID associated with the label on label.association |
payload.chat_lid |
string | Original LID chat identifier when WhatsApp supplied a LID before normalization |
Group Events
Group events are triggered when group metadata changes. Member join/leave events and admin promotions/demotions use the
group.participants event type. Group name (subject) changes use the group.info event type.
Group Member Join
Triggered when users join or are added to a group.
{
"event": "group.participants",
"device_id": "[email protected]",
"timestamp": "2025-07-28T10:30:00Z",
"payload": {
"chat_id": "[email protected]",
"type": "join",
"jids": [
"[email protected]",
"[email protected]"
]
}
}
Group Member Leave
Triggered when users leave or are removed from a group.
{
"event": "group.participants",
"device_id": "[email protected]",
"timestamp": "2025-07-28T10:32:00Z",
"payload": {
"chat_id": "[email protected]",
"type": "leave",
"jids": [
"[email protected]"
]
}
}
Group Member Promotion
Triggered when users are promoted to admin.
{
"event": "group.participants",
"device_id": "[email protected]",
"timestamp": "2025-07-28T10:33:00Z",
"payload": {
"chat_id": "[email protected]",
"type": "promote",
"jids": [
"[email protected]"
]
}
}
Group Member Demotion
Triggered when users are demoted from admin.
{
"event": "group.participants",
"device_id": "[email protected]",
"timestamp": "2025-07-28T10:34:00Z",
"payload": {
"chat_id": "[email protected]",
"type": "demote",
"jids": [
"[email protected]"
]
}
}
Group Participant Event Fields
| Field | Type | Description |
|---|---|---|
event |
string | Always "group.participants" for participant events |
device_id |
string | JID of the device that received this event |
timestamp |
string | RFC3339 formatted timestamp when the group event occurred |
payload.chat_id |
string | Group identifier (e.g., "[email protected]") |
payload.type |
string | Action type: "join", "leave", "promote", or "demote" |
payload.jids |
array | Array of user JIDs affected by this action |
Group Name Change
Triggered when a group's name (subject) is changed, by any participant or by this device. This event uses the
group.info event type.
{
"event": "group.info",
"device_id": "[email protected]",
"timestamp": "2025-07-28T10:35:00Z",
"payload": {
"chat_id": "[email protected]",
"name": "Project Team",
"name_set_by": "[email protected]"
}
}
| Field | Type | Description |
|---|---|---|
event |
string | Always "group.info" |
device_id |
string | JID of the device that received this event |
timestamp |
string | RFC3339 formatted timestamp when the name was changed |
payload.chat_id |
string | Group identifier (e.g., "[email protected]") |
payload.name |
string | The new group name |
payload.name_set_by |
string | JID of the user who changed the name, resolved from LID to phone number when possible. Omitted when WhatsApp does not say who changed it |
Newsletter Events
Newsletter events are triggered when you interact with WhatsApp Channels (newsletters). These include subscribing, unsubscribing, receiving new messages, and mute setting changes.
Newsletter Joined
Triggered when you subscribe to a newsletter/channel.
{
"event": "newsletter.joined",
"device_id": "[email protected]",
"timestamp": "2026-01-18T12:00:00Z",
"payload": {
"newsletter_id": "120363123456789@newsletter",
"name": "Tech News Daily",
"description": "Latest tech updates and news"
}
}
Newsletter Left
Triggered when you unsubscribe from a newsletter/channel.
{
"event": "newsletter.left",
"device_id": "[email protected]",
"timestamp": "2026-01-18T12:00:00Z",
"payload": {
"newsletter_id": "120363123456789@newsletter",
"role": "subscriber"
}
}
Newsletter Message
Triggered by live counter updates of a channel. WhatsApp only sends them while the device holds a live updates
subscription for that channel: subscribe with POST /newsletter/live-updates (GOWA keeps renewing it). Updates usually
carry only counters, so message_id, type and timestamp are present only when WhatsApp includes them. New posts of
followed channels are delivered as regular message events whose chat_id ends with @newsletter.
{
"event": "newsletter.message",
"device_id": "[email protected]",
"timestamp": "2026-01-18T12:00:00Z",
"payload": {
"newsletter_id": "120363123456789@newsletter",
"messages": [
{
"server_id": 123,
"forwards_count": 42,
"reaction_counts": {"👍": 50, "❤️": 25}
}
]
}
}
Newsletter Mute
Triggered when you mute or unmute a newsletter.
{
"event": "newsletter.mute",
"device_id": "[email protected]",
"timestamp": "2026-01-18T12:00:00Z",
"payload": {
"newsletter_id": "120363123456789@newsletter",
"mute": "on"
}
}
Newsletter Event Fields
| Field | Type | Description |
|---|---|---|
event |
string | Event type (see table above) |
device_id |
string | JID of the device that received this event |
timestamp |
string | RFC3339 formatted timestamp |
payload.newsletter_id |
string | Newsletter identifier (e.g., 120363...@newsletter) |
payload.name |
string | Newsletter name (only in newsletter.joined) |
payload.description |
string | Newsletter description (only in newsletter.joined) |
payload.role |
string | Your role in the newsletter (only in newsletter.left) |
payload.mute |
string | Mute state: "on" or "off" (only in newsletter.mute) |
payload.messages |
array | Array of messages (only in newsletter.message) |
payload.messages[].server_id |
number | Server-assigned message ID |
payload.messages[].message_id |
string | Message identifier (if available) |
payload.messages[].type |
string | Message type (e.g., "text", "media") (if available) |
payload.messages[].timestamp |
string | Message timestamp (if available) |
payload.messages[].views_count |
number | Number of views (only reported to channel admins) |
payload.messages[].forwards_count |
number | Number of forwards (if available) |
payload.messages[].reaction_counts |
object | Reaction emoji counts (if available) |
Call Events
Call events are triggered when you receive an incoming WhatsApp call. You can optionally auto-reject calls using the
WHATSAPP_AUTO_REJECT_CALL environment variable or --auto-reject-call CLI flag.
When chat storage is enabled, each incoming call is also persisted as a synthetic message in the chat history:
media_type is call, content is Incoming call, and call_metadata (JSON) holds call_id, auto_rejected, and
optional remote_platform, remote_version, and group_jid. List chat messages via the REST/MCP chat APIs to retrieve these rows.
Call Offer
Triggered when an incoming call is received.
{
"event": "call.offer",
"device_id": "[email protected]",
"timestamp": "2026-02-05T12:00:00Z",
"payload": {
"call_id": "ABC123DEF456",
"from": "[email protected]",
"sender_display_name": "Saved Contact",
"auto_rejected": false,
"remote_platform": "android",
"remote_version": "2.24.1.5"
}
}
Call Offer with Auto-Reject Enabled
When WHATSAPP_AUTO_REJECT_CALL=true, calls are automatically rejected and the webhook includes this status:
{
"event": "call.offer",
"device_id": "[email protected]",
"timestamp": "2026-02-05T12:00:00Z",
"payload": {
"call_id": "ABC123DEF456",
"from": "[email protected]",
"sender_display_name": "Saved Contact",
"auto_rejected": true,
"remote_platform": "android",
"remote_version": "2.24.1.5",
"group_jid": "[email protected]"
}
}
Call Event Fields
| Field | Type | Description |
|---|---|---|
event |
string | Always "call.offer" for call events |
device_id |
string | JID of the device that received this event |
timestamp |
string | RFC3339 formatted timestamp when the call was received |
payload.call_id |
string | Unique identifier for the call |
payload.from |
string | JID of the caller |
payload.sender_display_name |
string | Dynamic sender label when payload.from is non-empty |
payload.auto_rejected |
boolean | Whether the call was auto-rejected |
payload.remote_platform |
string | Platform of the caller (e.g., "android", "ios") |
payload.remote_version |
string | WhatsApp version of the caller |
payload.group_jid |
string | Group JID if this is a group call (optional) |
Configuration
Environment Variable:
# Auto-reject all incoming calls
WHATSAPP_AUTO_REJECT_CALL=true
CLI Flag:
# Auto-reject all incoming calls
./whatsapp rest --auto-reject-call=true
Reject Call via API
In addition to auto-rejecting all calls, you can programmatically reject specific calls using the REST API. This is useful when you want to apply custom logic (e.g., time-of-day rules, caller whitelists, or agent availability checks).
Endpoint: POST /call/reject
Headers:
X-Device-Id: <device_id>
Content-Type: application/json
Request Body:
{
"caller_jid": "[email protected]",
"call_id": "ABC123DEF456"
}
Where to get these values:
When you receive a call.offer webhook event, extract the values from the payload:
{
"event": "call.offer",
"device_id": "[email protected]",
"payload": {
"call_id": "ABC123DEF456",
"from": "[email protected]",
"sender_display_name": "Saved Contact",
"auto_rejected": false
}
}
caller_jid→ Usepayload.fromfrom the webhookcall_id→ Usepayload.call_idfrom the webhook
Example (curl):
curl -X POST http://localhost:3000/call/reject \
-H "X-Device-Id: [email protected]" \
-H "Content-Type: application/json" \
-d '{
"caller_jid": "[email protected]",
"call_id": "ABC123DEF456"
}'
Example (JavaScript/Node.js):
const axios = require('axios');
// When you receive a call.offer webhook event
app.post('/webhook', async (req, res) => {
const { event, payload, device_id } = req.body;
if (event === 'call.offer' && !payload.auto_rejected) {
// Apply your custom logic here
const shouldReject = checkBusinessHours() || isBlacklisted(payload.from);
if (shouldReject) {
try {
await axios.post('http://localhost:3000/call/reject', {
caller_jid: payload.from,
call_id: payload.call_id
}, {
headers: {
'X-Device-Id': device_id,
'Content-Type': 'application/json'
}
});
console.log(`Rejected call from ${payload.from}`);
} catch (error) {
console.error('Failed to reject call:', error.message);
}
}
}
res.sendStatus(200);
});
Important Notes:
- Timing: The call must still be ringing. Rejection will fail if the call has already ended or been answered.
- Device-scoped: The
X-Device-Idheader is required and must match the device that received the call. - Error handling: If the call has already ended, the API will return an error. Handle this gracefully in your application.
- Complementary to auto-reject: If
WHATSAPP_AUTO_REJECT_CALL=true, all calls are rejected automatically before the webhook is sent. The API is for selective rejection when auto-reject is disabled.
Webhook Integration Pattern:
- Enable
call.offerinWHATSAPP_WEBHOOK_EVENTS - Set up a webhook receiver endpoint in your application
- When a
call.offerevent arrives, apply your business logic - If the call should be rejected, call
POST /call/rejectwith the values from the webhook payload - The call is rejected on WhatsApp, and the caller sees a "declined" status
Device Events
Device events report what WhatsApp tells a device about its account: a logout and its reason, a temporary ban, or a restriction on starting new chats. Without them a temporary ban only shows as a disconnected device, and a reach-out timelock only shows as sends failing with error 463.
The codes are WhatsApp's, forwarded unchanged; the reason texts are whatsmeow's descriptions of them. A code whatsmeow does not know is still forwarded, with its generic reason text. Device events are not sent to Chatwoot.
session_id is always set on device events, to the slot the event is about, so slots that share one WhatsApp number
can be told apart.
Device Logged Out
Triggered when the device is logged out remotely: unlinked from the phone, or logged out by WhatsApp. The device slot
is kept for re-pairing, as before. device_id and session_id are the ones the device had before the logout.
{
"event": "device.logged_out",
"device_id": "[email protected]",
"session_id": "org_2",
"timestamp": "2026-10-28T09:00:00Z",
"payload": {
"code": 401,
"reason": "logged out from another device",
"on_connect": true
}
}
code |
reason |
Notes |
|---|---|---|
| 401 | logged out from another device | The usual code when the device is removed from the phone |
| 403 | primary device was logged out | Called LOCKED in WhatsApp Web; seen both on bans and when switching phones |
| 406 | logged out for unknown reason | Called BANNED in WhatsApp Web |
Device Temporary Ban
Triggered when WhatsApp refuses the connection because the account is temporarily banned. The session is kept, so the device can connect again once the ban expires.
{
"event": "device.temporary_ban",
"device_id": "[email protected]",
"session_id": "org_2",
"timestamp": "2026-10-28T09:00:00Z",
"payload": {
"code": 101,
"reason": "you sent too many messages to people who don't have you in their address books",
"expires_in_seconds": 86400,
"expires_at": "2026-10-29T09:00:00Z"
}
}
code |
reason |
|---|---|
| 101 | you sent too many messages to people who don't have you in their address books |
| 102 | too many people blocked you |
| 103 | you created too many groups with people who don't have you in their address books |
| 104 | you sent the same message to too many people |
| 106 | you sent too many messages to a broadcast list |
Device Reach-out Timelock
Triggered when WhatsApp notifies the account that it is restricted from starting new chats. While the restriction is
active, sends to people the account has no conversation with fail with error 463. is_active is false when WhatsApp
reports the restriction as no longer active.
{
"event": "device.reachout_timelock",
"device_id": "[email protected]",
"session_id": "org_2",
"timestamp": "2026-10-28T09:00:00Z",
"payload": {
"is_active": true,
"ends_at": "2026-10-28T21:00:00Z"
}
}
Device Event Fields
| Field | Type | Description |
|---|---|---|
event |
string | device.logged_out, device.temporary_ban or device.reachout_timelock |
device_id |
string | JID of the device the event is about; omitted when the slot has no JID yet |
session_id |
string | Slot ID: the ID registered via POST /devices, or a WhatsApp JID for slots gowa created; always set |
timestamp |
string | RFC3339 formatted timestamp when the event was received |
payload.code |
number | Logged out and temporary ban: the reason code |
payload.reason |
string | Logged out and temporary ban: whatsmeow's description of the code |
payload.on_connect |
boolean | Logged out: true when WhatsApp refused the connection, false when it closed an open one |
payload.expires_in_seconds |
number | Temporary ban: seconds until the ban expires, as WhatsApp reported it; 0 when it gave none |
payload.expires_at |
string | Temporary ban: RFC3339 expiry, computed from expires_in_seconds when the event was received; omitted when unknown |
payload.is_active |
boolean | Reach-out timelock: whether the restriction is in force |
payload.enforcement_type |
string | Reach-out timelock: WhatsApp's enforcement type, passed through unchanged; omitted when empty |
payload.ends_at |
string | Reach-out timelock: RFC3339 time the restriction ends; omitted when WhatsApp gave none |
Media Messages
Image Message
When WHATSAPP_AUTO_DOWNLOAD_MEDIA is enabled, media is downloaded and image contains the file path.
When disabled, image contains an object with the URL.
If a caption is present, it is included in the top-level body field (consistent with text messages).
When auto-download is enabled and a caption exists, image becomes an object with path and caption.
When no caption exists, image remains a plain file path string for backward compatibility.
With auto-download enabled (no caption):
{
"event": "message",
"device_id": "[email protected]",
"payload": {
"id": "3EB0C127D7BACC83D6A3",
"chat_id": "[email protected]",
"from": "[email protected]",
"from_name": "John Doe",
"timestamp": "2025-07-13T11:05:51Z",
"image": "statics/media/1752404751-ad9e37ac-c658-4fe5-8d25-ba4a3f4d58fd.jpeg"
}
}
With auto-download enabled (with caption):
{
"event": "message",
"device_id": "[email protected]",
"payload": {
"id": "3EB0C127D7BACC83D6A3",
"chat_id": "[email protected]",
"from": "[email protected]",
"from_name": "John Doe",
"timestamp": "2025-07-13T11:05:51Z",
"body": "Check this out!",
"image": {
"path": "statics/media/1752404751-ad9e37ac-c658-4fe5-8d25-ba4a3f4d58fd.jpeg",
"caption": "Check this out!"
}
}
}
With auto-download disabled:
{
"event": "message",
"device_id": "[email protected]",
"payload": {
"id": "3EB0C127D7BACC83D6A3",
"chat_id": "[email protected]",
"from": "[email protected]",
"from_name": "John Doe",
"timestamp": "2025-07-13T11:05:51Z",
"body": "Check this out!",
"image": {
"url": "https://mmg.whatsapp.net/...",
"caption": "Check this out!"
}
}
}
Video Message
{
"event": "message",
"device_id": "[email protected]",
"payload": {
"id": "3EB0C127D7BACC83D6A4",
"chat_id": "[email protected]",
"from": "[email protected]",
"from_name": "John Doe",
"timestamp": "2025-07-13T11:07:24Z",
"body": "Watch this!",
"video": {
"path": "statics/media/1752404845-b9393cd1-8546-4df9-8a60-ee3276036aba.mp4",
"caption": "Watch this!"
}
}
}
Audio Message
{
"event": "message",
"device_id": "[email protected]",
"payload": {
"id": "3EB0C127D7BACC83D6A5",
"chat_id": "[email protected]",
"from": "[email protected]",
"from_name": "John Doe",
"timestamp": "2023-10-15T10:55:00Z",
"audio": "statics/media/1752404905-b9393cd1-8546-4df9-8a60-ee3276036aba.ogg"
}
}
Document Message
{
"event": "message",
"device_id": "[email protected]",
"payload": {
"id": "3EB0C127D7BACC83D6A6",
"chat_id": "[email protected]",
"from": "[email protected]",
"from_name": "John Doe",
"timestamp": "2023-10-15T11:00:00Z",
"body": "Monthly report",
"document": {
"path": "statics/media/1752404965-document.pdf",
"caption": "Monthly report"
}
}
}
With auto-download disabled:
{
"event": "message",
"device_id": "[email protected]",
"payload": {
"id": "3EB0C127D7BACC83D6A6",
"chat_id": "[email protected]",
"from": "[email protected]",
"from_name": "John Doe",
"timestamp": "2023-10-15T11:00:00Z",
"body": "Monthly report",
"document": {
"url": "https://mmg.whatsapp.net/...",
"filename": "report.pdf"
}
}
}
Sticker Message
{
"event": "message",
"device_id": "[email protected]",
"payload": {
"id": "446AC2BAF2061B53E24CA526DBDFBD4E",
"chat_id": "[email protected]",
"from": "[email protected]",
"from_name": "John Doe",
"timestamp": "2025-07-13T11:09:45Z",
"sticker": "statics/media/1752404986-ff2464a6-c54c-4e6c-afde-c4c925ce3573.webp"
}
}
Video Note Message
{
"event": "message",
"device_id": "[email protected]",
"payload": {
"id": "3EB0C127D7BACC83D6A7",
"chat_id": "[email protected]",
"from": "[email protected]",
"from_name": "John Doe",
"timestamp": "2023-10-15T11:02:00Z",
"video_note": "statics/media/1752404990-videonote.mp4"
}
}
Special Message Types
Contact Message
When a user shares a single contact:
{
"event": "message",
"device_id": "[email protected]",
"payload": {
"id": "56B3DFF4994284634E7AAFEEF6F1A0A2",
"chat_id": "[email protected]",
"from": "[email protected]",
"from_name": "John Doe",
"timestamp": "2025-07-13T11:10:19Z",
"contact": {
"displayName": "3Care",
"vcard": "BEGIN:VCARD\nVERSION:3.0\nN:;3Care;;;\nFN:3Care\nTEL;type=Mobile:+62 132\nEND:VCARD",
"phone_number": "+62 132"
}
}
}
Contacts Array Message
When a user shares multiple contacts at once (via WhatsApp's multi-contact share feature):
{
"event": "message",
"device_id": "[email protected]",
"payload": {
"id": "A1B2C3D4E5F6789012345678",
"chat_id": "[email protected]",
"from": "[email protected]",
"from_name": "John Doe",
"timestamp": "2025-07-13T11:10:19Z",
"contacts_array": [
{
"displayName": "Alice",
"vcard": "BEGIN:VCARD\nVERSION:3.0\nN:;Alice;;;\nFN:Alice\nTEL;type=Mobile:+62 812 3456 7890\nEND:VCARD",
"phone_number": "+62 812 3456 7890"
},
{
"displayName": "Bob",
"vcard": "BEGIN:VCARD\nVERSION:3.0\nN:;Bob;;;\nFN:Bob\nTEL;type=Mobile:+62 813 9876 5432\nEND:VCARD",
"phone_number": "+62 813 9876 5432"
}
]
}
}
Note: WhatsApp uses
ContactMessage(field 4) for a single contact andContactsArrayMessage(field 13) for multiple contacts. A single contact produces"contact", while multiple contacts produce"contacts_array".
Business Template Message
Sent by WhatsApp Business / Cloud API senders (order confirmations, OTPs, booking updates):
{
"event": "message",
"device_id": "[email protected]",
"payload": {
"id": "3EB0A1B2C3D4E5F60718",
"chat_id": "[email protected]",
"from": "[email protected]",
"from_name": "Acme Store",
"timestamp": "2026-09-25T10:00:00Z",
"body": "Order confirmed\nHi John, your order #1234 has shipped.\nAcme Store\n🔗 Track order: https://acme.example/track/1234\n📞 Call us: +15550100\n[Stop updates]",
"template": {
"title": "Order confirmed",
"body": "Hi John, your order #1234 has shipped.",
"footer": "Acme Store",
"template_id": "order_confirmed",
"buttons": [
{ "type": "url", "text": "Track order", "url": "https://acme.example/track/1234" },
{ "type": "call", "text": "Call us", "phone_number": "+15550100" },
{ "type": "quick_reply", "text": "Stop updates", "id": "stop" }
]
}
}
}
bodyis the whole message as plain text: title, body and footer, then one line per button. Chat storage keeps the same text, and Chatwoot receives it with its usual WhatsApp-to-Markdown conversion. A template with no text getsTemplate message.buttons[].typeisurl,call,quick_replyorcopy(codeholds the value to copy). Other native-flow buttons keep their name as the type.- A
single_selectbutton lists its options inrows(id,title,description). header_typeis set when the header is media:image,video,document,locationorproduct. The header media itself is not included.- Templates wrapping an interactive message use the same shape, plus
subtitle, andcardsfor carousels. Theirbodyis rendered like an interactive message ([quick_reply] Stop updates,Card 1: …, andInteractive messagewhen empty). - Interactive, list and order messages keep their
interactive(the same text asbody),listandorder(raw WhatsApp message fields) keys, and get a plain-textbodytoo:List: <title>orOrder: <title>first, then the remaining text and list rows.
Buttons Message
Same shape as a template, under buttons. body renders it the same way (Buttons message when there is no text). A top-level interactive message with native-flow buttons (Cloud API reply buttons, CTAs, single select) also fills buttons, next to its interactive text — so a client can tell it apart and answer it as a native-flow reply:
"buttons": {
"title": "Support",
"body": "Please choose the service",
"footer": "Reply with a button",
"buttons": [
{ "type": "quick_reply", "text": "Sales", "id": "sales" },
{ "type": "quick_reply", "text": "Support", "id": "support" }
]
}
Product Message
Prices are in WhatsApp's unit (amount × 1000). body is Product: <title> (<currency> <price>) with the price in major units, e.g. Product: Weekend package (IDR 3500.00), using the sale price when set, followed by the message body and footer:
"product": {
"product_id": "p-77",
"title": "Weekend package",
"description": "2 nights, breakfast included",
"currency_code": "IDR",
"price_amount_1000": 3500000,
"catalog_title": "Packages",
"business_owner_jid": "[email protected]"
}
List / Button Reply
A tap on a list row, a button, a template quick reply or a native-flow button. selected_id matches the list row's rowID or the button id:
"selection": {
"kind": "list",
"text": "Void PNR",
"description": "Cancel the booking",
"selected_id": "row-void-pnr"
}
kindislist,buttons,templateorinteractive(native-flow replies, whoseselected_idcomes from the reply'sidparam).bodyis the selected text, falling back todescription. Recent clients often send replies with only the id;bodyis thenSelected option <selected_id>, orSelection messagewhen there is nothing at all.
Location Message
{
"event": "message",
"device_id": "[email protected]",
"payload": {
"id": "3EB0C127D7BACC83D6A9",
"chat_id": "[email protected]",
"from": "[email protected]",
"from_name": "John Doe",
"timestamp": "2023-10-15T11:15:00Z",
"location": {
"degreesLatitude": -6.2088,
"degreesLongitude": 106.8456,
"name": "Jakarta, Indonesia",
"address": "Central Jakarta, DKI Jakarta, Indonesia"
}
}
}
Live Location Message
{
"event": "message",
"device_id": "[email protected]",
"payload": {
"id": "94D13237B4D7F33EE4A63228BBD79EC0",
"chat_id": "[email protected]",
"from": "[email protected]",
"from_name": "John Doe",
"timestamp": "2025-07-13T11:11:22Z",
"live_location": {
"degreesLatitude": -7.8050297,
"degreesLongitude": 110.4549165
}
}
}
Protocol Messages
Message Deleted
Triggered when a message is deleted for the current user (DeleteForMe event).
{
"event": "message.deleted",
"device_id": "[email protected]",
"payload": {
"deleted_message_id": "3EB0C127D7BACC83D6A1",
"timestamp": "2025-07-13T11:12:00Z",
"from": "[email protected]",
"sender_display_name": "Saved Contact",
"chat_id": "[email protected]",
"original_content": "Hello, how are you?",
"original_sender": "[email protected]",
"original_timestamp": "2025-07-13T10:30:00Z",
"was_from_me": false
}
}
Fields:
| Field | Type | Description |
|---|---|---|
payload.deleted_message_id |
string | ID of the deleted message |
payload.timestamp |
string | RFC3339 timestamp when the delete event occurred |
payload.from |
string | JID of the user who deleted the message |
payload.from_lid |
string | LID of the user who deleted the message, when the event named them by LID |
payload.sender_display_name |
string | Dynamic sender label when payload.from is non-empty |
payload.chat_id |
string | Chat identifier where the message was deleted |
payload.chat_lid |
string | Original LID chat identifier when the event named the chat by LID |
payload.original_content |
string | Original message content (if available from storage) |
payload.original_sender |
string | Original sender of the deleted message |
payload.original_timestamp |
string | Original message timestamp |
payload.was_from_me |
boolean | Whether the deleted message was sent by current user |
payload.original_media_type |
string | Media type if the message contained media (optional) |
payload.original_filename |
string | Filename if the message contained media (optional) |
Message Revoked
{
"event": "message.revoked",
"device_id": "[email protected]",
"payload": {
"id": "F4062F2BBCB19B7432195AD7080DA4E2",
"chat_id": "[email protected]",
"from": "[email protected]",
"from_name": "John Doe",
"timestamp": "2025-07-13T11:13:30Z",
"is_from_me": true,
"revoked_message_id": "94D13237B4D7F33EE4A63228BBD79EC0",
"revoked_from_me": true,
"revoked_chat": "[email protected]"
}
}
Message Edited
When a message is edited, the webhook includes the original message ID to track which message was modified.
{
"event": "message.edited",
"device_id": "[email protected]",
"payload": {
"id": "D6271D8223A05B4DA6AE9FE3CD632543",
"chat_id": "[email protected]",
"from": "[email protected]",
"from_name": "John Doe",
"timestamp": "2025-07-13T11:14:19Z",
"is_from_me": false,
"original_message_id": "94D13237B4D7F33EE4A63228BBD79EC0",
"body": "Updated message text"
}
}
Fields:
original_message_id: The ID of the message that was edited (use this to update the correct message in your database)body: The new text content after editingid: The ID of the edit event itself (different from the original message ID)
Special Flags
View Once Message
{
"event": "message",
"device_id": "[email protected]",
"payload": {
"id": "3EB0C127D7BACC83D6B2",
"chat_id": "[email protected]",
"from": "[email protected]",
"from_name": "John Doe",
"timestamp": "2023-10-15T11:40:00Z",
"image": "statics/media/1752405060-image.jpeg",
"view_once": true
}
}
Media Album
When several photos or videos are sent together, WhatsApp first sends an album header that only announces how many items
follow, then each item as a regular image or video message. The header is forwarded with an album object (and no body):
{
"event": "message",
"device_id": "[email protected]",
"payload": {
"id": "3EB0A1B2C3D4E5F6A7B8",
"chat_id": "[email protected]",
"from": "[email protected]",
"from_name": "John Doe",
"timestamp": "2023-10-15T11:42:00Z",
"album": {
"expected_image_count": 3,
"expected_video_count": 1
}
}
}
Each item carries album_id, the id of its header, so the items can be grouped:
{
"event": "message",
"device_id": "[email protected]",
"payload": {
"id": "3EB0F1E2D3C4B5A6F7E8",
"chat_id": "[email protected]",
"from": "[email protected]",
"from_name": "John Doe",
"timestamp": "2023-10-15T11:42:01Z",
"image": "statics/media/1752405121-image.jpeg",
"album_id": "3EB0A1B2C3D4E5F6A7B8"
}
}
The header is not forwarded to Chatwoot, since it has no content of its own.
Forwarded Message
{
"event": "message",
"device_id": "[email protected]",
"payload": {
"id": "3EB0C127D7BACC83D6B3",
"chat_id": "[email protected]",
"from": "[email protected]",
"from_name": "John Doe",
"timestamp": "2023-10-15T11:45:00Z",
"body": "This is a forwarded message",
"forwarded": true
}
}
Meta Ads Referral (Click-to-WhatsApp)
When a conversation starts from a Meta Click-to-WhatsApp ad, the first inbound message includes ad attribution metadata in the referral field. This is extracted from the WhatsApp protocol's contextInfo.externalAdReply.
{
"event": "message",
"device_id": "[email protected]",
"payload": {
"id": "3EB0C127D7BACC83D6B4",
"chat_id": "[email protected]",
"from": "[email protected]",
"from_name": "Jane Customer",
"timestamp": "2023-10-15T12:00:00Z",
"is_from_me": false,
"body": "Hello! I would like more information about the property.",
"referral": {
"ctwa_clid": "FAKE_CLID_abc123xyz",
"source_url": "https://fb.me/fake-ad-link",
"source_id": "123456789012345",
"ref": "landing_page_01",
"source_app": "facebook",
"media_type": "IMAGE",
"ad_title": "Your Dream Farm",
"ad_body": "Discover exclusive rural properties in the countryside.",
"thumbnail_url": "https://example.com/ad-thumbnail.jpg",
"original_image_url": "https://example.com/ad-image.jpg",
"show_ad_attribution": true,
"click_to_whatsapp_call": false,
"contains_auto_reply": false,
"automated_greeting_message_shown": true,
"greeting_message_body": "Hello! I want to know more about this ad.",
"source_type": "ad",
"ad_type": "CTWA"
}
}
}
Referral fields (all optional, only present when the message originated from a Meta ad):
| Field | Type | Description |
|---|---|---|
ctwa_clid |
string | Meta Click-to-WhatsApp click ID for ad attribution |
source_url |
string | Landing page / ad destination URL |
source_id |
string | Meta ad creative or ad set ID |
ref |
string | The ref parameter set on the WhatsApp button in the ad |
source_app |
string | Origin platform: "facebook" or "instagram" |
media_type |
string | Ad creative media type: "NONE", "IMAGE", or "VIDEO" |
ad_title |
string | Ad creative title |
ad_body |
string | Ad creative description/body text |
thumbnail_url |
string | URL of the ad thumbnail image |
original_image_url |
string | URL of the original ad image |
media_url |
string | URL of the ad media |
show_ad_attribution |
boolean | Whether to show the ad attribution badge |
contains_auto_reply |
boolean | Whether the ad has a pre-filled auto-reply message |
automated_greeting_message_shown |
boolean | Whether the automated greeting was shown to the user |
greeting_message_body |
string | Body text of the automated greeting message |
click_to_whatsapp_call |
boolean | Whether this is a Click-to-WhatsApp Call ad (vs chat) |
source_type |
string | Source type (e.g., "ad") |
ad_type |
string | Ad type: "CTWA" (Click-to-WhatsApp) or "CAWC" (Click-to-Call) |
Conversion Attribution and Media Metadata
Regular message events may also carry conversion attribution, media metadata and a few contextInfo values. They are
read from the message's own contextInfo (never from a quoted message) after unwrapping ephemeral and view-once
containers. Every field is optional: a key is present only when WhatsApp sent a non-empty, non-zero value, and
conversion or media_info is omitted entirely when it would be empty.
{
"event": "message",
"device_id": "[email protected]",
"payload": {
"id": "3EB0C127D7BACC83D6B5",
"chat_id": "[email protected]",
"from": "[email protected]",
"from_name": "Jane Customer",
"timestamp": "2023-10-15T12:05:00Z",
"is_from_me": false,
"body": "Is this still available?",
"image": {
"url": "https://mmg.whatsapp.net/...",
"caption": "Is this still available?"
},
"conversion": {
"conversion_source": "FB_Ads",
"conversion_data": "AQI=",
"entry_point_conversion_source": "ctwa_ad",
"entry_point_conversion_app": "instagram",
"entry_point_conversion_delay_seconds": 4
},
"media_info": {
"mime_type": "image/jpeg",
"file_length": 204800,
"file_sha256": "n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is0V1sFbDwCgg=",
"width": 1080,
"height": 1350
},
"forwarding_score": 6,
"mentioned_jids": ["[email protected]"],
"expiration": 86400
}
}
Conversion fields (conversion, from contextInfo):
| Field | Type | Description |
|---|---|---|
conversion_source |
string | Conversion source reported by WhatsApp (e.g., "FB_Ads") |
conversion_data |
string | Opaque conversion data, standard base64-encoded |
conversion_delay_seconds |
integer | Delay between the conversion and the message, in seconds |
entry_point_conversion_source |
string | Entry point that opened the chat (e.g., "ctwa_ad") |
entry_point_conversion_app |
string | App the entry point came from (e.g., "instagram", "facebook") |
entry_point_conversion_delay_seconds |
integer | Delay between the entry point and the message, in seconds |
entry_point_conversion_external_source |
string | External source of the entry point |
entry_point_conversion_external_medium |
string | External medium of the entry point |
Media metadata fields (media_info, for image, video, video note, audio, document and sticker messages). It
describes the media without download URLs or keys, and is present whether or not WHATSAPP_AUTO_DOWNLOAD_MEDIA is
enabled:
| Field | Type | Description |
|---|---|---|
mime_type |
string | MIME type of the media |
file_name |
string | Original file name (documents only) |
file_length |
integer | File size in bytes |
file_sha256 |
string | SHA-256 of the decrypted file, standard base64-encoded |
width |
integer | Width in pixels (image, video, video note and sticker) |
height |
integer | Height in pixels (image, video, video note and sticker) |
seconds |
integer | Duration in seconds (audio, video and video note) |
ptt |
boolean | true for voice notes; omitted otherwise |
is_animated |
boolean | true for animated stickers; omitted otherwise |
gif_playback |
boolean | true for videos sent as GIFs; omitted otherwise |
Context fields (top level of payload, from contextInfo):
| Field | Type | Description |
|---|---|---|
forwarding_score |
integer | How many times the message has been forwarded |
mentioned_jids |
array | JIDs mentioned in the message; LIDs are resolved to phone JIDs when possible, as with from |
expiration |
integer | Disappearing-message timer of the chat, in seconds |
Integration Guide
Setting Up Webhook Endpoint
Configure webhook URL(s):
./whatsapp rest --webhook="https://yourapp.com/webhook"Set webhook secret:
./whatsapp rest --webhook-secret="your-secret-key"Multiple webhooks:
./whatsapp rest --webhook="https://app1.com/webhook,https://app2.com/webhook"
Webhook Endpoint Implementation (Express.js)
const express = require('express');
const crypto = require('crypto');
const app = express();
app.use(express.raw({type: 'application/json'}));
app.post('/webhook', (req, res) => {
const signature = req.headers['x-hub-signature-256'];
const payload = req.body;
const secret = 'your-secret-key';
// Verify signature
if (!verifyWebhookSignature(payload, signature, secret)) {
return res.status(401).send('Unauthorized');
}
// Parse and process webhook data
const data = JSON.parse(payload);
console.log('Received webhook:', data);
// Handle different event types based on data.event
switch (data.event) {
case 'message':
console.log('New message:', {
id: data.payload.id,
from: data.payload.from,
body: data.payload.body,
chat_id: data.payload.chat_id
});
break;
case 'message.reaction':
console.log('Reaction:', {
reaction: data.payload.reaction,
reacted_message_id: data.payload.reacted_message_id
});
break;
case 'message.revoked':
console.log('Message revoked:', data.payload.revoked_message_id);
break;
case 'message.edited':
console.log('Message edited:', {
original_id: data.payload.original_message_id,
new_body: data.payload.body
});
break;
case 'message.ack':
console.log(`Message ${data.payload.receipt_type}:`, {
chat_id: data.payload.chat_id,
message_ids: data.payload.ids,
description: data.payload.receipt_type_description
});
break;
case 'group.participants':
console.log(`Group ${data.payload.type} event:`, {
chat_id: data.payload.chat_id,
affected_users: data.payload.jids
});
break;
case 'newsletter.joined':
console.log('Joined newsletter:', {
newsletter_id: data.payload.newsletter_id,
name: data.payload.name
});
break;
case 'newsletter.left':
console.log('Left newsletter:', {
newsletter_id: data.payload.newsletter_id,
role: data.payload.role
});
break;
case 'newsletter.message':
console.log('Newsletter message:', {
newsletter_id: data.payload.newsletter_id,
messages: data.payload.messages
});
break;
case 'newsletter.mute':
console.log('Newsletter mute changed:', {
newsletter_id: data.payload.newsletter_id,
mute: data.payload.mute
});
break;
case 'call.offer':
console.log('Incoming call:', {
call_id: data.payload.call_id,
from: data.payload.from,
auto_rejected: data.payload.auto_rejected,
platform: data.payload.remote_platform
});
break;
}
res.status(200).send('OK');
});
function verifyWebhookSignature(payload, signature, secret) {
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(payload, 'utf8')
.digest('hex');
const receivedSignature = signature.replace('sha256=', '');
return crypto.timingSafeEqual(
Buffer.from(expectedSignature, 'hex'),
Buffer.from(receivedSignature, 'hex')
);
}
app.listen(3001, () => {
console.log('Webhook server listening on port 3001');
});
Error Handling
The webhook system includes retry logic with exponential backoff:
- Timeout: 10 seconds per request
- Max Attempts: 5 retries
- Backoff: Exponential (1s, 2s, 4s, 8s, 16s)
Ensure your webhook endpoint:
- Responds within 10 seconds
- Returns HTTP 2xx status for successful processing
- Handles duplicate events gracefully
- Validates signatures for security
Configuration
Environment Variables
# Single webhook URL
WHATSAPP_WEBHOOK=https://yourapp.com/webhook
# Multiple webhook URLs (comma-separated)
WHATSAPP_WEBHOOK=https://app1.com/webhook,https://app2.com/webhook
# Webhook secret for HMAC verification
WHATSAPP_WEBHOOK_SECRET=your-super-secret-key
Command Line Flags
# Single webhook
./whatsapp rest --webhook="https://yourapp.com/webhook"
# Multiple webhooks
./whatsapp rest --webhook="https://app1.com/webhook,https://app2.com/webhook"
# Custom secret
./whatsapp rest --webhook-secret="your-secret-key"
Best Practices
- Always verify signatures to ensure webhook authenticity
- Handle duplicates - the same event might be sent multiple times
- Process quickly - respond within 10 seconds to avoid timeouts
- Log errors for debugging webhook integration issues
- Use HTTPS for webhook URLs to ensure secure transmission
- Store media files locally if you need to process them later
- Implement proper error handling for different event types
Troubleshooting
Common Issues
Webhook not receiving events:
- Check webhook URL is accessible from the internet
- Verify webhook configuration
- Check firewall and network settings
Signature verification fails:
- Ensure webhook secret matches configuration
- Use raw request body for signature calculation
- Check HMAC implementation
Timeouts:
- Optimize webhook processing speed
- Implement asynchronous processing
- Return response quickly, process in background
Missing media files:
- Check media storage path configuration
- Ensure sufficient disk space
- Verify file permissions
Debug Logging
Enable debug mode to see webhook logs:
./whatsapp rest --debug=true --webhook="https://yourapp.com/webhook"
This will show detailed logs of webhook delivery attempts and errors.