訊息回調 API

最新更新:2023-03-07

概述

將「訊息狀態」和「訊息回響」的數據回調給企業的業務係統,可根據該信息進行統計、回複用戶等動作。

回調地址

企業需要設定接收「訊息狀態」以及「訊息回響」的回調地址,詳情參見 回呼設定

回調格式

請求方式是 POST,請求體為 JSON,數據類型:"Content-Type: application/json"
一次請求將批量返回多條數據。

安全機製

待上線。目前回調暫未帶上鑒權信息,故開發者接收回調的接口請不要設定權限驗證。

應答機製

開發者服務接收到 Engagelab 的回調後,需要在 3 秒內按下述要求進行應答。
接收成功:HTTP 應答狀態碼需返回 200 ,無需返回應答報文。

重試機製

待上線。

請求參數

EngageLab 嚮業務係統的回調地址發起的請求參數如下:

字段 類型 選項 描述
total int 必填 回調的數據量
rows JSON Array 必填 回調的詳細信息

rows 中的參數如下:

字段 類型 選項 描述
message_id string 可選 訊息狀態以及訊息回響的時候返回。
from string 可選 傳送方,訊息狀態以及上行訊息的時候返回
to string 可選 接收方,訊息狀態以及上行訊息的時候返回
server string 必選 回調信息所屬的産品服務,固定取值 whatsapp
channel string 可選 該狀態或者回響屬於哪一個通道,固定取值 whatsapp
itime int 必選 回調數據真實産生的時間戳,與 message_status 字段相結合,可以得到:請求時間戳、傳送時間戳、送達時間戳、已讀時間戳
custom_args JSON Object 可選 在訊息傳送時自訂的可選字段,在訊息狀態回調中原樣返回。
status JSON Object 可選 訊息狀態字段
response JSON Object 可選 訊息回響字段

訊息狀態-status

回調參數

字段 類型 選項 描述
message_status string 必選 訊息的狀態
status_data JSON Object 可選 該狀態下的詳細數據
error_code int 可選 錯誤碼,失敗時返回
error_detail JSON Object 可選 錯誤詳情,失敗時返回
loss JSON Object 可選 摺損階段和摺損來源

message_status

取值 描述 定義
plan 計畫傳送 該號碼在傳遞的「收件人號碼」內,即為該號碼記錄 1 個計劃傳送目標的狀態
target_valid 目標有效 通過合法性校驗
1、該號碼被 EngageLab 判定為合法
2、該號碼被 Meta WhatsApp 服務判定為合法
sent 傳送成功 該號碼由 EngageLab 提交給 Meta WhatsApp 服務後返回了成功
delivered 送達成功 由 Meta WhatsApp 服務確認訊息已送達用戶
read 已讀 由 Meta WhatsApp 服務確認用戶已讀訊息
target_invalid 目標無效 1、該號碼被 EngageLab 判定為非法
2、該號碼被 Meta WhatsApp 服務判定為非法
sent_failed 傳送失敗 該號碼提交給 Meta WhatsApp 服務後返回了失敗
delivered_failed 送達失敗 該號碼提交給 Meta WhatsApp 服務成功,但 Meta 回調告知失敗。
delivered_timeout 超時未送達 該號碼提交給 Meta WhatsApp 服務成功,但在 5 分鐘內 Meta 未回調告知是否成功/失敗,計為超時。

status_data

