回呼設定

最新更新:2024-06-13

概述

設定回撥地址,用以接收 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-IDX-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                       // 警報閾值;
            }
        }
    }]
}

        
此代碼塊在浮窗中顯示
在文档中心打开
Contact Sales