发送智能信息

功能介绍

根据客户的参数发送任务名称、智能信息模板ID等进行智能信息发送。一次最多发送100个智能信息。

URI

POST /v1/aim/send-tasks

请求参数

表1 请求Header参数
参数	是否必选	参数类型	描述
X-Auth-Token	是	String	用户Token。通过调用IAM服务获取用户Token接口获取（响应消息头中X-Subject-Token的值）。
Content-Type	是	String	请求体参数类型，该字段必须设置为：application/json。

表2 请求Body参数
参数	是否必选	参数类型	描述
task_name	是	String	智能信息发送任务名称。说明：不能为空白字符串。
sms_channel	是	SmsChannel object	短信发送通道参数。
resolve_task	是	CreateAIMSendResolve object	短链生成配置。

表3 SmsChannel
参数	是否必选	参数类型	描述
channel_number	是	String	短信通道号。说明：必须与另外三个字段sms_tpl_id、sms_sign、sms_app_name相匹配，这些字段信息可以从“云消息服务KooMessage-管理控制台-短信配置-短信签名管理-通道号”中获取。
sms_tpl_id	是	String	短信模板ID。说明：必须与另外三个字段channel_number、sms_sign、sms_app_name相匹配，这些字段信息可以从“云消息服务KooMessage-管理控制台-短信配置-短信模板管理-模板ID”中获取。
sms_sign	是	String	短信签名。说明：必须与另外三个字段channel_number、sms_tpl_id、sms_app_name相匹配，这些字段信息可以从“云消息服务KooMessage-管理控制台-短信配置-短信模板管理-所属签名”中获取。
sms_app_name	是	String	短信应用名称。说明：必须与另外三个字段channel_number、sms_sign、sms_tpl_id相匹配，这些字段信息可以从“云消息服务KooMessage-管理控制台-短信配置-短信模板管理-所属应用”中获取。

表4 CreateAIMSendResolve
参数	是否必选	参数类型	描述
tpl_id	是	String	智能信息模板ID，由9位数字组成。最小长度：1 最大长度：9
resolve_times	是	Integer	短链的最大解析次数。说明：个性化短链只支持最大解析数为1，设置其他值无效。最小值：1 最大值：10000000
aim_code_type	是	String	智能信息编码类型。 individual：个性化
generation_type	否	String	生成短码方式。 1：标准 2：自定义说明：默认1，即标准生成短码。
domain	否	String	自定义短链域名，样例：km2g.cn、km2g.cn/a1、km2g.cn/a1/b2。说明：自定义短码即generation_type为2时，此参数为必填，域名需要提前申请。域名申请支持单独域名申请，也支持域名加路径申请，最多支持两层路径。最大长度：100
expiration_time	是	Integer	失效时间（天）。aim_code_type为individual个性化时，取值范围为1~7。说明：失效时间精确到秒，例如参数设置为1，创建时间为2022-07-22 21:10:12，过期时间为2022-07-23 21:10:12。
params	是	Array of CreateSendResolveTaskParam objects	短链解析详情列表。一次请求最多100个短链。

表5 CreateSendResolveTaskParam
参数	是否必选	参数类型	描述
cust_flag	是	String	创建解析任务时填写用户唯一标识，手机号码或者任何的唯一标识，唯一标识不超过64个字符。发送智能信息时则必须填客户的手机号码。样例为：130****0001。最大长度：64
dync_params	否	Map<String,String>	智能信息模板动态参数。说明：使用动态参数模板时，aim_code_type字段只能为individual。
custom_url	否	String	自定义跳转地址。长度要求不超过2048。说明：未填时，终端用户点击短信原文中的短链后，跳转智能信息模板H5页已填时，终端用户点击短信原文中的短链后，跳转该字段对应的页面，填写时必须为http或https作为前缀使用自定义跳转链接功能请联系KooMessage运营人员进行域名备案自定义短码即generation_type为2时，不支持自定义跳转链接功能，传入的参数值无效
custom_short_code	否	String	自定义短码，支持长度为3到10位的数字或大小写字母。样例为：aDC123。说明：自定义短码即generation_type为2时，此参数为必填。最小长度：3 最大长度：10
sms_params	否	Array of strings	短信模板参数。短信模板中的变量类型可以是：短链、电话号码、其他号码（验证码、订单号、密码等）、日期时间、金额、其他（名称、账号、地址等）。字符串数组，最多19个。数组中参数按短信模板中除了短链类型参数外的变量的顺序进行匹配，比如短信模板内容中按顺序有3个变量：${1}、${2}、${3}，其中${1}表示手机号码，${2}表示短链，${3}表示日期，则sms_params传的是：[手机号码, 日期]。如果短信模板只包含短链1个参数，则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

