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. สิทธิ์รับเหตุการณ์โทรควบคุมด้วย is_beta ของเวิร์กสเปซ สำหรับเวิร์กสเปซทดสอบ subscribed_events ที่เป็น *, รายการว่าง หรือไม่ระบุฟิลด์จะรวมเหตุการณ์โทร ส่วนรายการเฉพาะจะรับเฉพาะเหตุการณ์ที่ระบุ เวิร์กสเปซทั่วไปใช้ wildcard ได้แต่จะไม่ได้รับเหตุการณ์โทร การระบุสมัครเหตุการณ์โทรโดยตรงยังคงได้ 403 beta_feature_not_enabled ตรวจสิทธิ์ใหม่ทุกครั้งที่ส่ง ลองใหม่ และเล่นซ้ำ dead letter หากตรวจสอบล้มเหลวจะไม่อนุญาต ส่วนบันทึกการโทร message.* เป็นอิสระจากสิทธิ์นี้

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 เป็นสัญญาที่สงวนไว้ ยังไม่เปิดรับสาย เมื่อเปิดแล้ว เวิร์กสเปซทดสอบจะรับได้ผ่าน subscribed_events ที่ระบุชื่อเหตุการณ์, *, รายการว่าง หรือไม่ระบุฟิลด์
call.answered
call.answered แจ้งว่าการโทรเชื่อมต่อแล้ว เวิร์กสเปซทดสอบรับได้เมื่อ subscribed_events มี call.answered หรือ * หรือเป็นรายการว่างหรือไม่ระบุฟิลด์
call.ended
call.ended แจ้งการสิ้นสุดพร้อม data.call.id, reason, duration_seconds เวิร์กสเปซทดสอบรับได้เมื่อ subscribed_events มี call.ended หรือ * หรือเป็นรายการว่างหรือไม่ระบุฟิลด์
post.comment.created
การแจ้งเตือนความคิดเห็น TikTok หลังผ่านการระบุและตรวจสอบว่าโพสต์เป็นของบัญชีปัจจุบัน ก่อนเปิดใช้ให้ยืนยันว่าสภาพแวดล้อมรองรับการแจ้งเตือนและผู้รับพร้อมแล้ว การ polling ปิดไว้โดยค่าเริ่มต้น เมื่อตั้ง provider_data.enable_comment=true ต้องเริ่มหรือเชื่อมต่อใหม่ การเปลี่ยนค่าขณะออนไลน์ต้องเชื่อมต่อใหม่ start สำเร็จไม่ได้ยืนยันว่าใช้ค่าใหม่แล้ว การปิดไม่ถอนเหตุการณ์ที่อยู่ในคิว สมัครรับ post.comment.created หรือใช้รายการสมัครว่างหรือ * การสมัครอย่างเดียวไม่เปิด polling การส่งเป็นแบบพยายามให้ดีที่สุด อาจล่าช้า ซ้ำ ผิดลำดับ หรือตกหล่น และไม่รับประกันประวัติครบถ้วน ใช้ id ของเหตุการณ์เพื่อตัดรายการซ้ำ การไม่มี parent_comment_id ไม่ได้ยืนยันว่าเป็นความคิดเห็นระดับแรกที่ตอบกลับได้ ต้องตรวจสอบเป้าหมายก่อนตอบกลับ
contact.updated
ชื่อในสมุดที่อยู่ WhatsApp เปลี่ยนแล้ว (ไม่รวม whatsapp-protocol) อัปเดตเฉพาะฟิลด์ที่ส่งมาใน data.contact.address_book สตริงว่างหมายถึงล้างค่า ฟิลด์ที่ละเว้นคงค่าเดิม และ null ใช้ไม่ได้ ไม่เขียนทับชื่อเล่นของอีกฝ่ายหรือโปรไฟล์บัญชีเอง contact.id ระบุทรัพยากรผู้ติดต่อ ไม่จำเป็นต้องเป็นรหัสการสนทนา
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
ซิงค์โปรไฟล์ชื่อสาธารณะของบัญชีแล้ว; ปัจจุบัน trigger โดยอีเวนต์ชื่อของ 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
อนุญาตบัญชีสำเร็จแล้ว ก่อนส่งข้อความให้สอบถามบัญชีและยืนยันว่า runtime_status=running
account.auth.failed
An authentication attempt failed.

หมายเหตุ

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.