文档中心

SendSms - 发送短信

最近更新时间：2024.01.29 14:41:45

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

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

注意事项

一次调用中最多支持设置 200 个手机号
当传入多个手机号时，部分错误码将通过回执返回

请求说明

请求方式: POST
请求地址: https://sms.volcengineapi.com?Action=SendSms&Version=2020-01-01

API Explorer

您可以通过API Explorer在线发起调用，无需关注签名生成过程，快速获取调用结果。

去调试

请求参数

Query

名称	类型	是否必填	示例值	描述
Action	String	是	SendSms	要执行的操作，取值：SendSms
Version	String	是	2020-01-01	API的版本，取值：2020-01-01

Body

名称	类型	是否必填	示例值	描述
SmsAccount	String	是	A123****	消息组 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	透传字段。这个字段用于关联发送请求和短信回执，在回传回执消息的时候，会将该字段原样返回给服务使用方。例：如果你在短信发送请求的 Tag 中传了一个唯一的 ID，在短信回执的 ext 参数中会把这个 ID 也原样返回给调用方。

响应数据

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

示例

成功请求示例

请求

{
    "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****"
        ]
    }
}

失败响应示例

请求

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

响应

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

错误码

下表提供了该接口业务逻辑相关的错误码。公共错误码请参见公共错误码。

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