回調設定

回調設定用於配置業務系統的回調地址，實時接收 EngageLab NewSMS 服務推送的「消息狀態」和「消息響應」事件。通過回調，您可以實現消息鏈路的自動化統計、策略補發、系統告警等業務場景，提升消息處理效率和系統智能化水平。

消息狀態：指單條 SMS 消息在發送、送達、已讀、驗證等各環節的狀態變化。
消息響應：指用戶上行（回覆）短信的內容與事件。

回調列表

回調列表頁面集中展示所有已配置的回調信息及其健康狀態，便於統一管理和維護。

搜索欄：支持按回調描述實時篩選，快速定位目標回調。
配置回調：點擊按鈕進入新建回調流程，便於靈活擴展回調需求。

alt text

字段說明

字段	說明
回調描述	回調配置的自定義說明，便於區分不同用途。
回調地址	回調接口的 URL 地址。
狀態	回調接口健康狀態。
消息狀態	已勾選的消息狀態事件數量，懸停顯示具體事件類型。
消息響應	已勾選的消息響應事件數量，懸停顯示具體事件類型。
操作	包含“刷新”、“編輯”、“刪除”操作。刷新可檢測健康狀態，刪除均需二次確認。

配置回調

點擊右上角【配置回調】後，進入頁面。

alt text 按照上圖所示，依次填寫「回調描述」、「回調地址」、「用戶名」、「Authorization」、「回調事件」、「消息響應」等信息。

勾選回調事件，在所選事件發生後，將信息推送到您設定的回調地址上。
點擊右側消息狀態和消息響應可以查看對應示例。

配置流程

配置回調地址時，EngageLab NewSMS 系統會發送一個 HTTP 的 POST 請求到該地址，該地址對應的開發者服務在收到 POST 請求之後，需要在 3 秒內響應 HTTP 狀態碼 200，否則系統會認為該地址無效。

開發者服務只需要響應 HTTP 狀態碼 200，無需返回應答報文。

請求示例

假設配置的回調地址為 https://example.engagelabSMS.callback.com ，我們會發送如下一個空報文給該地址，用 curl 命令表示如下：

curl -X POST https://example.engagelabSMS.callback.com -d ''

              
              curl -X POST https://example.engagelabSMS.callback.com -d ''

此代碼塊在浮窗中顯示

響應示例

該回調地址對應的開發者服務在收到 POST 請求之後，只需要響應 200 HTTP 狀態碼，示例如下：

HTTP/1.1 200 OK Content-Length: 0

              
              HTTP/1.1 200 OK
Content-Length: 0

此代碼塊在浮窗中顯示

回調地址安全機制配置

用戶名設置

這是一個可選操作，如果設置了用戶名，則必須填寫密鑰。

為了確保消息的來源身份是 EngageLab，您可以選擇對 POST 數據的來源進行安全認證。

配置用戶名和密鑰後，EngageLab 發過來的數據將帶有 HTTP Header： X-CALLBACK-ID。 X-CALLBACK-ID 的值為 timestamp={timestamp};nonce={nonce};username={username};signature={signature}

例如：

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 的 python 代碼示例：

import hashlib, hmac def verify(username, secret, timestamp, nonce, signature): return signature == hmac.new( key=secret, msg='{}{}{}'.format(timestamp, nonce, username), digestmod=hashlib.sha256).hexdigest()

              
              import hashlib, hmac
def verify(username, secret, timestamp, nonce, signature):
    return signature == hmac.new(
        key=secret,
        msg='{}{}{}'.format(timestamp, nonce, username),
        digestmod=hashlib.sha256).hexdigest()

此代碼塊在浮窗中顯示

Authorization 設置

這是一個可選操作，如果您的回調地址需要對 EngageLab 的請求進行鑒權，請在此提供鑒權信息，EngageLab 將在請求時帶上該 Authorization 。

回調請求體

回調事件觸發時，EngageLab SMS 系統服務將會給回調地址發送數據。

「消息狀態」請求示例

消息狀態：

