摘要

Wati 中的 Webhook 允許您透過將事件資料傳送到您的伺服器,即時接收關於訊息及其狀態的更新。本指南說明您可以追蹤哪些事件、如何設定 Webhook,以及基於對話階段 (session-based) 的回調如何運作,以便您能夠可靠地處理系統中的訊息活動。

說明

Wati Webhook 可以擷取哪些事件?

當您的 Wati 帳戶中發生特定事件時,Wati Webhook 會通知您的外部系統。當事件發生時,Wati 會將回調負載 (callback payload) 傳送到您設定的 Webhook URL。您的系統可以使用此資訊來追蹤訊息、監控訊息狀態,並隨時掌握 WhatsApp 帳戶的變更。

Wati 支援以下 Webhook 事件:

訊息與對話事件

  • Message Received (已接收訊息) – 當客戶傳送訊息時。

  • New Contact Message (新聯絡人訊息) – 當新聯絡人傳送訊息時。

  • Session Message Sent (已傳送對話訊息) – 當對話訊息傳送時。

  • Template Message Sent (已傳送範本訊息) – 當範本訊息傳送時。

  • Sent Message is DELIVERED (已傳送訊息已送達) – 當已傳送的訊息送達時。

  • Sent Message is Read (已傳送訊息已讀) – 當已傳送的訊息被讀取時。

  • Sent Message is REPLIED (已傳送訊息已回覆) – 當客戶回覆已傳送的訊息時。

  • Session Message Failed (對話訊息失敗) – 當對話訊息傳送失敗時。

  • Template Message FAILED (範本訊息失敗) – 當範本訊息傳送失敗時。

範本事件

  • Template Status Update (範本狀態更新) – 當範本狀態變更時。

  • Template Quality Update (範本品質更新) – 當範本品質評級變更時。

  • Template Category Update (範本類別更新) – 當範本類別變更時。

WhatsApp 帳戶與電話號碼事件

  • WhatsApp Account Review Updated (WhatsApp 帳戶審查更新) – 當 WhatsApp 帳戶的審查狀態變更時。

  • Phone Number Quality Update (電話號碼品質更新) – 當電話號碼的品質評級變更時。

  • WABA Account Deleted (WABA 帳戶已刪除) – 當 WhatsApp Business Account (WABA) 被刪除時。

  • WABA Account Content Updated (WABA 帳戶內容已更新) – 當 WABA 的內容更新時。

  • Phone Number Deleted (電話號碼已刪除) – 當電話號碼被刪除時。

  • Business Capability Updated (商家功能已更新) – 當商家功能更新時。

其他事件

  • Chatbot Triggered (聊天機器人已觸發) – 當聊天機器人被觸發時。

  • CTA URL Clicked (CTA 連結已點擊) – 當客戶點擊 CTA 連結時。

  • CTA Button Clicked (BSUID) (CTA 按鈕已點擊) – 當客戶點擊 CTA 按鈕時。

  • Call Status (通話狀態) – 當 WhatsApp 通話狀態變更時。

  • Contact Request Response (聯絡人請求回覆) – 當客戶回覆聯絡人請求時。

  • WhatsApp Payment Captured (WhatsApp 付款已扣款) – 當 WhatsApp 付款完成扣款時。

針對 BSUID 的額外 Webhook 事件

Wati 也支援針對 BSUID (Business-Scoped User ID) 的額外 Webhook 事件。

其中包括:

  • Message Received (BSUID)

  • New Contact Message (BSUID)

  • Session Message Sent (BSUID)

  • Session Message Sent v2 (BSUID)

  • Template Message Sent (BSUID)

  • Template Message Sent v2 (BSUID)

  • Chatbot Triggered (BSUID)

  • CTA Button Clicked (BSUID)

  • Call Status (BSUID)

關於個別事件及其回調負載的詳細資訊,請參閱我們的 webhook 文件。

如何在 Wati 中新增 Webhook

請按照以下步驟設定 Webhook:

  • 登入您的 Wati 儀表板。

  • 前往 Connectors (連接器) 並點擊 Webhooks。

  • 點擊 Add Webhook (新增 Webhook)。

  • 輸入您完整的 Webhook URL。

  • 將狀態設定為 Enabled (已啟用)。Webhook 狀態可以是 Enabled (已啟用)、Disabled (已停用) 和 Defective (異常)。

  • 選擇您要擷取的事件。

  • 點擊 Save (儲存)。

