API 參考

接收事件

標準事件類型與載荷

每次投遞攜帶的統一信封，以及全部公開標準事件類型目錄。依端點用 subscribed_events 訂閱，或用 ["*"] 訂閱全部公開事件；provider.raw_event 不會投遞給客戶。信封固定為 id / type / provider / account_id / occurred_at / data。

事件載荷

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

標準事件類型

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