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

发送分批短信

功能介绍

该接口用于向不同用户发送不同内容的短信。

  • 前提条件

  1. 已创建短信应用。

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

  3. 已申请短信模板，获取模板ID。

  • 注意事项

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

URI

POST /v1/aim/sms/diff-messages

请求参数

表1 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

是

String

用户Token。通过调用IAM服务获取用户Token接口获取（响应消息头中X-Subject-Token的值）。
表2 请求Body参数

参数

是否必选

参数类型

描述

sms_content

是

Array of MsgContent objects

短信内容。

channel_num

是

String

短信通道号。

说明：

模板所属签名的通道号，可以从“云消息服务KooMessage-管理控制台-短消息配置（国内）-短消息签名管理-通道号”中获取。

签名和模板为对应关系，模板所属签名可在“短消息模板管理”查看。未填写时默认取sms_content第一条数据模板所属签名的通道号。

最小长度：1

最大长度：21

extend

否

String

扩展参数。

在状态报告中会原样返回。

不允许赋空值，不允许携带以下字符：“{”，“}”（即大括号）。

最小长度：0

最大长度：128

task_name

否

String

发送任务名称。

说明：

不能为空白字符串，允许重复，为空时默认为Task_拼接当前时间值。

最小长度：0

最大长度：30
表3 MsgContent

参数

是否必选

参数类型

描述

to

是

Array of strings

群发短信接收方的号码。

标准号码格式：+{国家码}{地区码}{终端号码}。

发送国内短信：接收号码为国内手机号码时，所填号码可以不带+86，系统默认添加86。每个号码最大长度为21位，最多允许携带500个号码。

数组长度：1 - 500

template_id

是

String

短信模板ID。

最小长度：1

最大长度：50

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地址，请申请模板时选择变量属性为“金额”。

响应参数

状态码： 200

表4 响应Body参数

参数

参数类型

描述

task_id

String

任务ID。

最小长度：1

最大长度：50

status

String

任务状态。

  • Success：发送成功

  • Failed：发送失败

说明：

此状态仅代表任务提交状态，不代表智能信息发送结果。用户手机接收智能信息结果请以收到的回执结果为准，也可通过查询智能信息发送明细API获取或登录KooMessage控制台查看。

最小长度：1

最大长度：20

result

Array of SmsDetailResponse objects

短信ID列表，当目标号码存在多个时，每个号码都会返回一个SmsID。

当返回异常响应时不携带此字段。
表5 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

表6 响应Body参数

参数

参数类型

描述

error_code

String

结果状态码。

最小长度：0

最大长度：32

error_msg

String

结果详情。

最小长度：0

最大长度：32

状态码： 500

表7 响应Body参数

参数

参数类型

描述

error_code

String

结果状态码。

最小长度：0

最大长度：32

error_msg

String

结果详情。

最小长度：0

最大长度：32

请求示例

向不同用户发送不同内容的短信。

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

{
  "channel_num" : "882306284****",
  "task_name" : "多模板API",
  "sms_content" : [ {
    "to" : [ "1552785****" ],
    "template_id" : "151**334",
    "template_params" : [ "fnafc.cc/kXfvIwzs" ]
  }, {
    "to" : [ "1392740****" ],
    "template_id" : "151**335",
    "template_params" : [ "(KM:F49C3EGz)" ]
  } ]
}

响应示例

状态码： 200

发送短信响应体。

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

状态码

状态码

描述

200

发送短信响应体。

400

非法参数。

500

内部错误。

错误码

请参见错误码。

父主题： 短信发送

相关文档