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；歷史同步訊息不含此欄位。