AppPush
WebPush
WhatsApp
Email
SMS
OTP
回呼設定
最新更新：2024-06-13
概述
設定回撥地址，用以接收 EngageLab OTP 服務的「消息狀態」和「消息通知」數據回撥給業務系統，並根據回撥的資訊進行數據統計、策略補發或觸發系統警報等。
- 消息狀態：用戶發送一條 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 // 警報閾值；
}
}
}]
}
此代碼塊在浮窗中顯示
