发送短信

功能介绍

向单个或多个用户发送相同内容的短信。

前提条件

已创建短信应用。
已申请短信签名，获取签名通道号。
已申请短信模板，获取模板ID。

注意事项

最多允许携带500个号码，每个号码最大长度为21位。

URI

POST /v1/aim/sms/messages

请求参数

表1 请求Header参数
参数	是否必选	参数类型	描述
X-Auth-Token	是	String	用户Token。通过调用IAM服务获取用户Token接口获取（响应消息头中X-Subject-Token的值）。

表2 请求Body参数
参数	是否必选	参数类型	描述
channel_num	否	String	短信通道号。说明：模板所属签名的通道号，可以从“云消息服务KooMessage-管理控制台-短消息配置（国内）-短消息签名管理-通道号”中获取。未填写时默认取模板所属签名通道号。最小长度：1 最大长度：21
template_id	是	String	短信模板ID。说明：可以从“云消息服务KooMessage-管理控制台-短消息配置（国内）-短消息模板管理-模板ID”中获取。最小长度：1 最大长度：32
signature	否	String	短信签名名称(暂不支持)。说明：签名名称，必须是已审核通过的，与模板类型一致的签名名称。仅在template_id指定的模板类型为通用模板时生效且必填，用于指定在通用模板短信内容前面补充的签名。最小长度：0 最大长度：32
task_name	否	String	发送任务名称。说明：不能为空白字符串，允许重复，为空时默认为Task_拼接当前时间值。最小长度：1 最大长度：30
to	是	Array of strings	短信接收方的号码。所填号码可以不带+86，系统默认添加+86，最多允许携带500个号码。示例：1315678，+861556666。数组长度：1 - 500
template_params	是	Array of strings	短信模板参数，字符串数组，最多20个。短信模板中的变量类型可以是：短链、电话号码、其他号码（验证码、订单号、密码等）、日期时间、金额、其他（名称、账号、地址等）。数组中参数按短信模板中的变量顺序进行匹配，比如短信模板内容中按顺序有3个变量：${1}、${2}、${3}，其中${1}表示手机号码，${2}表示短链，${3}表示日期，则sms_params传的是：[手机号码, 短链, 日期]。电话号码：长度限制1-15个字符，可以传入手机号、座机号、95或400、800电话等。其他号码：长度限制1-20个字符，不允许出现手机号、QQ号、微信号、URL等联系方式，仅支持大小写字母和数字组合。时间：长度限制1-20个字符，日期格式：yyyyMMdd、yyyy-MM-dd、yyyy/MM/dd、yyyy年mm月dd日，时间格式：HH:mm:ss、HH:mm、HH点mm分、HH点mm。如果需要同时指定日期和时间，请在模板中填充两个变量，一个变量传入日期，另一个变量传入时间。金额：长度限制1-20个字符，仅支持传入能够正常表达金额的数字、小数点或中文，例如壹、贰、叁、肆等，支持传入IP地址，例如：10.1.1.10。￥$等货币符号需要放在模板中，不支持变量传入。其他：长度限制1-20个字符，可以设置为公司/产品/地址/姓名/内容/账号/会员名等。不允许出现QQ号/微信号（公众号）/手机号/网址/座机号等联系方式。如果确有需要，请将联系方式放入模板中，不允许在传入值中携带“.”（短链参数除外）、“。”、“'”、“<”、“>”、“{”或“}”。否则，可能导致模板变量解析异常。不允许在传入值中携带“.”，即不支持传入IP地址，如变量取值为IP地址，请申请模板时选择变量属性为“金额”。
extend	否	String	扩展参数。在状态报告中会原样返回。不允许赋空值，不允许携带以下字符：“{”，“}”（即大括号）。最小长度：0 最大长度：128

响应参数

状态码： 200

表3 响应Body参数
参数	参数类型	描述
task_id	String	任务ID。最小长度：1 最大长度：50
status	String	任务状态。 Success：发送成功 Failed：发送失败说明：此状态仅代表任务提交状态，不代表智能信息发送结果。用户手机接收智能信息结果请以收到的回执结果为准，也可通过查询智能信息发送明细API获取或登录KooMessage控制台查看。最小长度：1 最大长度：20
result	Array of SmsDetailResponse objects	短信ID列表，当目标号码存在多个时，每个号码都会返回一个SmsID。当返回异常响应时不携带此字段。

表4 SmsDetailResponse
参数	参数类型	描述
to	String	短信接收方的号码。最小长度：1 最大长度：21
channel_num	String	短信发送方的号码。最小长度：1 最大长度：21
msg_id	String	短信的唯一标识。最小长度：1 最大长度：50
send_status	String	短信状态码。以下举例状态码及其说明，具体处理建议请参考API错误码。 000000：短信平台处理请求成功 E200015：待发送短信数量太大 E200028：模板变量校验失败 E200029：模板类型校验失败 E200030：模板未激活 E200031：协议校验失败 E200033：模板类型不正确 E200041：同一短信内容接收号码重复最小长度：1 最大长度：7
create_time	String	短信资源的创建时间。即短信平台接收到用户发送短信请求的时间，为UTC时间。格式为：yyyy-MM-dd'T'HH:mm:ss'Z'。最小长度：1 最大长度：20

状态码： 400

表5 响应Body参数
参数	参数类型	描述
error_code	String	结果状态码。最小长度：0 最大长度：32
error_msg	String	结果详情。最小长度：0 最大长度：32

状态码： 500

表6 响应Body参数
参数	参数类型	描述
error_code	String	结果状态码。最小长度：0 最大长度：32
error_msg	String	结果详情。最小长度：0 最大长度：32

请求示例

向用户发送短信，短信通道号为882306039，模板ID为1512。

https://koomessage.myhuaweicloud.cn/v1/aim/sms/messages

{
  "channel_num" : "8823060****39",
  "template_id" : "1512****",
  "signature" : "测试签名",
  "app_name" : "OPACCOUNT688",
  "task_name" : "测试发送",
  "to" : [ "139274****98", "15527****78" ],
  "template_params" : [ "kXfvIwzs" ]
}

响应示例

状态码： 200

发送短信响应体。

{
  "status" : "Success",
  "result" : [ {
    "to" : "+86139274****8",
    "channel_num" : "8823060****9",
    "msg_id" : "b24f1f03-556e-468e-9fe1-23729b9414d7_72****6",
    "create_time" : "2023-08-11T12:11:24",
    "send_status" : "000000"
  }, {
    "to" : "+861552****978",
    "channel_num" : "8823060806439",
    "msg_id" : "b24f1f03-556e-468e-9fe1-23729b9414d7_****407",
    "create_time" : "2023-08-11T12:11:24",
    "send_status" : "000000"
  } ],
  "task_id" : "a914ca57-09cf-4899-af62-f9a****06c3c"
}