回呼設定

概述

設定回撥地址，用以接收 EngageLab OTP 服務的「消息狀態」和「消息通知」數據回撥給業務系統，並根據回撥的資訊進行數據統計、策略補發或觸發系統警報等。

消息狀態：用戶發送一條 OTP 消息後，該消息的發送、送達、已讀、驗證等狀態。
消息通知：主要是系統事件，如驗證率過低、餘額不足等事件。

配置回撥

在【配置管理】-【回撥設定】頁面，點擊「配置回撥」，進行 EngageLab OTP 服務的回撥配置。

EngageLab OTP回撥配置按鈕

EngageLab OTP回撥配置詳情

依照上圖所示，依次填寫「回撥描述」、「回撥地址」、「用戶名」、「Authorization」、「回撥事件」等資訊。

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

配置回撥地址

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

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

請求範例

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

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

          curl -X POST https://example.engagelabotp.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=59682d71e2aa2747252e4e62c15f6f241ddecc8ff08999eda7e0c 4451207a16b

          X-CALLBACK-ID: timestamp=1681991058;nonce=123123123123;username=test;signature=59682d71e2aa2747252e4e62c15f6f241ddecc8ff08999eda7e0c

4451207a16b

此代碼塊在浮窗中顯示

其中 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。

回撥請求體

回撥事件觸發時，EnageLab OTP 系統服務將會給回撥地址發送數據。

「消息狀態」請求範例

消息狀態：

plan：計劃發送
sent：已發送
sent_failed：發送失敗
delivered：已送達
delivered_failed：送達失敗
verified：已驗證
verified_failed：驗證失敗
verified_timeout：驗證超時

{ "total": 2, // 總數量 "rows": [{ // 數據 "message_id": "1742442805608914944", // 消息id "to": "+8615989574757", // 接收者 "server": "otp", // 服務，固定為otp "channel": "otp", // 通道，固定為otp "itime": 1704265712, // 該條數據的創建時間 "status": { // 消息狀態 "message_status": "plan", // 消息狀態，plan為計劃發送，sent為已發送，sent_failed為發送失敗 "status_data": { // 狀態數據 "msg_time": 1704265712, // 消息發送時間 "message_id": "1742442805608914944", // 消息id "current_send_channel": "", // 當前發送通道，取值為sms、email、voice、whatsapp，當炒 plan 時為空 "template_key": "auto_create_templateu25az170295320745", // 模板key "business_id": "100917676394736" // business id }, "error_code": 0 } }, { "message_id": "1742442805608914944", "to": "+8615989574757", "server": "otp", "channel": "otp", "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": "otp",                    // 服務，固定為otp
        "channel": "otp",                   // 通道，固定為otp
        "itime": 1704265712,                // 該條數據的創建時間
        "status": {                         // 消息狀態
            "message_status": "plan",       // 消息狀態，plan為計劃發送，sent為已發送，sent_failed為發送失敗
            "status_data": {                // 狀態數據
                "msg_time": 1704265712,     // 消息發送時間
                "message_id": "1742442805608914944",    // 消息id
                "current_send_channel": "",             // 當前發送通道，取值為sms、email、voice、whatsapp，當炒 plan 時為空
                "template_key": "auto_create_templateu25az170295320745",    // 模板key
                "business_id": "100917676394736"        // business id
            },
            "error_code": 0
        }
    }, {
        "message_id": "1742442805608914944",
        "to": "+8615989574757",
        "server": "otp",
        "channel": "otp",
        "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"        // 錯誤訊息
            }
        }
    }]
}

此代碼塊在浮窗中顯示

「消息通知」請求範例

事件：

insufficient_balance: 餘額低於警報閾值

{ "total": 1, "rows": [{ "server": "otp", "itime": 1712458844, "notification": { "event": "insufficient_balance", "notification_data": { "business_id": "1744569418236633088", "remain_balance": -0.005, // 當前餘額； "balance_threshold": 2 // 警報閾值； } } }] }

          {
    "total": 1,
    "rows": [{
        "server": "otp",
        "itime": 1712458844,
        "notification": {
            "event": "insufficient_balance",
            "notification_data": {
                "business_id": "1744569418236633088",
                "remain_balance": -0.005,                    // 當前餘額；
                "balance_threshold": 2                       // 警報閾值；
            }
        }
    }]
}

此代碼塊在浮窗中顯示