表6 响应Body参数
参数	参数类型	描述
task_name	String	智能信息发送任务名称。
sms_channel	SmsChannel object	短信发送通道参数。
resolve_task	CreateAIMTaskResolveResult object	短链生成配置。
task_id	String	任务ID。
task_state	String	任务状态。 Success：发送成功 Failed：发送失败说明：此状态仅代表任务提交状态，不代表智能信息发送结果。用户手机接收智能信息结果请以收到的回执结果为准，也可通过查询智能信息发送明细API获取或登录KooMessage控制台查看。
creation_time	String	创建时间。样例：2019-10-12T07:20:50.522Z。
submission_count	Integer	提交的手机号码总数。
send_count	Integer	发送数量。
resolve_count	Integer	智能信息解析成功的手机号码总数。
support_resolve_count	Integer	支持智能信息解析的手机号码总数。说明：通过API发送的智能信息任务不做解析能力判断，返回-1作为标识。
failed_short_chains	Array of CreateResolveTaskResultParam objects	短链生成失败列表。

表7 SmsChannel
参数	参数类型	描述
channel_number	String	短信通道号。说明：必须与另外三个字段sms_tpl_id、sms_sign、sms_app_name相匹配，这些字段信息可以从“云消息服务KooMessage-管理控制台-短信配置-短信签名管理-通道号”中获取。
sms_tpl_id	String	短信模板ID。说明：必须与另外三个字段channel_number、sms_sign、sms_app_name相匹配，这些字段信息可以从“云消息服务KooMessage-管理控制台-短信配置-短信模板管理-模板ID”中获取。
sms_sign	String	短信签名。说明：必须与另外三个字段channel_number、sms_tpl_id、sms_app_name相匹配，这些字段信息可以从“云消息服务KooMessage-管理控制台-短信配置-短信模板管理-所属签名”中获取。
sms_app_name	String	短信应用名称。说明：必须与另外三个字段channel_number、sms_sign、sms_tpl_id相匹配，这些字段信息可以从“云消息服务KooMessage-管理控制台-短信配置-短信模板管理-所属应用”中获取。

表8 CreateAIMTaskResolveResult
参数	参数类型	描述
tpl_id	String	智能信息模板ID，由9位数字组成。
resolve_times	Integer	短链的最大解析次数。
aim_code_type	String	智能信息编码类型。 individual：个性化
generation_type	String	生成短码方式。 1：标准 2：自定义
domain	String	自定义短链域名，样例：km2g.cn、km2g.cn/a1、km2g.cn/a1/b2。
expiration_time	Integer	失效时间（天）。
params	Array of CreateSendResolveTaskParam objects	短链解析详情列表。一次请求最多100个短链。

表9 CreateSendResolveTaskParam
参数	参数类型	描述
cust_flag	String	创建解析任务时填写用户唯一标识，手机号码或者任何的唯一标识，唯一标识不超过64个字符。发送智能信息时则必须填客户的手机号码。样例为：130****0001。最大长度：64
dync_params	Map<String,String>	智能信息模板动态参数。说明：使用动态参数模板时，aim_code_type字段只能为individual。
custom_url	String	自定义跳转地址。长度要求不超过2048。说明：未填时，终端用户点击短信原文中的短链后，跳转智能信息模板H5页已填时，终端用户点击短信原文中的短链后，跳转该字段对应的页面，填写时必须为http或https作为前缀使用自定义跳转链接功能请联系KooMessage运营人员进行域名备案自定义短码即generation_type为2时，不支持自定义跳转链接功能，传入的参数值无效
custom_short_code	String	自定义短码，支持长度为3到10位的数字或大小写字母。样例为：aDC123。说明：自定义短码即generation_type为2时，此参数为必填。最小长度：3 最大长度：10
sms_params	Array of strings	短信模板参数。短信模板中的变量类型可以是：短链、电话号码、其他号码（验证码、订单号、密码等）、日期时间、金额、其他（名称、账号、地址等）。字符串数组，最多19个。数组中参数按短信模板中除了短链类型参数外的变量的顺序进行匹配，比如短信模板内容中按顺序有3个变量：${1}、${2}、${3}，其中${1}表示手机号码，${2}表示短链，${3}表示日期，则sms_params传的是：[手机号码, 日期]。如果短信模板只包含短链1个参数，则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地址，请申请模板时选择变量属性为“金额”。

**表10** CreateResolveTaskResultParam
参数	参数类型	描述
cust_flag	String	创建解析任务时填写用户唯一标识，手机号码或者任何的唯一标识，唯一标识不超过64个字符。发送智能信息时则必须填客户的手机号码。样例为：130****0001。
cust_id	String	租户ID。
dync_params	Map<String,String>	动态参数。
custom_url	String	自定义跳转地址。说明：未填时，终端用户点击访问短信原文中的短链，跳转智能信息H5页已填时，终端用户点击访问短信原文中的短链，跳转客户填写的链接落地页，填写时必须为http或https作为前缀
aim_url	String	完整的短链连接地址，通过自己的短信渠道发送时，需要把该短链添加到短信模板中，并确保发送短信时的签名与创建短链时的签名保持一致。样例：km2g.cn/PDiWqc。
aim_code	String	智能信息编码，样例：PDiWqc。
ext_data	String	自定义扩展参数。说明：预留字段。
result_code	String	短链申请结果返回码。 0：成功非0：失败，具体请参见错误码
error_message	String	短链申请结果错误描述。
generate_date	String	短链生成时间。样例为：2019-10-12T07:20:50Z。
expire_date	String	短链到期时间。样例为：2019-10-12T07:20:50Z。
resolved_date	String	解析时间。样例为：2019-10-12T07:20:50Z。说明：预留字段。
resolved_times	Integer	短链实际解析次数。说明：预留字段。
custom_short_code	String	自定义短码，支持长度为3到10位的数字或大小写字母。样例为：aDC123。

