Logo Site EngageLab Mark Colored Transparent文件
SMS
文檔首頁
文件API 參考
搜尋
登錄
API 參考/回調事件參考
API 參考回調事件參考...

回調事件參考

最新更新：5 天前

回調位址設定與校驗

設定回調位址後，EngageLab SMS 會自動向該位址發送一次 HTTP POST 請求，用於校驗介面的可用性。您的服務需在 3 秒內回傳 HTTP 200 狀態碼，否則系統會認為該位址不可用。

注意：
為確保能夠正常接收回調資料，請將 119.8.170.74 和 114.119.180.30 加入您的伺服器防火牆白名單。

請求範例

假設您的回調位址為 https://example.engagelabSMS.callback.com，系統會發送如下請求：

curl -X POST https://example.engagelabSMS.callback.com -d '{}'
              
              curl -X POST https://example.engagelabSMS.callback.com -d '{}'
此代碼塊在浮窗中顯示

回應要求

您的服務只需回傳 HTTP 200 狀態碼，無需回傳任何內容。例如：

HTTP/1.1 200 OK Content-Length: 0
              
              HTTP/1.1 200 OK
Content-Length: 0
此代碼塊在浮窗中顯示

注意：
回調位址校驗僅判斷 HTTP 狀態碼，不要求回傳具體封包內容。請確保您的服務介面能在 3 秒內正確回應 200。

回調安全機制

為保障回調資料的安全性和來源可信，EngageLab SMS 支援多種安全校驗方式。

使用者名稱與金鑰校驗（可選）

  • 可選設定。如果設定了使用者名稱，必須同時設定金鑰。
  • 設定後，EngageLab 在每次回調請求的 HTTP Header 中新增 X-CALLBACK-ID 欄位，格式如下：
X-CALLBACK-ID: timestamp={timestamp};nonce={nonce};username={username};signature={signature}
              
              X-CALLBACK-ID: timestamp={timestamp};nonce={nonce};username={username};signature={signature}
此代碼塊在浮窗中顯示
  • 其中：
    • timestamp：回調發送的時間戳記
    • nonce：隨機數
    • username：您設定的使用者名稱
    • signature：簽名資訊，計算方法如下

簽名計算方式（Python 範例）

import hashlib, hmac def verify(username, secret, timestamp, nonce, signature): return signature == hmac.new( key=secret.encode(), msg=f'{timestamp}{nonce}{username}'.encode(), digestmod=hashlib.sha256 ).hexdigest()
              
              import hashlib, hmac
def verify(username, secret, timestamp, nonce, signature):
    return signature == hmac.new(
        key=secret.encode(),
        msg=f'{timestamp}{nonce}{username}'.encode(),
        digestmod=hashlib.sha256
    ).hexdigest()
此代碼塊在浮窗中顯示
  • 伺服器端可用上述方式校驗回調請求的合法性。

Authorization 鑑權（可選）

  • 如果您的回調介面需要鑑權（如 Basic Auth、Bearer Token 等），可在設定時填寫 Authorization 資訊。
  • EngageLab 在請求時會自動攜帶該 Authorization 欄位，便於您的服務校驗請求身分。

回調事件說明

訊息狀態

訊息狀態用於追蹤每一條訊息在生命週期中的狀態變化。用於即時了解訊息的發送、送達、驗證等各個環節的進展，便於統計分析、異常處理和使用者體驗最佳化。

事件標識 說明
plan 訊息計畫發送，進入待發送佇列
target_valid 目標號碼有效
target_invalid 目標號碼無效
sent 訊息成功發送
sent_failed 訊息發送失敗
delivered 訊息送達使用者設備
delivered_failed 訊息已發送，但未能送達使用者設備

回調資料結構

外層結構

