logo
繁體中文
English
繁體中文
简体中文
日本語
ภาษาไทย
聯絡我們
登錄
icon AppPushicon WebPushicon WhatsAppicon Emailicon SMSicon OTP
EngageLab 檔案 >AppPush >REST API >消息回调 API
EngageLab 檔案 >AppPush >REST API >消息回调 API

消息回调 API

最新更新：2023-11-27

將「消息狀態」的數據回調給企業的業務系統，可根據該信息進行統計分析等動作。

回調地址

企業需要設置接收「消息狀態變更」的回調地址，可在Push後台管理->應用設置->回調設置進行配置。

回調地址合法性校驗

在Push後台管理->應用設置->回調設置進行配置回調地址時，會發起一個POST請求並附帶一個8位隨機字符串的請求body參數echostr，您需要在Response Body裡將echostr的value 返回，格式如下：

請求body { "echostr": "12345678" } 
          請求body  
{  
    "echostr": "12345678"  
}
此代碼塊在浮窗中顯示
返回body 12345678 
          返回body  
12345678
此代碼塊在浮窗中顯示

安全機制

用於客戶鑑權，可選。

為了確保消息的來源身份是 Engagelab, 你可以選擇對 POST 數據的來源進行安全認證。（不驗證, 直接解析 POST 的數據也可以）

安全認證的方法如下：

在Enagelab控制台的回調地址上配置回調用戶名（可選，下邊描述為username）和回調密鑰（可選，下邊描述為secret）進行身份驗證。

從請求Header中獲取 X-CALLBACK-ID，舉例如下：

X-CALLBACK-ID: timestamp=1681991058;nonce=123123123123;username=test;signature=59682d71e2aa2747252e4e62c15f6f241ddecc8ff08999eda7e0c4451207a16b
          X-CALLBACK-ID: timestamp=1681991058;nonce=123123123123;username=test;signature=59682d71e2aa2747252e4e62c15f6f241ddecc8ff08999eda7e0c4451207a16b
此代碼塊在浮窗中顯示

其中 timestamp 為回調消息的時間戳（標準），nonce 為一個隨機數，signature 為簽名信息，簽名方法為：

signature=HMAC-SHA256(secret, timestamp+nonce+username)
          signature=HMAC-SHA256(secret, timestamp+nonce+username)
此代碼塊在浮窗中顯示

應答機制

開發者服務接收到 Engagelab 的回調後，需要在 3 秒內按下述要求進行應答。

  • **接收成功：**HTTP 應答狀態碼需返回 200 或 204，無需返回應答報文。
  • **接收失敗：**HTTP 應答狀態碼需返回 5XX 或 4XX，同時需返回應答報文，格式如下：
{ "code": 2002, "message": "失敗" } 
          {  
    "code": 2002,  
    "message": "失敗"  
}
此代碼塊在浮窗中顯示
字段 類型 必選/可選 說明
code int 可選 錯誤碼
message string 可選 錯誤詳細信息

重試機制

如果遇到 URL 訪問錯誤、超時、應答返回了接收失敗，Engagelab 最多會重試 5 次。每次重試的時間間隔最快為 10s, 1min, 5min, 30min, 1h. 即在消息丟失前，你有足夠的時間來修復 URL。
如果超過重試次數，Engagelab 將會把消息丟棄。
每次事件處理、數據解析，你需要在 3 秒內返回「接收成功的應答」 , 否則 Engagelab 將會重發該條消息。

回調內容

回調方式：POST
Content-Type：application/json

回調字段說明

消息主體

字段名 類型 必選/可選 說明
total int 必選 本次回調包含的消息數量
rows array 必選 消息狀態變更的詳細信息列表，包含以下字段：

rows 陣列字段

字段名 類型 必選/可選 說明
message_id string 必選 消息的唯一標識
from string 可選 發送方，默認appkey
to string 可選 接收方的標識（如 registrationID）
server string 必選 消息服務名稱，取值範圍：AppPush、WebPush
channel string 必選 消息通道，取值範圍：EngageLab、HuaWei、XiaoMi、MeiZu、OPPO、VIVO、HONOR、FCM、APNs
custom_args object 可選 消息創建時提交的自定義參數，此處原樣返回
itime int 必選 消息狀態真實產生的時間戳，與message_status字段相結合，可以得到各個消息狀態的時間戳
status object 必選 消息狀態信息，包含以下字段：

status 對象字段

字段名 類型 必選/可選 說明
message_status string 必選 消息狀態，取值範圍：target_valid、sent、delivered、click、target_invalid、sent_failed、delivered_failed、no_click
status_data object 可選 自定義狀態數據，包含以下字段：
channel_message_id string 可選 第三方通道的消息 ID
ntf_msg int 必選 消息類型，取值範圍：1: 通知消息、2: 自定義消息、5: ios實時活動消息、6: ios voip消息、7: 應用內消息
platform string 必選 推送平台，取值範圍：a: 安卓、i: ios、b: web
uid int 必選 推送的 UID
app_version string 必選 SDK 集成 app 版本，通過 SDK 上報數據獲得
channel string 必選 SDK 集成 app 渠道，通過 SDK 上報數據獲得
msg_time int 必選 消息下發時間，調用 API 請求發送消息成功的時間點
time_zone string 必選 組織所在時區
loss_valid_type int 可選 該字段無實際意義，無需處理
plan_user_total int 可選 該字段無實際意義，無需處理
callback_type int 可選 該字段無實際意義，無需處理
error_code int 可選 錯誤碼，僅在失敗時提供
error_detail object 可選 錯誤詳細信息，僅在失敗時提供，包含以下字段：
message string 可選 描述詳細錯誤原因，僅 FCM 通道提供
loss object 可選 折損信息，包含以下字段：
loss_source string 可選 折損來源，取值範圍：EngageLab、HuaWei、XiaoMi、MeiZu、OPPO、VIVO、HONOR、FCM、APNs
loss_step int 可選 折損階段，取值範圍：1: 計劃目標→有效目標、2: 有效目標→發送數量、3: 發送數量→送達數量、4: 送達數量→點擊數量