状态码： 400

**表11** 响应Body参数
参数	参数类型	描述
error_code	String	结果状态码。
error_msg	String	结果详情。
error_message	AnyType	结果详情。说明：该字段在以后可能会废弃，建议使用error_msg字段对接。

状态码： 500

**表12** 响应Body参数
参数	参数类型	描述
error_code	String	结果状态码。
error_msg	String	结果详情。
error_message	AnyType	结果详情。说明：该字段在以后可能会废弃，建议使用error_msg字段对接。

请求示例

发送智能信息。模板ID为"600000001"，短链最大解析次数为1次，过期时间为7天，发送手机号码如"131****0000"；通道号为"8822053111111"，短信模板ID为"15010661"。

https://koomessage.myhuaweicloud.cn/v1/aim/send-tasks

{
  "task_name" : "智能信息发送",
  "sms_channel" : {
    "channel_number" : "8822053111111",
    "sms_tpl_id" : 15010661,
    "sms_sign" : "华为云KooMessage",
    "sms_app_name" : "KooMessage"
  },
  "resolve_task" : {
    "tpl_id" : "600000001",
    "resolve_times" : 1,
    "aim_code_type" : "individual",
    "domain" : null,
    "expiration_time" : 7,
    "params" : [ {
      "cust_flag" : "131****0000",
      "custom_url" : "https://www.example.com"
    } ]
  }
}

发送智能信息-动态参数。模板ID为"600000002"，短链最大解析次数为1次，过期时间为7天，发送手机号码如"131****0000"，分别设置动态参数；通道号为"8822053111111"，短信模板ID为"15010661"。

https://koomessage.myhuaweicloud.cn/v1/aim/send-tasks

{
  "task_name" : "智能信息发送-动态参数",
  "sms_channel" : {
    "channel_number" : "8822053111111",
    "sms_tpl_id" : 15010661,
    "sms_sign" : "华为云KooMessage",
    "sms_app_name" : "KooMessage"
  },
  "resolve_task" : {
    "tpl_id" : "600000002",
    "resolve_times" : 1,
    "aim_code_type" : "individual",
    "domain" : null,
    "expiration_time" : 7,
    "params" : [ {
      "cust_flag" : "131****0000",
      "dync_params" : {
        "param1" : "参数1",
        "param2" : "参数2",
        "param3" : "参数3",
        "param4" : "参数4"
      },
      "custom_url" : "https://www.example.com",
      "sms_params" : [ "参数1", "参数2" ]
    }, {
      "cust_flag" : "131****0001",
      "dync_params" : {
        "param1" : "参数1",
        "param2" : "参数2",
        "param3" : "参数3",
        "param4" : "参数4"
      },
      "custom_url" : "https://www.example.com",
      "sms_params" : [ "参数1", "参数2" ]
    } ]
  }
}

响应示例

状态码： 200

返回200状态码仅代表接口请求成功，任务提交结果由task_state字段来区分，此结果仅代表任务提交结果，并非智能信息发送结果。用户手机接收智能信息结果请以收到的回执结果为准，也可通过查询智能信息发送明细API获取或登录KooMessage控制台查看。

{
  "task_name" : "智能信息发送",
  "sms_channel" : {
    "channel_number" : "8822053111111",
    "sms_tpl_id" : 15010661,
    "sms_sign" : "华为云KooMessage",
    "sms_app_name" : "KooMessage"
  },
  "resolve_task" : {
    "tpl_id" : "600000001",
    "resolve_times" : 1,
    "aim_code_type" : "individual",
    "domain" : null,
    "expiration_time" : 7,
    "generation_type" : "1",
    "params" : [ {
      "cust_flag" : "131****0000",
      "dync_params" : null,
      "custom_url" : "https://www.example.com",
      "custom_short_code" : null,
      "sms_params" : [ ]
    } ]
  },
  "task_id" : "c3d7659d-06b0-4fa0-9eed-9225389ecccc",
  "task_state" : "Success",
  "creation_time" : "2022-07-19T14:37:34.00Z",
  "submission_count" : 1,
  "send_count" : 1,
  "resolve_count" : 0,
  "failed_short_chains" : [ ]
}

状态码

状态码	描述
200	返回200状态码仅代表接口请求成功，任务提交结果由task_state字段来区分，此结果仅代表任务提交结果，并非智能信息发送结果。用户手机接收智能信息结果请以收到的回执结果为准，也可通过查询智能信息发送明细API获取或登录KooMessage控制台查看。
400	非法参数。
500	内部错误。