Receiving Events

Standard event types & payload

The unified envelope every delivery carries and the full catalogue of public standard event types. Subscribe per endpoint with subscribed_events using the exact names below, or use ["*"] for all public standard events. Internal raw events are not delivered. The envelope is always id / type / provider / account_id / occurred_at / data; the shape of data depends on type. Call-event access is controlled by workspace is_beta. In beta workspaces, * and empty or omitted subscribed_events include call events; specific lists match only their listed events. Non-beta workspaces may use wildcard subscriptions but never receive call events; explicitly subscribing to call events returns 403 beta_feature_not_enabled. Eligibility is rechecked for every delivery, retry and dead-letter replay; lookup failures do not grant access. Ordinary message.* call records are independent.

Event payload

{
  "id": "evt_2f9c1a4b7e",
  "type": "message.received",
  "provider": "whatsapp",
  "account_id": "acc_8c21d0",
  "occurred_at": "2026-06-08T12:34:56Z",
  "data": {
    "account": { "provider_account_ref": "8600000000000" },
    "conversation": { "id": "8613912345678", "type": "user", "title": "Jordan Lee" },
    "sender": { "id": "8613912345678", "name": "Jordan Lee", "type": "user" },
    "message": {
      "id": "wamid.HBgM",
      "text": "Hi - is my order shipped yet?",
      "direction": "inbound",
      "sent_at": "2026-06-08T12:34:55Z"
    }
  }
}

Standard event types

call.incoming
call.incoming is a reserved private-beta contract, not an available incoming-call feature. When enabled, beta workspaces can receive it through a matching subscribed_events entry, * or an empty/omitted list.
call.answered
call.answered reports that a managed call connected. Beta workspaces can receive it through subscribed_events containing call.answered or *, or an empty/omitted list.
call.ended
call.ended reports the end of a managed call, with data.call.id, reason and duration_seconds. Beta workspaces can receive it through subscribed_events containing call.ended or *, or an empty/omitted list.
post.comment.created
TikTok comment notification after identification and own-post ownership checks. Confirm environment availability and receiver readiness before enabling. Polling defaults off; provider_data.enable_comment=true requires start or reconnect, and online changes require reconnect. Successful start does not prove application; disabling does not retract queued events. Subscribe to post.comment.created, or use empty subscriptions or *; subscription alone does not enable polling. Delivery is best-effort: delays, duplicates, reordering and omissions are possible, with no full history guarantee. Deduplicate by event id. Missing parent_comment_id does not prove a replyable top-level comment; verify the target before replying.
contact.updated
WhatsApp address-book names changed (not whatsapp-protocol). Update only supplied data.contact.address_book fields: empty strings clear values, omitted fields stay unchanged, and null is invalid. Does not overwrite nicknames or the account profile. contact.id identifies the contact resource, not necessarily a conversation.
message.received
A message was observed on the account; data.message.direction identifies inbound or outbound.
message.updated
A previously delivered message was edited.
message.deleted
A message was deleted or recalled.
message.read
A read receipt — the recipient read a message.
message.reaction
A reaction was added to or removed from a message.
message.delivered
A message was delivered to the recipient's device.
conversation.updated
A conversation-level setting changed — muted/unmuted, archived, pinned, or marked read.
conversation.deleted
A conversation was deleted.
conversation.cleared
A conversation's history was cleared.
conversation.history
Recent WhatsApp history for one conversation was synced after bootstrap or reconnect.
group.updated
Group metadata changed — name, members, or settings.
group.join_request
Someone asked to join a group with join approval enabled. Push is best-effort — poll List group join requests as the reliable source.
account.status.updated
The account runtime / connection status changed.
account.profile.updated
The account public name profile was synced; currently triggered by WhatsApp name events.
account.started
The account runtime connected and is ready to send and receive.
account.history.synced
A WhatsApp history-sync batch finished; data.summary gives the delivered conversation and message counts.
account.auth.required
The account needs (re)authentication — a code, QR scan, or 2FA.
account.auth.succeeded
Account authorization succeeded. Before sending, query the account and confirm runtime_status=running.
account.auth.failed
An authentication attempt failed.

Notes

For media messages, data.message.attachments[] carries a temporary signed OSS url plus type, mimetype, and size.
subscribed_events must contain exact public standard event names from above or ["*"]. Unknown names are rejected when you create or update the endpoint, and the wildcard does not expose internal raw events.
Not every provider emits every event, and some payload fields differ — see "Webhook standard event differences" for the per-provider matrix.
message.read and message.delivered carry the exact receipt scope: data.message.ids lists every message covered by the receipt, and read_at / delivered_at give the provider-reported time.
WhatsApp inbound messages can include data.message.reply_token — an opaque handle you pass back in reply_to.reply_token of POST /v1/messages to quote the current message. It appears only for real-time message.received when reply-token signing is configured. It is not reply_to_message_id, which identifies the parent of a received quoted reply.