跳至主要內容

如何使用 Wati webhook 追蹤範本訊息的傳送和狀態

今日已更新

總結

當您使用 Wati API 發送範本訊息時，您可能想追蹤它們的狀態——例如已發送、已送達、已讀、已回覆或失敗——使用 Webhook 而不是僅依賴 Wati 的內建廣告活動分析。

透過 API 發送廣告活動後，您隨時可以在 Wati 的廣告活動總覽中查看其成效。但是，您也可以使用 Wati Webhook，透過您自己的系統即時追蹤這些廣告活動的訊息狀態和傳送事件。

此方法可協助您監控訊息效能、排除傳送問題，並透過您的應用程式管理客戶互動。本指南說明如何發送範本訊息，並使用 Webhook 追蹤其生命週期。

說明

發送範本訊息

若要使用 Wati 的 API 發送範本訊息，請使用 sendTemplateMessage V2 端點。

範例 cURL 請求

curl --location 'https://live-mt-server.wati.io/{tenant_id}/api/v2/sendTemplateMessage?whatsappNumber=<whatsappNumber>' \
--header 'Authorization: Bearer <Token>' \
--header 'Content-Type: application/json' \
--data '{
  "template_name": "update_for_you",
  "broadcast_name": "JPTestBroadcast",
  "parameters": []
}'

範例 API 回應

{
  "result": true,
  "error": null,
  "templateName": "update_for_you",
  "receivers": [
    {
      "localMessageId": "d38f0c3a-e833-4725-a894-53a2b1dc1af6",
      "waId": "<whatsappNumber>",
      "isValidWhatsAppNumber": true,
      "errors": []
    }
  ],
  "parameters": []
}

重點欄位

  • localMessageId：用於追蹤 Webhook 事件中訊息的唯一識別碼。請儲存此值，因為它會將所有狀態更新連結到訊息。

使用 Webhook 追蹤訊息狀態

訊息傳送後，Wati 會針對每個狀態更新發送 Webhook 事件。使用 localMessageId 將這些事件與原始訊息進行比對。

1.範本訊息已發送

  • 觸發時機：訊息已從 Wati 成功發送

  • 事件：templateMessageSent_v2

  • 狀態：SENT

Webhook 示例酬載

{
  "eventType": "templateMessageSent_v2",
  "localMessageId": "d38f0c3a-e833-4725-a894-53a2b1dc1af6",
  "id": "640c8fd48b67615f886237b8",
  "whatsappMessageId": "gBEGkXmJQZVJAgkRHwjjZsITS6M",
  "templateId": "63766ae83b2e064905789c63",
  "templateName": "update_for_you",
  "created": "2023-03-11T14:27:32.9655388Z",
  "statusString": "SENT",
  "sourceType": "API"
}

2.訊息已送達

  • 觸發時機：訊息已傳送到收件者

  • 事件：sentMessageDELIVERED_v2

  • 狀態：Delivered

Webhook 示例酬載

{
  "eventType": "sentMessageDELIVERED_v2",
  "statusString": "Delivered",
  "localMessageId": "d38f0c3a-e833-4725-a894-53a2b1dc1af6",
  "id": "640c8fd48b67615f886237b8",
  "whatsappMessageId": "gBEGkXmJQZVJAgkRHwjjZsITS6M",
  "timestamp": "1678544854",
  "operatorEmail": "[email protected]"
}

3.訊息已讀

  • 觸發時機：收件者已讀取訊息

  • 事件：sentMessageREAD_v2

  • 狀態：Read

Webhook 示例酬載

{
  "eventType": "sentMessageREAD_v2",
  "statusString": "Read",
  "localMessageId": "d38f0c3a-e833-4725-a894-53a2b1dc1af6",
  "id": "640c8fd48b67615f886237b8",
  "whatsappMessageId": "gBEGkXmJQZVJAgkRHwjjZsITS6M",
  "timestamp": "1678545043",
  "operatorEmail": "[email protected]"
}

4.訊息已回覆

  • 觸發時機：收件者回覆了訊息

  • 事件：sentMessageREPLIED_v2

  • 狀態：Replied

Webhook 示例酬載

{
  "eventType": "sentMessageREPLIED_v2",
  "statusString": "Replied",
  "localMessageId": "d38f0c3a-e833-4725-a894-53a2b1dc1af6",
  "id": "640c8fd48b67615f886237b8",
  "whatsappMessageId": "gBEGkXmJQZVJAgkRHwjjZsITS6M",
  "timestamp": "1678545074",
  "operatorEmail": "[email protected]"
}

5.訊息已收到

  • 觸發時機：使用者向您的 Wati 號碼發送訊息

  • 事件：messageReceived

  • 狀態：Received

使用案例：

  • 追蹤使用者的回覆

  • 擷取範本訊息中的快速回覆按鈕點擊

Webhook 示例酬載

{
  "eventType": "messageReceived",
  "statusString": "Received",
  "localMessageId": "fd29c1f-9033-59b2-7d72-5ac964c4c8a7",
  "whatsappMessageId": "wamid.HBgMOAE4NjY4NDkzNjAxFAIAERgSOTEENzFCNjEwMkNDNENGQUJGAA==",
  "text": "Hello, I need help!",
  "timestamp": "1665645642",
  "operatorEmail": "[email protected]"
}