plan：計劃發送
sent：已發送
sent_failed：發送失敗
delivered：已送達
delivered_failed：送達失敗

{ "total": 2, // 總數量 "rows": [{ // 數據 "message_id": "1742442805608914944", // 消息id "to": "+8615989574757", // 接收者 "server": "SMS", // 服務，固定為SMS "channel": "SMS", // 通道，固定為SMS "itime": 1704265712, // 該條數據的創建時間 "status": { // 消息狀態 "message_status": "plan", // 消息狀態，plan為計劃發送，sent為已發送，sent_failed為發送失敗 "status_data": { // 狀態數據 "msg_time": 1704265712, // 消息發送時間 "message_id": "1742442805608914944", // 消息id "current_send_channel": "", // 當前發送通道，取值為NewNewNewSMS、email、voice、whatsapp，當為plan時為空 "template_key": "auto_create_templateu25az170295320745", // 模板key "business_id": "100917676394736" // business id }, "error_code": 0 } }, { "message_id": "1742442805608914944", "to": "+8615989574757", "server": "SMS", "channel": "SMS", "itime": 1704265712, "status": { "message_status": "sent_failed", "status_data": { "msg_time": 1704265712, "message_id": "1742442805608914944", "current_send_channel": "whatsapp", "template_key": "auto_create_templateu25az170295320745", "business_id": "100917676394736" }, "error_code":5001, // 錯誤碼 "error_detail":{ // 錯誤詳情 "message":"sender config is invalid" // 錯誤信息 } } }] }

              
              {
    "total": 2,					// 總數量
    "rows": [{                  // 數據
        "message_id": "1742442805608914944",    // 消息id
        "to": "+8615989574757",            // 接收者
        "server": "SMS",                    // 服務，固定為SMS
        "channel": "SMS",                   // 通道，固定為SMS
        "itime": 1704265712,                // 該條數據的創建時間
        "status": {                         // 消息狀態
            "message_status": "plan",       // 消息狀態，plan為計劃發送，sent為已發送，sent_failed為發送失敗
            "status_data": {                // 狀態數據
                "msg_time": 1704265712,     // 消息發送時間
                "message_id": "1742442805608914944",    // 消息id
                "current_send_channel": "",             // 當前發送通道，取值為NewNewNewSMS、email、voice、whatsapp，當為plan時為空
                "template_key": "auto_create_templateu25az170295320745",    // 模板key
                "business_id": "100917676394736"        // business id
            },
            "error_code": 0
        }
    }, {
        "message_id": "1742442805608914944",
        "to": "+8615989574757",
        "server": "SMS",
        "channel": "SMS",
        "itime": 1704265712,
        "status": {
            "message_status": "sent_failed",
            "status_data": {
                "msg_time": 1704265712,
                "message_id": "1742442805608914944",
                "current_send_channel": "whatsapp",
                "template_key": "auto_create_templateu25az170295320745",
                "business_id": "100917676394736"
            },
            "error_code":5001,      // 錯誤碼
            "error_detail":{    // 錯誤詳情
                "message":"sender config is invalid"        // 錯誤信息
            }
        }
    }]
}

此代碼塊在浮窗中顯示

「消息響應」請求示例

事件：

uplink_message: 上行消息

{ "total": 1, "rows": [ { "server": "SMS", "itime": 1741083306, "message_id": "0", "business_id": "0", "response": { "event": "uplink_message", "response_data": { "message_sid": "SM1234567890", "account_sid": "AC1234567890", "from": "+1234567890", "to": "+0987654321", "body": "Hello, it's time to struggle!" } } } ] }

              
              {
    "total": 1,
    "rows": [
        {
            "server": "SMS",
            "itime": 1741083306,
            "message_id": "0",
            "business_id": "0",
            "response": {
                "event": "uplink_message",
                "response_data": {
                    "message_sid": "SM1234567890",
                    "account_sid": "AC1234567890",
                    "from": "+1234567890",
                    "to": "+0987654321",
                    "body": "Hello, it's time to struggle!"
                }
            }
        }
    ]
}

此代碼塊在浮窗中顯示