跳至主要內容

如何使用 Wati 網頁掛鉤追蹤模板消息的送達和狀態

今日已更新

摘要

當您使用 Wati 的 API 發送模板消息時，跟蹤其狀態（例如已發送、已送達、已閱讀、已回復或失敗）非常重要。這有助於您了解消息性能、排查問題，並更有效地管理客戶互動。本指南解釋了如何發送模板消息並使用 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 達ilig

  2. 轉到 連接器 → Webhook

  3. 點擊 添加 Webhook

  4. 輸入您的 Webhook URL

  5. 將狀態設置為 啟用

  6. 選擇所需的事件：

    • 模板消息已發送

    • 已送達

    • 已閱讀

    • 已回復

    • 失敗

最終注意事項

  • 發送消息時始終存儲 localMessageId

  • 使用它來將所有 Webhook 事件映射到同一消息

  • 將多個 Webhook 事件結合起來以構建完整的消息生命週期

通過正確設置 Webhook，您可以可靠地跟蹤通過 Wati 發送的每條模板消息，並根據實時更新採取行動。

常見問題解答 (FAQs)

發送模板消息

1. 如何使用 Wati 的 API 發送模板消息？

您可以通過調用 sendTemplateMessage V2 端點並使用所需的標頭和 JSON 主體（包括 template_name、broadcast_name 和 parameters 等字段）來使用 Wati 的 API 發送模板消息。

2. API 响應中的 localMessageId 的目的是什麼？

API 响應中返回的 localMessageId 是用于跟蹤消息在所有 Webhook 事件中的唯一標識符。應存儲此值，因為它將所有狀態更新與同一消息鏈接。

使用 Webhook 跟蹤消息狀態

3. 如何在 Wati 中跟蹤模板消息的生命週期？

您可以通過 Wati 發送消息後發送的 Webhook 事件來跟蹤模板消息的生命週期。每個 Webhook 事件都包含一個 localMessageId，允許您將事件與原始消息匹配並跟蹤其狀態更新。

4. 不同模板消息狀態觸發哪些 Webhook 事件？

Wati 觸發以下模板消息狀態的 Webhook 事件：

  • templateMessageSent_v2（當消息成功發送時，狀態：SENT）

  • sentMessageDELIVERED_v2（當消息已送達時，狀態：Delivered）

  • sentMessageREAD_v2（當消息已閱讀時，狀態：Read）

  • sentMessageREPLIED_v2（當接收者回復時，狀態：Replied）

  • messageReceived（當用戶向您的 Wati 號碼發送消息時，狀態：Received）

  • templateMessageFailed（當消息發送失敗時，狀態：Failed）

5. messageReceived Webhook 事件在什麼時候觸發，有何用途？

messageReceived Webhook 事件在用戶向您的 Wati 號碼發送消息時觸發。它可以用于跟蹤用戶回復和捕獲模板消息中的快速回復按鈕點擊。

Webhook 設置

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

要在 Wati 中設置 Webhook：

  • 登錄您的 Wati 達ilig。

  • 轉到 連接器 → Webhook。

  • 點擊 添加 Webhook。

  • 輸入您的 Webhook URL。

  • 將狀態設置為 啟用。

  • 選擇所需的事件，如模板消息已發送、已送達、已閱讀、已回復和失敗。

消息跟蹤最佳實踐

7. 為什麼在發送消息時應存儲 localMessageId？

應存儲 localMessageId，因為它用於將所有 Webhook 事件映射到同一消息並跟蹤其完整生命週期。

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

您可以通過將同一 localMessageId 鏈接的多個 Webhook 事件結合起來來構建完整的消息生命週期，從而獲得單個模板消息的所有狀態更新。

9. 為什麼在 Wati 中設置 Webhook 對于跟蹤模板消息很重要？

Webhook 設置很重要，因為它能夠實時跟蹤通過 Wati 發送的每條模板消息，並根據狀態更新採取行動，如已發送、已送達、已閱讀、已回復或失敗。

相關文章
如何整合 Wati 與 Bitrix24
連接 Wati 到 Eber：逐步指南
如何將 Wati 整合到 Swipe
常規常見問題解答：Wati Apis和Webhooks
如何設定及使用 Wati 中的 Webhook
是否回答了您的問題？