短信状态报告回调--短信服务-火山引擎

文档中心

短信服务

回调消息

短信状态报告回调

您可以在短信服务控制台的回执配置中设置回调 URL，接收短信服务异步返回的短信状态报告，以确认短信发送是否成功。

注意事项

回调地址需要符合以下条件，才可以成功接收短信服务发送的短信状态报告。

使用 HTTP/HTTPS URL。
短信服务可以直接访问回调地址，即回调地址具备公网访问能力。
如果回调地址所在服务器设置了防火墙，请放行来自短信服务的请求。

准备工作

在您接收短信服务的回调消息之前，需要登录短信服务控制台配置用于接收回调消息的 URL。

登录短信服务控制台。
在左侧导航栏，选择通用管理 > 回执配置。
在回执配置页面，编辑默认状态报告地址。
设置您用于接收回调消息的 URL。URL 格式为http(s)://<您的回调地址>。

在短信服务控制台设置回调地址后，如果您调用 SendSms 接口发送短信，则短信服务会异步向回调地址返回短信状态报告。

回调请求说明

当短信服务返回短信状态报告时，会向回调地址发送 POST 请求。本章节介绍请求 Header 和 Body 包含的参数说明。

参数	取值	描述
Content-Type	application/json;charset=utf-8	定义网络文件的类型和网页的编码。
Accept-Encoding	gzip, deflate	采用指定的压缩格式传输数据。
Accept	/	指定客户端希望接收的数据类型。

Body

请求体整体是一个 JSON 数组。

参数	类型	描述
account	string	火山引擎账号
sub_account	string	消息组ID
status_code	string	发送状态，"0"代表成功，其余表示失败
description	string	状态描述
signature	string	签名
template_id	string	模板ID
mobile	string	手机号
channel_type	string	短信类型，可能值：CN_OTP
message_id	string	发送时返回的`message_id`字段
msg_count	int	拆分条数
service_id	string	服务参数，可用于定位问题，非必传
ext	string	发送时传递的`Tag`字段
send_time	int64	短信发送时间，milliseconds时间戳
recv_time	int64	短信接收时间，milliseconds时间戳
mccmnc	string	移动网络提供者唯一代码 ,仅当非中国大陆运营商时有值
iso_code	string	ISO 3166-1 国家代码
carrier_name	string	运营商名称，可能值：China Mobile/China Telecom/China Unicom

回调结果示例

[
  {
    "account": "200****",
    "sub_account": "1504****",
    "signature": "短信服务",
    "mobile": "188******",
    "channel_type": "CN_OTP",
    "service_id": "106966940****",
    "send_time": 1669171012444,
    "template_id": "SPT_0fa7****",
    "ext": "123456",
    "message_id": "bde1b10d-19cf-460f-abcd-26231a82****",
    "recv_time": 1669171015941,
    "status_code": "0",
    "description": "发送成功",
    "msg_count": 1,
    "mccmnc": "",
    "iso_code": "CN",
    "carrier_name": "China Mobile"
  }
]

发送状态错误码（status_code）及说明

请参考发送状态错误码。

返回值

要求用户侧接收成功后，返回 httpStatus为200，否则火山侧会认为回执失败

常见问题

回执推送失败后会重试几次？

答：10次，时间间隔：[0,5,10,30,120,300,1200,3600,21600,86400]，单位秒。

返回httpStatus为200的格式是怎样的？

答：http协议里的statuscode返200即可，不是在请求体中返回。

最近更新时间：2026.03.16 21:53:00

这个页面对您有帮助吗？

有用

无用

短信服务

注意事项 #

准备工作 #

回调请求说明 #

Header #

Body #

回调结果示例 #

发送状态错误码（status_code）及说明 #

返回值 #

常见问题 #