字段 類型 選項 描述
msg_time int 必填 訊息下發時間,調用 API 請求傳送訊息成功的時間點
channel_message_id String 必填 WhatsApp 官方返回的訊息 ID
whatsapp_business_account_id String 必填 傳送號所屬的 WhatsApp 商業賬戶的編號
timezone String 必填 組織所在時區
plan_user_total int 可選 計劃目標總數,隻有當 message_status=plan 時這個才會有值
country_code String 必填 接收方手機號碼歸屬的國家/地區代碼
from_phone_id String 必填 傳送號碼(from)的 ID 標識
conversation JSON Object 可選 會話信息
pricing JSON Object 可選 價格信息
conversation
字段 類型 選項 描述
id String 可選 該條訊息所屬的 Meta 對話 ID
origin JSON Object 可選 表示是由誰發起的對話。由 type 指定。
示例:"origin":{"type":"business_initiated"},取值如下:
  • business_initiated:示對話由企業嚮客戶傳送第一條訊息開始。這適用於距離最後一條客戶訊息超過 24 小時的任何時間。
  • customer_initiated:示對話是由企業回複客戶訊息開始的。這僅適用於業務回複距離最後一條客戶訊息在 24 小時內的情況。
  • referral_conversion:示對話源自一個 自由入口點。這些對話總是由客戶發起的。
  • pricing
    字段 類型 選項 描述
    pricing_model String 可選 固定取值為 CBP
    category String 可選 對話定價類別,取值如下:
  • business_initiated:商家對話。
  • customer_initiated: 用戶對話。
  • referral_conversion: 免費接入點對話。
  • error_detail

    字段 類型 選項 描述
    message String 必填 錯誤原因

    loss

    字段 類型 選項 描述
    loss_step int 必填 摺損階段
  • 1:計劃目標 ~ 有效目標,即無效目標
  • 2:有效目標 ~ 傳送,即傳送失敗
  • 3:傳送 ~ 送達。即送達失敗
  • loss_source String 必填 摺損來源,取值:
  • engagelab:EngageLab WhatsApp 服務進行校驗産生的摺損
  • meta:Meta 官方返回的錯誤
  • 回調示例

    { "total": 1, "rows": [ { "message_id": "1666165485030094861", // EngageLab 的訊息 id "from": "", // 傳送方 "to": "", // 接收方 "server": "whatsapp", "channel": "whatsapp", "itime": 1640707579, // 訊息狀態産生的時間戳,如訊息已送達的時間 "custom_args": {}, // 這條訊息創建時提交的參數,將於此回調時原樣返回 "status": { // 成功時回響這些字段 "message_status": "delivered" // 訊息狀態 "status_data": { // 自訂 "msg_time": 1663432355, // 訊息下發時間,曆史記錄上的訊息傳送時間,即用戶調用 API 傳送訊息-調用 API 成功的那個時間 "channel_message_id": "wamid.123321abcdefed==", // 可選,Meta 返回的 msgid "whatsapp_business_account_id": "", //傳送號 from 對應的 Whatsapp 商業賬戶編碼 "timezone": "", //組織時區 "plan_user_total": 2007, //計劃目標總數,隻有當 message_status=plan 時這個才會有值 "country_code": "CN", //接收方手機號碼歸屬的國家/地區代碼 "from_phone_id": "111111" // 傳送號碼(from)的 ID 標識 "conversation": { // 可選,會話信息 "id": "ebe2398cdaa37a0899ca5268b987b0c8", "origin": { "type": "business_initiated" } }, "pricing": { // 可選,價格信息 "pricing_model": "CBP", "category": "business_initiated" } }, // 失敗狀態下(無效目標、傳送失敗、送達失敗、未讀)返回這些字段 "error_code": 0, //錯誤碼 "error_detail": { "message": "" //錯誤原因 }, "loss": { "loss_step": 1, "loss_source": "aa" } } } ] }
              {
        "total": 1,
        "rows": [
            {
                "message_id": "1666165485030094861", // EngageLab 的訊息 id
                "from": "", // 傳送方
                "to": "", // 接收方
                "server": "whatsapp",
                "channel": "whatsapp",
                "itime": 1640707579, // 訊息狀態産生的時間戳,如訊息已送達的時間
                "custom_args": {}, // 這條訊息創建時提交的參數,將於此回調時原樣返回
                "status": {
                    // 成功時回響這些字段
                    "message_status": "delivered" // 訊息狀態    
          "status_data": { // 自訂
                        "msg_time": 1663432355, // 訊息下發時間,曆史記錄上的訊息傳送時間,即用戶調用 API 傳送訊息-調用 API 成功的那個時間
                        "channel_message_id": "wamid.123321abcdefed==", // 可選,Meta 返回的 msgid
                        "whatsapp_business_account_id": "", //傳送號 from 對應的 Whatsapp 商業賬戶編碼
                        "timezone": "", //組織時區
                        "plan_user_total": 2007, //計劃目標總數,隻有當 message_status=plan 時這個才會有值
                        "country_code": "CN", //接收方手機號碼歸屬的國家/地區代碼
                        "from_phone_id": "111111" // 傳送號碼(from)的 ID 標識
           "conversation": { // 可選,會話信息
                            "id": "ebe2398cdaa37a0899ca5268b987b0c8",
                            "origin": {
                                "type": "business_initiated"
                            }
                        },
                        "pricing": { // 可選,價格信息
                            "pricing_model": "CBP",
                            "category": "business_initiated"
                        }
                    },
                    // 失敗狀態下(無效目標、傳送失敗、送達失敗、未讀)返回這些字段
                    "error_code": 0, //錯誤碼
                    "error_detail": {
                        "message": "" //錯誤原因
                    },
                    "loss": {
                        "loss_step": 1,
                        "loss_source": "aa"
                    }
                }
            }
        ]
    }
    
            
    此代碼塊在浮窗中顯示

    訊息回響

    回調參數

    字段 類型 選項 描述
    event string 可選 回響事件
    response_data JSON Object 可選 上行回複/交互的訊息內容

    event

    取值 描述 詳細說明
    received 收到用戶的訊息 用戶直接傳送了一條訊息
    reply 用戶回複了你的訊息 企業先傳送了訊息給用戶,用戶選擇對該條信息進行回複
    order 用戶下訂單 -
    deleted 用戶刪除了他的訊息 用戶將自己發出的訊息刪除了(待上線)

    response_data

    字段 類型 選項 描述
    channel_message_id String 必填 WhatsApp 官方返回的訊息 ID
    whatsapp_business_account_id String 必填 傳送號所屬的 WhatsApp 商業賬戶的編號
    contact JSON Object 可選 傳送方信息
    message JSON Object 必填 訊息內容
    contact
    字段 類型 選項 描述
    profile JSON Object 可選 傳送方(客戶)的資料,當前僅有 name 字段表示客戶的姓名。
    示例:"profile": {"name": "bob"}
    wa_id String 可選 傳送方的號碼
    message
    字段 類型 選項 描述
    type String 必填 取值:text、image、audio、video、document、sticker、button、interactive、unknown、order
    text JSON Object 可選 詳見 text object 說明
    image JSON Object 可選 詳見 image object 說明
    audio JSON Object 可選 詳見 audio object 說明
    video JSON Object 可選 詳見 video object 說明
    document JSON Object 可選 詳見 document object 說明
    sticker JSON Object 可選 詳見 sticker object 說明

    回調示例

    { "total": 1, "rows": [ { "message_id": "1666165485030094861", // Engagelab側的訊息 id "from": "", // 傳送方,即客戶的手機號碼 "to": "", // 接收方,即開發者的傳送號 "server": "whatsapp", "channel": "whatsapp", "itime": 1640707579, // 時間戳 "response": { "event": "", // 回響事件 "response_data": { // 具體訊息內容 "channel_message_id": "wamid.123321abcdefed==", // 可選,Meta 返回的 msgid "whatsapp_business_account_id": "123321", //開發者的傳送號 to 對應的 Whatsapp 商業賬戶編碼 "contact": { // 可選,傳送方信息 "profile": { "name": "bob" // 傳送方的昵稱 }, "wa_id": "8613800138000" // 傳送方的號碼 }, "message": { // 具體訊息內容 "type": "text", // 訊息的類型,可以根據這個值來識別具體訊息字段,如 text 則內容為 text 字段 "text": { // 訊息內容 "body": "here is the message content text" } } } } } ] }
              {
        "total": 1,
        "rows": [
            {
                "message_id": "1666165485030094861", // Engagelab側的訊息 id
                "from": "", // 傳送方,即客戶的手機號碼
                "to": "", // 接收方,即開發者的傳送號
                "server": "whatsapp",
                "channel": "whatsapp",
                "itime": 1640707579, // 時間戳
                "response": {
                    "event": "", // 回響事件
                    "response_data": { // 具體訊息內容
                        "channel_message_id": "wamid.123321abcdefed==", // 可選,Meta 返回的 msgid
                        "whatsapp_business_account_id": "123321", //開發者的傳送號 to 對應的 Whatsapp 商業賬戶編碼
                        "contact": { // 可選,傳送方信息
                            "profile": {
                                "name": "bob" // 傳送方的昵稱
                            },
                            "wa_id": "8613800138000" // 傳送方的號碼
                        },
                        "message": { // 具體訊息內容
                            "type": "text", // 訊息的類型,可以根據這個值來識別具體訊息字段,如 text 則內容為 text 字段
                            "text": { // 訊息內容
                                "body": "here is the message content text"
                            }
                        }
                    }
                }
            }
        ]
    }
    
            
    此代碼塊在浮窗中顯示
    在文档中心打开