如何測試您的 Webhook

新增 Webhook 後,您可以測試連線:

  • 使用 Trigger sample callback (觸發範例回調) 選項。

  • Wati 將會傳送一個範例負載到您的 Webhook URL。

  • 驗證您的伺服器是否正確接收並處理了該負載。

了解基於對話階段的 Webhook

在 WhatsApp Business API 中,對話會以 24 小時的對話階段進行追蹤。當商業訊息送達時,對話階段即開始。

對話階段類型

  • Active session (活躍階段)

    • 商家與客戶至少已交換過一則訊息。

    • 範例:商家傳送範本訊息,而客戶回覆了訊息。

  • Inactive session (非活躍階段)

    • 只有一方傳送了訊息,而另一方尚未回覆。

    • 範例:商家傳送了範本訊息,但客戶未回覆。

注意:Webhook 回調可能會根據對話階段是「活躍」或「非活躍」而有所不同。

Webhook 回應與重試邏輯

為確保傳遞可靠,您的 Webhook 必須正確回應。

  • 您的伺服器必須回傳 200 OK 回應,以確認已接收到事件。

  • 若未收到 200 回應:

    • Wati 會重新嘗試傳送該事件。

    • 重試次數最多可達 144 次。

    • 重試嘗試將以 10 分鐘為間隔執行。

  • 若發生超過 100 次連續失敗:

    • 該 Webhook 將被標記為 Defective (異常)。

    • 您將會收到電子郵件通知。

如果所有重試嘗試均失敗,該事件將不再傳送。

最佳實踐

  • 確保您的 Webhook 端點始終可用且回應迅速。

  • 記錄傳入的負載以便於除錯。

  • 處理重複的事件,因為重試可能會導致傳送相同的負載多次。

  • 驗證傳入的請求,確保它們確實源自 Wati。

此設定有助於讓您的系統與 Wati 中的即時訊息活動保持同步。

常見問題 (FAQs)

Webhook 事件與設定

1. Wati Webhook 可以擷取哪些類型的事件?

Wati Webhook 可以擷取訊息與對話事件、範本事件、WhatsApp 帳戶與電話號碼事件以及其他事件。當支援的事件發生時,Wati 會將回調負載傳送到您設定的 Webhook URL。

2. Wati 提供哪些 Webhook 狀態?

Wati 支援三種 Webhook 狀態:

  • Enabled (已啟用) – Webhook 已啟用。

  • Disabled (已停用) – Webhook 已停用。

  • Defective (異常) – 在多次傳遞失敗後,Webhook 已被標記為異常。

3. Wati 是否支援針對 BSUID 的額外 Webhook 事件?

是的。Wati 支援針對 Business-Scoped User ID (BSUID) 的額外 Webhook 事件。有關個別 BSUID 事件及其回調負載的詳細資訊,請參閱 Webhook 文件。

基於對話階段的 Webhook

4. 活躍階段與非活躍階段有什麼區別?

活躍階段 (Active session) 是指商家與客戶至少已交換過一則訊息的情況。

非活躍階段 (Inactive session) 是指只有一方傳送了訊息,而另一方尚未回覆的情況。

5. Webhook 回調是否會因活躍或非活躍階段而異?

是的。Webhook 回調可能會根據 WhatsApp 對話階段是活躍還是非活躍而有所不同。WhatsApp 對話階段會在商業訊息送達時開始,並持續 24 小時。

Webhook 回應與疑難排解

6. 如果我的 Webhook 端點沒有回傳 200 OK 回應會怎樣?

您的伺服器必須回傳 200 OK 回應,以確認已接收到 Webhook 事件。如果 Wati 未收到此回應,它會以 10 分鐘為間隔,重新嘗試傳送該事件最多 144 次。

若發生超過 100 次連續失敗,Wati 會將該 Webhook 標記為 Defective (異常) 並傳送電子郵件通知。如果所有重試嘗試均失敗,Wati 將停止傳送該事件。

7. 我該如何提高 Webhook 的可靠性?

保持您的 Webhook 端點可用且回應迅速,記錄傳入的回調負載以便於除錯,處理重複的事件以避免多次處理相同的負載,並驗證傳入的請求以確保它們確實源自 Wati。

Did this answer your question?