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. Quyền nhận sự kiện gọi do is_beta của không gian làm việc quyết định. Với quyền thử nghiệm, subscribed_events là *, rỗng hoặc bị bỏ qua bao gồm sự kiện gọi; danh sách cụ thể chỉ nhận các sự kiện đã liệt kê. Không gian không có quyền vẫn dùng được wildcard nhưng không nhận sự kiện gọi; đăng ký rõ sự kiện gọi trả về 403 beta_feature_not_enabled. Quyền được kiểm tra lại mỗi lần gửi, thử lại và phát lại dead letter; lỗi tra cứu không cho phép gửi. Bản ghi cuộc gọi message.* thông thường độc lập.

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 là hợp đồng dự phòng; hiện chưa mở cuộc gọi đến. Khi được mở, không gian thử nghiệm có thể nhận qua subscribed_events chứa tên sự kiện, *, danh sách rỗng hoặc bỏ qua trường.
call.answered
call.answered thông báo cuộc gọi đã kết nối. Không gian thử nghiệm có thể dùng subscribed_events chứa call.answered hoặc *, danh sách rỗng hoặc bỏ qua trường.
call.ended
call.ended thông báo kết thúc với data.call.id, reason, duration_seconds. Không gian thử nghiệm có thể dùng subscribed_events chứa call.ended hoặc *, danh sách rỗng hoặc bỏ qua trường.
post.comment.created
Thông báo bình luận TikTok sau khi nhận diện và xác minh bài đăng thuộc tài khoản hiện tại. Trước khi bật, xác nhận môi trường đã hỗ trợ thông báo và bên nhận đã sẵn sàng. Polling mặc định tắt; đặt provider_data.enable_comment=true cần khởi động hoặc kết nối lại, thay đổi khi đang trực tuyến cần kết nối lại. start thành công không chứng minh cấu hình đã áp dụng; tắt không thu hồi sự kiện đã xếp hàng. Đăng ký post.comment.created, hoặc dùng danh sách đăng ký rỗng hay *; chỉ đăng ký không bật polling. Gửi theo khả năng tốt nhất: có thể trễ, trùng, sai thứ tự hoặc thiếu, không bảo đảm lịch sử đầy đủ. Loại trùng theo id sự kiện. Thiếu parent_comment_id không chứng minh đây là bình luận cấp đầu có thể trả lời; xác minh mục tiêu trước khi trả lời.
contact.updated
Tên trong danh bạ WhatsApp đã thay đổi (không gồm whatsapp-protocol). Chỉ cập nhật các trường được cung cấp trong data.contact.address_book: chuỗi rỗng xóa giá trị, trường bị bỏ qua giữ nguyên, null không hợp lệ. Không ghi đè biệt danh của đối phương hoặc hồ sơ của chính tài khoản. contact.id xác định tài nguyên liên hệ, không nhất thiết là mã hội thoại.
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
Hồ sơ tên công khai của tài khoản đã được đồng bộ; hiện được kích hoạt bởi sự kiện tên của WhatsApp.
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
Ủy quyền tài khoản đã thành công. Trước khi gửi, truy vấn tài khoản và xác nhận runtime_status=running.
account.auth.failed
An authentication attempt failed.

Ghi chú

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.