回调设置

回调设置用于配置业务系统的回调地址，实时接收 EngageLab NewSMS 服务推送的「消息状态」和「消息响应」事件。通过回调，您可以实现消息链路的自动化统计、策略补发、系统告警等业务场景，提升消息处理效率和系统智能化水平。

消息状态：指单条 SMS 消息在发送、送达、已读、验证等各环节的状态变化。
消息响应：指用户上行（回复）短信的内容与事件。

回调列表

回调列表页面集中展示所有已配置的回调信息及其健康状态，便于统一管理和维护。

搜索栏：支持按回调描述实时筛选，快速定位目标回调。
配置回调：点击按钮进入新建回调流程，便于灵活扩展回调需求。

alt text

字段说明

字段	说明
回调描述	回调配置的自定义说明，便于区分不同用途。
回调地址	回调接口的 URL 地址。
状态	回调接口健康状态。
消息状态	已勾选的消息状态事件数量，hover 显示具体事件类型。
消息响应	已勾选的消息响应事件数量，hover 显示具体事件类型。
操作	包含“刷新”、“编辑”、“删除”操作。刷新可检测健康状态，删除均需二次确认。

配置回调

点击右上角【配置回调】后，进入页面。

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 。

回调请求体

回调事件触发时，EnageLab 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!"
                }
            }
        }
    ]
}

此代码块在浮窗中显示