文档首页/ 云消息服务 KooMessage/ API参考/ API/ 短信发送/ 发送短信
更新时间：2025-01-06 GMT+08:00
查看PDF
分享

发送短信

功能介绍

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

  • 前提条件

  1. 已创建短信应用。

  2. 已申请短信签名，获取签名通道号。

  3. 已申请短信模板，获取模板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"
}

状态码

状态码

描述

200

发送短信响应体。

400

非法参数。

500

内部错误。

错误码

请参见错误码。

父主题： 短信发送

相关文档