{ "total": 1, "rows": [ { // ReportLifecycle 物件 } ] }
              
              {
  "total": 1,
  "rows": [
    {
      // ReportLifecycle 物件
    }
  ]
}
此代碼塊在浮窗中顯示
欄位名 類型 說明
total int 本次回調包含的資料筆數
rows array 生命週期狀態資料陣列

ReportLifecycle 物件

欄位名 類型 說明
message_id string 訊息唯一 ID
to string 接收方號碼
server string 服務類型（如 SMS）
channel string 管道類型
itime int64 回調時間戳記（秒）
custom_args object 自訂參數（如有傳入則回傳）
status object 狀態詳情物件

status 物件

欄位名 類型 說明
message_status string 訊息目前狀態（見下表）
status_data object 狀態資料物件
billing object 計費資訊物件（有計費時回傳）
error_code int 錯誤碼，0 表示無錯誤
error_detail object 錯誤詳情（發生錯誤時回傳）

status_data 物件

欄位名 類型 說明
msg_time int64 訊息建立時間戳記(秒)
message_id string 訊息 ID
current_send_channel string 目前發送管道名稱
template_key string 範本設定 Key
business_id string 業務 ID
plan_id string 計畫 ID

billing 物件（有計費時回傳）

欄位名 類型 說明
cost float64 費用金額
currency string 幣種，固定為 "USD"

一般僅 sent 階段的訊息包含計費資訊。

error_detail 物件（發生錯誤時回傳）

欄位名 類型 說明
message string 錯誤訊息描述

範例：訊息發送成功

{ "total": 1, "rows": [ { "message_id": "123456789", "to": "+6598765432", "server": "sms", "channel": "sms", "itime": 1701234567, "custom_args": { "order_id": "ORDER123", "user_id": "USER456" }, "status": { "message_status": "sent", "status_data": { "msg_time": 1701234560, "message_id": "123456789", "current_send_channel": "CHANNEL_A", "template_key": "verify_code", "business_id": "1001", "plan_id": "7198765432109876543" }, "billing": { "cost": 0.005, "currency": "USD" }, "error_code": 0 } } ] }
              
              {
  "total": 1,
  "rows": [
    {
      "message_id": "123456789",
      "to": "+6598765432",
      "server": "sms",
      "channel": "sms",
      "itime": 1701234567,
      "custom_args": {
        "order_id": "ORDER123",
        "user_id": "USER456"
      },
      "status": {
        "message_status": "sent",
        "status_data": {
          "msg_time": 1701234560,
          "message_id": "123456789",
          "current_send_channel": "CHANNEL_A",
          "template_key": "verify_code",
          "business_id": "1001",
          "plan_id": "7198765432109876543"
        },
        "billing": {
          "cost": 0.005,
          "currency": "USD"
        },
        "error_code": 0
      }
    }
  ]
}
此代碼塊在浮窗中顯示

範例：訊息發送失敗

{ "total": 1, "rows": [ { "message_id": "123456790", "to": "+6598765433", "server": "sms", "channel": "sms", "itime": 1701234568, "status": { "message_status": "sent_fail", "status_data": { "msg_time": 1701234561, "message_id": "123456790", "current_send_channel": "CHANNEL_B", "template_key": "verify_code", "business_id": "1001", "plan_id": "7198765432109876543" }, "error_code": 4001, "error_detail": { "message": "Invalid phone number" } } } ] }
              
              {
  "total": 1,
  "rows": [
    {
      "message_id": "123456790",
      "to": "+6598765433",
      "server": "sms",
      "channel": "sms",
      "itime": 1701234568,
      "status": {
        "message_status": "sent_fail",
        "status_data": {
          "msg_time": 1701234561,
          "message_id": "123456790",
          "current_send_channel": "CHANNEL_B",
          "template_key": "verify_code",
          "business_id": "1001",
          "plan_id": "7198765432109876543"
        },
        "error_code": 4001,
        "error_detail": {
          "message": "Invalid phone number"
        }
      }
    }
  ]
}
此代碼塊在浮窗中顯示

訊息通知

訊息通知是指系統級的業務事件或告警。用於提醒業務方關注服務運作狀態、餘額、範本審核等重要資訊，便於及時處理和風險預警。

事件標識 說明
template_audit_result 範本審核結果的通知

訊息回應

訊息回應主要指與使用者或外部系統互動時的回調回應事件。

事件標識 說明
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!"
                }
            }
        }
    ]
}
此代碼塊在浮窗中顯示

系統事件

系統事件涵蓋與帳號、範本、API 呼叫等相關的操作行為。便於對帳號登入、金鑰變更、API 呼叫等關鍵操作進行監控、稽核和自動化處理。

事件標識 說明
account_login 帳號登入相關操作通知
key_manage 金鑰變更、管理等相關操作通知
template_manage 範本新增、修改、刪除等操作通知
api_call API 介面呼叫相關操作通知

回調資料結構

外層結構

