Docs
导览

状态报告 (DLR)

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

设置

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

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

接入

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

Request Body

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

示例内容如下：

{
  "id": "9f1c4ebbbfacae8d3733abd22f67981c",
  "status": "delivered",
  "to": "+8618600001234",
  "iso": "CN",
  "cc": "86",
  "parts": 1,
  "price": "0.045000",
  "currency": "CNY",
  "errorCode": "DELIVRD",
  "errorMessage": "Delivered",
  "submitDate": "2022-03-07T05:18:00.252Z",
  "doneDate": "2022-03-07T05:18:03.252Z",
}

Response

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

签名验证

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

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

Authorization: UNI1-HMAC-SHA256 Timestamp=1646630283, Nonce=815962dd19a52a64, Signature=9Eli20S/7n1H/ODMnbNWXuN86gulv26iUMQiUFB727U=

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

cc=86&currency=CNY&doneDate=2022-03-07T06%3A23%3A31.361Z&errorCode=DELIVRD&errorMessage=Delivered&id=9f1c4ebbbfacae8d3733abd22f67981c&parts=1&nonce=815962dd19a52a64&price=0.045000&iso=CN&status=delivered&submitDate=2022-03-07T06%3A23%3A28.361Z&timestamp=1646630283&to=%2B8618600001234

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

9Eli20S/7n1H/ODMnbNWXuN86gulv26iUMQiUFB727U=

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

Mock 测试

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

重新推送

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

本页目录