消息回调 API

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

回調地址

企業需要設置接收「消息狀態變更」的回調地址，可在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.發送成功5天之後的送達數量和展示數量不會再回調。

消息回调 API

回調地址

回調地址合法性校驗

安全機制

應答機制

重試機制

回調內容

回調字段說明

消息主體

rows 陣列字段

status 對象字段

消息狀態取值說明

回調示例

請求報頭

請求體

折損階段

`rows` 陣列字段

`status` 對象字段