{ "total": 1, "rows": [ { // 系統事件物件 } ] }
              
              {
  "total": 1,
  "rows": [
    {
      // 系統事件物件
    }
  ]
}
此代碼塊在浮窗中顯示
欄位 類型 說明
total int64 本次回調包含的事件總數
rows array 系統事件物件陣列

系統事件物件

欄位 類型 說明
server string 固定為 "SMS"
itime int64 事件發生時間戳記（秒）
system_event object 系統事件內容

system_event 物件

欄位 類型 說明
event string 事件類型
data object 事件資料

data 物件

欄位 類型 說明
business_id string 業務 ID
org_id string 組織 ID
operator object 操作者資訊

operator 物件

欄位 類型 說明
email string 操作者信箱（如有）
api_key string API Key（如有）
ip_address string 操作 IP

請求結構

{ "total": 1, "rows": [ { "server": "SMS", "itime": 1694012345, "system_event": { "event": "account_login", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "email": "foo@example.com", "api_key": "api-xxxx", "ip_address": "1.2.3.4" }, "account_login": { "action": "login_success" } } } } ] }
              
              {
  "total": 1,
  "rows": [
    {
      "server": "SMS",
      "itime": 1694012345,
      "system_event": {
        "event": "account_login",
        "data": {
          "business_id": "123",
          "org_id": "org-abc",
          "operator": {
            "email": "foo@example.com",
            "api_key": "api-xxxx",
            "ip_address": "1.2.3.4"
          },
          "account_login": {
            "action": "login_success"
          }
        }
      }
    }
  ]
}
此代碼塊在浮窗中顯示

帳號登入事件

欄位 類型 說明
action string 成功登入/登入失敗/登出
fail_reason string 登入失敗原因，僅 login_failed 時回傳

範例

{ "event": "account_login", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "email": "foo@example.com", "ip_address": "1.2.3.4" }, "account_login": { "action": "login_success" } } }
              
              {
  "event": "account_login",
  "data": {
    "business_id": "123",
    "org_id": "org-abc",
    "operator": {
      "email": "foo@example.com",
      "ip_address": "1.2.3.4"
    },
    "account_login": {
      "action": "login_success"
    }
  }
}
此代碼塊在浮窗中顯示

範本管理事件

欄位 類型 說明
action string 建立範本/更新範本/刪除範本
template_id string 範本 ID
template_name string 範本名稱

範例

{ "event": "template_manage", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "email": "foo@example.com", "ip_address": "1.2.3.4" }, "template_manage": { "action": "update template", "template_id": "tmpl-456", "template_name": "Verification Code" } } }
              
              {
  "event": "template_manage",
  "data": {
    "business_id": "123",
    "org_id": "org-abc",
    "operator": {
      "email": "foo@example.com",
      "ip_address": "1.2.3.4"
    },
    "template_manage": {
      "action": "update template",
      "template_id": "tmpl-456",
      "template_name": "Verification Code"
    }
  }
}
此代碼塊在浮窗中顯示

金鑰管理事件

欄位 類型 說明
action string 建立金鑰/更新金鑰/刪除金鑰/查看金鑰
api_key string API Key
description string 描述（可選）

範例

{ "event": "key_manage", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "email": "foo@example.com", "ip_address": "1.2.3.4" }, "key_manage": { "action": "create", "api_key": "apikey-789", "description": "新建密钥" } } }
              
              {
  "event": "key_manage",
  "data": {
    "business_id": "123",
    "org_id": "org-abc",
    "operator": {
      "email": "foo@example.com",
      "ip_address": "1.2.3.4"
    },
    "key_manage": {
      "action": "create",
      "api_key": "apikey-789",
      "description": "新建密钥"
    }
  }
}
此代碼塊在浮窗中顯示

API 呼叫事件

欄位 類型 說明
api_path string 介面路徑
method string HTTP 方法

範例

{ "event": "api_call", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "api_key": "apikey-789", "ip_address": "1.2.3.4" }, "api_call": { "api_path": "/api/v1/messages/send", "method": "POST" } } }
              
              {
  "event": "api_call",
  "data": {
    "business_id": "123",
    "org_id": "org-abc",
    "operator": {
      "api_key": "apikey-789",
      "ip_address": "1.2.3.4"
    },
    "api_call": {
      "api_path": "/api/v1/messages/send",
      "method": "POST"
    }
  }
}
此代碼塊在浮窗中顯示
Icon Solid Transparent White Qiyu
聯繫銷售