状态报告 (DLR)

短信发送状态报告 (Delivery Receipt, DLR),也称为短信回执消息。是为开发者程序化获取短信发送状态所提供的服务,UniSMS 支持通过 Webhook 主动推送短信状态报告。

设置

本功能为扩展服务,默认不开启。请根据您的实际需求前往控制台「扩展管理-状态报告」进行配置。

设置接收状态报告的 Webhook URL,并指定您需要接收的请求主体数据格式,支持 JSON 或 XML,默认为 JSON。即完成基础配置,准备接入。

接入

UniSMS 将以 POST 方法向您设定的 Webhook URL 发送 HTTP 请求,请求主体以 JSON 格式为例。

Request Body

参数名类型描述示例值
idstring消息标识b3f6106a6135ad78d6ac3f232bbf1812
statusstring发送状态delivered
tostring收件人手机号 (E.164)+8618600001234
regionCodestring国际代码CN
countryCodestring国际电话区号86
messageCountinteger计费消息总条数1
pricestring消费金额0.040000
currencystring计费币种CNY
errorCodestring回执代码DELIVRD
errorMessagestring回执描述消息发送成功
submitDatestring提交时间 (ISO 8601)2022-03-07T05:18:00.252Z
doneDatestring完成时间 (ISO 8601)2022-03-07T05:18:03.252Z

示例内容如下:

{
  "id": "b3f6106a6135ad78d6ac3f232bbf1812",
  "status": "delivered",
  "to": "+8618600001234",
  "regionCode": "CN",
  "countryCode": "86",
  "messageCount": 1,
  "price": "0.040000",
  "currency": "CNY",
  "errorCode": "DELIVRD",
  "errorMessage": "发送成功",
  "submitDate": "2022-03-07T05:18:00.252Z",
  "doneDate": "2022-03-07T05:18:03.252Z",
}

Response

响应 HTTP Status Code 200 即被视为状态报告接收成功,UniSMS 不对响应载荷进行额外校验。

签名验证

为进一步保障数据安全,UniSMS 支持通过配置签名以验证 Webhook 请求来自 UniSMS 且数据在传输过程中未被篡改。仅需在设置页面中启用「签名验证」并设定签名密钥 (Secret) 即可。

启用签名验证后,UniSMS 将在 Webhook 请求头中携带 Authorization 字段,其值构造格式为 UNI1-HMAC-SHA256 Timestamp={unix_epoch}, Nonce={nonce_str}, Signature={signature},示例如下:

Authorization: UNI1-HMAC-SHA256 Timestamp=1646634211, Nonce=0702b4ae425b0c2e, Signature=khZU1yxkyedU+va6L1WVgn418ycXs7xz0kxitwjFvl4=

提取 TimestampNonce 字段并将其字段名转换为小写后加入请求有效载荷中,根据参数 Key 按字典顺序排序 (正序),以 = 连接 Key-Value,以 & 连接参数对组成待签文本串,示例如下:

countryCode=86&currency=CNY&doneDate=2022-03-07T06%3A23%3A31.361Z&errorCode=DELIVRD&errorMessage=%E5%8F%91%E9%80%81%E6%88%90%E5%8A%9F&id=1e72734fabab9d42c9a32f9b8ad87940&messageCount=1&nonce=0702b4ae425b0c2e&price=0.045000&regionCode=CN&status=delivered&submitDate=2022-03-07T06%3A23%3A28.361Z&timestamp=1646634211&to=%2B8618600001234

使用 HmacSHA256 算法,以设置好的签名密钥 (Secret) 对待签文本串生成签名,输出为 Base64 字符串,示例如下:

khZU1yxkyedU+va6L1WVgn418ycXs7xz0kxitwjFvl4=

将从 Authorization 中提取的 Signature 值与生成的签名比对,一致则校验成功。

Mock 测试

为方便开发者快速接入,UniSMS 贴心的提供了 Mock 测试功能。您可以通过控制台直接向目标服务器发送模拟构造的 DLR 请求。

重新推送

在第一次推送状态报告失败后,UniSMS 仍会向目标地址重推信息,直至推送成功或超过最大推送次数。重推间隔为 1分钟5分钟10分钟30分钟1小时

Related Posts