发送短信SendSms

最近更新时间：2023.07.27 16:11:07

首次发布时间：2021.03.23 15:19:39

短信服务方可调用 SendSms 接口向一个或者多个手机号发送相同内容的短信。

接口说明

请求方式：POST
接口地址：https://sms.volcengineapi.com?Action=SendSms&Version=2020-01-01
注意事项：一次调用中最多支持设置 200 个手机号

请求参数

参数	数据类型	是否必填	示例值	描述
AccessKey	string	是	AKLTNzEzY2****	发送请求的火山引擎账号的 Access Key ID。您可以登录密钥管理页面获取。
SecretKey	string	是	RGTLuSHvnYxn****	发送请求的火山引擎账号的 Secret Access Key。您可以登录密钥管理页面获取。
ServiceName	string	是	volcSMS	服务名称。短信服务的服务名称为`volcSMS`。
Region	string	是	cn-north-1	区域名称。短信服务的区域名称为`cn-north-1`。
Content-Type	string	是	application/json;charset=utf-8	指定请求消息体的结构化格式。短信服务的 Content-Type 为`application/json;charset=utf-8`。

Query

参数	数据类型	是否必填	示例值	描述
Action	string	是	SendSms	接口名称。该接口固定值为`SendSms`。
Version	string	是	2020-01-01	接口版本。短信服务接口版本为`2020-01-01`。

Body

参数	数据类型	是否必填	示例值	说明
SmsAccount	string	是	A123****	消息组 ID。您可在该页面https://console.volcengine.com/sms/subaccount/list?subAccountId=7331c4b7查看消息组ID。
Sign	string	是	短信服务	短信签名内容。您需要使用已通过审核的短信签名内容。
TemplateID	string	是	ST_6f8c****	短信模板 ID。
TemplateParam	string	否	{"code":"1234"}	当指定的短信模板（TemplateID）存在变量时，您需要设置变量的实际值。支持传入一个或多个参数，格式示例：`{"code1":"1234", "code2":"5678"}`。
PhoneNumbers	string	是	188********	短信发送的目标手机号。配置说明：最多支持设置 200 个手机号码，多个号码之间使用英文逗号（,）间隔。如果您设置的是中国大陆手机号，则国际区号为可选项。例如`+86188******`和`188******`都是合法的手机号码。如果您设置的是非中国大陆手机号，则国际区号为必填项，且格式需符合 E.164 标准。
Tag	string	否	123456	透传字段，最大长度限制为512。这个字段用于关联发送请求和短信回执，在回传回执消息的时候，会将该字段原样返回给服务使用方。例：如果你在短信发送请求的 Tag 中传了一个唯一的 ID，在短信回执的 ext 参数中会把这个 ID 也原样返回给调用方。

返回参数

请求响应数据以JSON格式返回，以下仅列出了短信业务逻辑相关的字段，其他公共返回参数详见返回结果。

参数	数据类型	描述
ResponseMetadata	ResponseMetadata	响应公共参数。包含的参数说明请参见ResponseMetadata。
Result	Result	响应业务参数。包含的参数说明请参见Result。

ResponseMetadata

参数	数据类型	描述
RequestId	string	请求 ID。
Action	string	请求的接口名称。
Version	string	请求的版本号。
Service	string	请求的服务名称。
Region	string	请求的区域。
Error	Error	错误信息。如果请求没有异常则不会返回错误信息。包含的参数说明请参见Error。

Result

参数	数据类型	描述
MessageID	Array	响应的消息 ID。手机号解析成功：返回多条消息ID。每条消息 ID 对应一个手机号的请求，其中展示顺序为传入电话号码的顺序；手机号解析失败：只返回一条消息ID；

Error

参数	数据类型	描述
Code	string	错误码。
Message	string	错误信息。

示例

请求示例

{
    "SmsAccount": "A123****",
    "Sign": "短信服务",
    "TemplateID": "ST_6f8c****",
    "TemplateParam": "{\"code\":\"1234\"}",
    "Tag": "123456",
    "PhoneNumbers": "188********"
}

返回示例

正确返回示例

{
    "ResponseMetadata": {
        "RequestId": "202211221049040101310571****",
        "Action": "SendSms",
        "Version": "2020-01-01",
        "Service": "volcSMS",
        "Region": "cn-north-1"
    },
    "Result": {
        "MessageID": [
            "31293de5-9ef6-4e11-abcd-69659****"
        ]
    }
}

错误返回示例

{
    "ResponseMetadata": {
        "RequestId": "202211221050270101330310****",
        "Action": "SendSms",
        "Version": "2020-01-01",
        "Service": "volcSMS",
        "Region": "cn-north-1",
        "Error": {
            "Code": "ZJ10101",
            "Message": "SmsAccount not exist."
        },
	    "Result": {
	        "MessageID": [
	            "31283de5-9ef6-5e11-abcd-69659****"
	        ]
	    }
    }
}

错误码

如果您在返回结果中遇到错误消息，可以使用下表作为详细信息和解决方案的指南。其中火山引擎网关公共错误码请参考火山引擎网关公共错误码。

错误码	描述	处理建议
RE:0000	账号鉴权失败	请检查参数是否使用正确或参考SDK内的鉴权处理
RE:0001	账号短信服务未开通	请检查当前AccessKey是否已经开通短信服务。如已开通短信服务，则参照短信服务文档调用接口。
RE:0002	账号被关停	请联系火山引擎客服确认
RE:0003	子账号不存在	请填写正确的SmsAccount，即消息组ID
RE:0004	签名错误	请确认对应SmsAccount下是否存在该签名，或登录短信服务控制台，在短信签名页面查询此签名是否审核通过。
RE:0005	模板错误	请检查对应SmsAccount下是否存在该模板，或登录短信服务控制台，在短信模板页面查询此模板是否审核通过。
RE:0006	手机号格式错误	参数PhoneNumbers请传入正确的格式。国内消息：+86或无任何前缀的11位手机号码，例如1580799**。国际/港澳台消息：国际区号+号码，例如8520000**。
RE:0007	IP校验错误	已开启IP白名单，请联系火山引擎客服确认当前IP是否已加白。
RE:0009	请求参数错误	请根据接口文档检查参数是否正确
RE:0010	账号欠费	请登录控制台费用中心查询余额是否充足
RE:0011	不支持对应地区下发	请在允许的地区内进行下发或者申请对应地区的短信下发
RE:0012	不支持的发送类型	请登录控制台，在消息组列表点击编辑，检查允许发送的短信类型是否勾选
RE:0500	未知交互类错误	请尝试重新调用接口
VE:0001	账户不允许发送视频短信	请检查当前AccessKey是否已经开通视频短信服务。如已开通视频短信服务，则参照视频短信务文档调用接口。
VE:0002	视频短信模板不可用	请确认对应的模板是否审核通过或允许使用
VE:0003	签名和申请模板时不一致	请确保使用的签名和报备模板时保持一致