6.範本訊息失敗

  • 觸發時機：訊息傳送失敗

  • 事件：templateMessageFailed

  • 狀態：Failed

Webhook 示例酬載

{
  "eventType": "templateMessageFailed",
  "statusString": "Failed",
  "localMessageId": "fd29c1f-9033-59b2-7d72-5ac964c4c8a7",
  "failedCode": "131026",
  "failedDetail": "Message undeliverable",
  "id": "66b2531d4931581381944612",
  "whatsappMessageId": "wamid.HBgMOAE4NjY4NDkzNjAxFAIAERgSOTEENzFCNjEwMkNDNENGQUJGAA==",
  "timestamp": "1665645642",
  "operatorEmail": "[email protected]"
}

如何在 Wati 中設定 Webhook

請按照下列步驟開始接收 Webhook 事件：

  1. 登入您的 Wati 儀表板

  2. 前往連接器 → Webhook

  3. 按一下新增 Webhook

  4. 輸入您的 Webhook URL

  5. 將狀態設定為已啟用

  6. 選取所需的事件：

    • 範本訊息已發送

    • 已送達

    • 已讀

    • 已回覆

    • 失敗

最後說明

  • 傳送訊息時，請務必儲存 localMessageId

  • 使用它將所有 Webhook 事件對應到同一訊息

  • 結合多個 Webhook 事件來建立完整的訊息生命週期

透過正確設定 Webhook，您可以可靠地追蹤透過 Wati 發送的每則範本訊息，並根據即時更新採取動作。

常見問題 (FAQ)

發送範本訊息

1. 如何使用 Wati 的 API 發送範本訊息？

您可以呼叫 sendTemplateMessage V2 端點，連同所需的標頭和 JSON 主體（包括 template_name、broadcast_name 和 parameters 等欄位），以使用 Wati 的 API 發送範本訊息。

2. API 回應中的 localMessageId 用途為何？

localMessageId 是 API 回應中傳回的唯一識別碼，用於追蹤所有 Webhook 事件中的訊息。應儲存此值，因為它會將所有狀態更新連結到同一則訊息。

使用 Webhook 追蹤訊息狀態

3. 您如何在 Wati 中追蹤範本訊息的生命週期？

您可以使用訊息傳送後 Wati 發送的 Webhook 事件追蹤範本訊息的生命週期。每個 Webhook 事件都包含一個 localMessageId，讓您可以將事件與原始訊息進行比對，並追蹤其狀態更新。

4. 針對不同的範本訊息狀態會觸發哪些 Webhook 事件？

Wati 會針對範本訊息狀態觸發下列 Webhook 事件：

  • templateMessageSent_v2：訊息成功發送時（狀態：已發送）

  • sentMessageDELIVERED_v2：訊息已送達時（狀態：已送達）

  • sentMessageREAD_v2：訊息已讀取時（狀態：已讀）

  • sentMessageREPLIED_v2：收件者回覆時（狀態：已回覆）

  • messageReceived：使用者向您的 Wati 號碼發送訊息時（狀態：已收到）

  • templateMessageFailed：訊息傳送失敗時（狀態：失敗）

5. 何時觸發 messageReceived Webhook 事件？其用途為何？

當使用者向您的 Wati 號碼發送訊息時，會觸發 messageReceived Webhook 事件。它可用於追蹤使用者回覆和擷取範本訊息中的快速回覆按鈕點擊。

Webhook 設定

6. 如何在 Wati 中設定 Webhook 以接收訊息狀態事件？

若要在 Wati 中設定 Webhook：

  • 登入您的 Wati 儀表板。

  • 前往連接器 → Webhook。

  • 按一下新增 Webhook。

  • 輸入您的 Webhook URL。

  • 將狀態設定為已啟用。

  • 選取所需的事件，例如範本訊息已發送、已送達、已讀、已回覆和失敗。

訊息追蹤的最佳實務

7. 傳送訊息時，為什麼應該儲存 localMessageId？

您應該儲存 localMessageId，因為需要它才能將所有 Webhook 事件對應到同一則訊息，並追蹤其完整生命週期。

8. 如何使用 Webhook 事件建立完整的訊息生命週期？

您可以透過結合由相同 localMessageId 連結的多個 Webhook 事件來建立完整的訊息生命週期，這會提供單一範本訊息的所有狀態更新。

9. 為什麼 Webhook 設定對於在 Wati 中追蹤範本訊息非常重要？

Webhook 設定非常重要，因為它能夠即時追蹤透過 Wati 發送的每則範本訊息，並讓您可以根據狀態更新（例如已發送、已送達、已讀、已回覆或失敗）採取動作。

相關文章
如何使用 Wati 範本訊息傳送圖片或 PDF檔
如何使用 Webhook 來檢查付款狀態
CTWA 轉換追蹤最佳實踐及範本範例
常規常見問題解答：Wati Apis和Webhooks
如何設定及使用 Wati 中的 Webhook
是否回答了您的問題？