API 參考

接收事件

標準事件類型同載荷

每次投遞帶嘅統一信封，同埋全部公開標準事件類型目錄。按端點用 subscribed_events 訂閱，或者用 ["*"] 訂閱全部公開事件；provider.raw_event 唔會投遞畀客戶。信封固定係 id / type / provider / account_id / occurred_at / data。 通話事件權限由工作區 is_beta 控制。內測工作區的 subscribed_events 為 *、空陣列或省略時包含通話事件；具體事件清單只匹配列出的事件。非內測工作區可使用通配訂閱，但不會收到通話事件；明確訂閱通話事件仍傳回 403 beta_feature_not_enabled。每次投遞、重試及死信重放都重新核驗資格，查詢失敗不放行；一般 message.* 通話記錄獨立，不受影響。

事件載荷

{
  "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"
    }
  }
}

標準事件類型

  • 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 留言通知。啟用前要確認環境已開放通知，而且接收端已準備好。輪詢預設關閉；設定 provider_data.enable_comment=true 後要啟動或重新連線，在線修改要重新連線。start 成功唔代表設定已生效；關閉唔會撤回已排隊嘅事件。訂閱 post.comment.created，或者用空訂閱或 *；單靠訂閱唔會開啟輪詢。通知盡力而為，可能延遲、重複、亂序或遺漏，唔保證完整歷史。按事件 id 去重。缺少 parent_comment_id 唔代表係可回覆嘅一級留言；回覆前要核實目標。

  • contact.updated

    WhatsApp 通訊錄名稱更新（唔包括 whatsapp-protocol）。只更新 data.contact.address_book 有提供嘅欄位：空字串表示清空，省略就保留原值，null 無效。唔會覆蓋對方暱稱或帳號本人資料。contact.id 識別聯絡人資源，唔一定係對話識別碼。

  • message.received

    帳號觀察到一條訊息；用 data.message.direction 區分 inbound 同 outbound。

  • message.updated

    一條已投遞嘅訊息被編輯。

  • message.deleted

    一條訊息被刪除或者收回。

  • message.read

    已讀回條——對方已讀某條訊息。

  • message.reaction

    某條訊息被加上或者移除咗表情回應（reaction）。

  • message.delivered

    一條訊息已送達對方裝置。

  • conversation.updated

    會話層級設定有變——靜音 / 取消靜音、封存、置頂或者標記已讀。

  • conversation.deleted

    一個會話俾刪除咗。

  • conversation.cleared

    一個會話嘅聊天記錄俾清空咗。

  • conversation.history

    WhatsApp 喺啟動或者重連之後同步咗某個會話嘅近期歷史訊息。

  • group.updated

    群組中繼資料有變——名稱、成員或者設定。

  • group.join_request

    有人申請加入已開入群審批嘅群組。推送係盡力而為——請以輪詢「列出入群申請」為準。

  • account.status.updated

    帳號嘅執行環境 / 連線狀態有變化。

  • account.profile.updated

    帳號公開名稱資料已同步；目前由 WhatsApp 名稱事件觸發。

  • account.started

    帳號執行環境已經連線，可以收發訊息。

  • account.history.synced

    一次 WhatsApp 歷史同步批次已經結束；data.summary 會俾出已投遞嘅會話同訊息數量。

  • account.auth.required

    帳號需要（重新）認證——驗證碼、掃碼或者兩步驗證。

  • account.auth.succeeded

    帳戶授權成功。傳送前查詢帳戶，確認 runtime_status=running。

  • account.auth.failed

    一次認證嘗試失敗。

備註

  • 對於媒體訊息，data.message.attachments[] 會帶暫時簽章嘅 OSS url，同埋 type、mimetype、size。
  • subscribed_events 必須填上面嘅精確事件名或者 ["*"]；星號只包公開標準事件，唔包括 provider.raw_event。
  • 唔係每個 provider 都會發出全部事件，部分載荷欄位亦有差異——按 provider 嘅差異見「Webhook 標準事件差異」矩陣。
  • message.read 同 message.delivered 帶有精確嘅回執範圍：data.message.ids 列出今次回執涵蓋嘅全部訊息，read_at / delivered_at 俾出渠道回報嘅時間。
  • WhatsApp 即時 message.received 喺渠道提供可回覆嘅訊息標識時，可能帶 data.message.reply_token；將佢原樣放入 POST /v1/messages 嘅 reply_to.reply_token。佢用嚟回覆目前訊息，唔係父訊息 id；歷史同步訊息冇呢個欄位。