Skip to content

GOWA - WhatsApp REST API with support for UI, Multi Account, Webhooks, and MCP, and Chatwoot. Built with Golang for efficient memory use.

81.6 KB
Raw Blame

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_EVENTS is 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_lid or from_lid against the list (so an @lid pattern matches LID-migrated events, whose @lid JID lives in the *_lid fields).
  • 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-device webhook_url means: instead of replacing the global WHATSAPP_WEBHOOK targets it is added to them. The device URL is signed with the device's webhook_secret and filtered by its webhook_events; the global URLs keep the global secret and WHATSAPP_WEBHOOK_EVENTS. The ignore-JID rules above apply to both. A global URL that equals the device URL is delivered once. Default false keeps the replace behaviour.
  • @g.us is the recommended way to mute groups (it matches the group chat_id). The @s.whatsapp.net wildcard matches the sender too, so it also suppresses group messages (whose from is the participant's @s.whatsapp.net JID) — 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.offer puts the group in group_jid (not chat_id), message.deleted only includes chat_id when the original message is found locally, and group.participants/group.info/group.joined have no from. The @g.us wildcard 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_SECRET or --webhook-secret to a private value. The old published default secret is 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 → Use payload.from from the webhook
  • call_id → Use payload.call_id from 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-Id header 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:

  1. Enable call.offer in WHATSAPP_WEBHOOK_EVENTS
  2. Set up a webhook receiver endpoint in your application
  3. When a call.offer event arrives, apply your business logic
  4. If the call should be rejected, call POST /call/reject with the values from the webhook payload
  5. 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 and ContactsArrayMessage (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" }
      ]
    }
  }
}
  • body is 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 gets Template message.
  • buttons[].type is url, call, quick_reply or copy (code holds the value to copy). Other native-flow buttons keep their name as the type.
  • A single_select button lists its options in rows (id, title, description).
  • header_type is set when the header is media: image, video, document, location or product. The header media itself is not included.
  • Templates wrapping an interactive message use the same shape, plus subtitle, and cards for carousels. Their body is rendered like an interactive message ([quick_reply] Stop updates, Card 1: …, and Interactive message when empty).
  • Interactive, list and order messages keep their interactive (the same text as body), list and order (raw WhatsApp message fields) keys, and get a plain-text body too: List: <title> or Order: <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"
}
  • kind is list, buttons, template or interactive (native-flow replies, whose selected_id comes from the reply's id param).
  • body is the selected text, falling back to description. Recent clients often send replies with only the id; body is then Selected option <selected_id>, or Selection message when 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 editing
  • id: 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

  1. Configure webhook URL(s):

    ./whatsapp rest --webhook="https://yourapp.com/webhook"
    
  2. Set webhook secret:

    ./whatsapp rest --webhook-secret="your-secret-key"
    
  3. 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

  1. Always verify signatures to ensure webhook authenticity
  2. Handle duplicates - the same event might be sent multiple times
  3. Process quickly - respond within 10 seconds to avoid timeouts
  4. Log errors for debugging webhook integration issues
  5. Use HTTPS for webhook URLs to ensure secure transmission
  6. Store media files locally if you need to process them later
  7. Implement proper error handling for different event types

Troubleshooting

Common Issues

  1. Webhook not receiving events:

    • Check webhook URL is accessible from the internet
    • Verify webhook configuration
    • Check firewall and network settings
  2. Signature verification fails:

    • Ensure webhook secret matches configuration
    • Use raw request body for signature calculation
    • Check HMAC implementation
  3. Timeouts:

    • Optimize webhook processing speed
    • Implement asynchronous processing
    • Return response quickly, process in background
  4. 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.