消息狀態取值說明

狀態取值 含義 含義
target_valid 有效目標 過去365天活躍過即被視為有效目標
sent 發送成功 發送到服務器成功
delivered 送達成功
  • EngageLab、XiaoMi、OPPO、VIVO以真實回調為成功送達；
  • FCM和APNs是以成功發送到廠商服務器為成功送達；
  • HuaWei、MeiZu、HONOR未配置廠商回調則以成功發送到廠商服務器為成功送達，配置了以廠商的真實回調為成功送達。
    		•
    click 用戶點擊 以sdk上報點擊為用戶點擊
    target_invalid 無效目標 根據折損表定義，在折損階段1的就為無效目標
    sent_failed 發送失敗 根據折損表定義，在折損階段2的就為無效目標
    delivered_failed 送達失敗 根據折損表定義，在折損階段3的就為送達失敗
    no_click 點擊失敗 根據折損表定義，在折損階段4的就為點擊失敗，僅應用內消息會有此事件

    回調示例

    請求報頭

    POST /developer_define_url HTTP/1.1 Content-Type: application/json 
              POST /developer_define_url HTTP/1.1  
Content-Type: application/json
    此代碼塊在浮窗中顯示

    請求體

    { "total": 1, "rows": [ { "message_id": "1666165485030094861", //engagelab側的消息id "from": "", // 發送方 "to": "", // 接收方，registrationID "server": "AppPush", "channel": "FCM", "custom_args": {}, // 這條消息創建時提交的參數，將於此回調時原樣返回 "itime": 1640707579, // 消息狀態變更時的時間戳，如消息已送達的時間 "status": { // 成功時響應這些字段 "message_status": "delivered", // 消息狀態 "status_data": { // 自定義 "channel_message_id": "wamid.123321abcdefed==" // 可選，第三方通道的msgid "ntf_msg": 1, //消息類型 "platform": "a", //推送平台 "uid": 100, //推送的uid "app_version": "", //sdk集成app版本，通過sdk上報數據獲得 "channel": "", //sdk集成app渠道，通過sdk上報數據獲得 "msg_time": 1640707579, //消息下發時間，調用 API 請求發送消息成功的時間點 "time_zone": "+8", //組織所在時區 "loss_valid_type": 0, //該字段無實際意義，無需處理 "plan_user_total": 0, //該字段無實際意義，無需處理 "callback_type": 0 //該字段無實際意義，無需處理 }, // 失敗時響應這些字段 "error_code": 0, //錯誤碼--對應生命周期錯誤碼 "error_detail": { "message": "" //錯誤原因 }, "loss": { "loss_source": "vivo", "loss_step": 1 } //折損階段和折損來源 } } ] } 
              {  
    "total": 1,  
    "rows": [  
        {  
            "message_id": "1666165485030094861", //engagelab側的消息id  
            "from": "", // 發送方  
            "to": "", // 接收方，registrationID  
            "server": "AppPush",  
            "channel": "FCM",  
            "custom_args": {}, // 這條消息創建時提交的參數，將於此回調時原樣返回  
            "itime": 1640707579, // 消息狀態變更時的時間戳，如消息已送達的時間  
            "status": {  
                // 成功時響應這些字段  
                "message_status": "delivered", // 消息狀態    
                "status_data": { // 自定義  
                    "channel_message_id": "wamid.123321abcdefed==" // 可選，第三方通道的msgid  
                    "ntf_msg": 1, //消息類型  
                    "platform": "a",    //推送平台  
                    "uid": 100, //推送的uid    
                    "app_version": "",  //sdk集成app版本，通過sdk上報數據獲得   
                    "channel": "",  //sdk集成app渠道，通過sdk上報數據獲得     
                    "msg_time": 1640707579, //消息下發時間，調用 API 請求發送消息成功的時間點  
                    "time_zone": "+8",  //組織所在時區  
                    "loss_valid_type": 0,   //該字段無實際意義，無需處理  
                    "plan_user_total": 0,   //該字段無實際意義，無需處理  
                    "callback_type": 0  //該字段無實際意義，無需處理  
                },  
                // 失敗時響應這些字段  
                "error_code": 0, //錯誤碼--對應生命周期錯誤碼  
                "error_detail": {  
                    "message": "" //錯誤原因  
                },  
                "loss": {  
                    "loss_source": "vivo",  
                    "loss_step": 1  
                } //折損階段和折損來源  
            }  
        }  
    ]  
}
    此代碼塊在浮窗中顯示

    折損階段

    1. 計劃目標-》有效目標
    2. 有效目標-》已發送
    3. 已發送-》已送達
    4. 已送達-》點擊

    注意：
    1.部分通道的點擊和送達可能存在重複現象，開發者可自行進行去重處理。
    2.發送成功5天之後的送達數量和展示數量不會再回調。

    在文档中心打开
    icon
    聯繫銷售