# 发送智能信息 #### 功能介绍 根据客户的参数发送任务名称、智能信息模板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 | 短链生成配置。 | 表3SmsChannel | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | 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-管理控制台-短信配置-短信模板管理-所属应用"中获取。 | 表4CreateAIMSendResolve | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | 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个短链。 | 表5CreateSendResolveTaskParam | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | cust_flag | 是 | String | 创建解析任务时填写用户唯一标识，手机号码或者任何的唯一标识，唯一标识不超过64个字符。 发送智能信息时则必须填客户的手机号码。样例为：130\*\*\*\*0001。 最大长度：**64** | | dync_params | 否 | Map\ | 智能信息模板动态参数。 说明： 使用动态参数模板时，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 | 短链生成失败列表。 | 表7SmsChannel | 参数 | 参数类型 | 描述 | |:---|:---|:---| | 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-管理控制台-短信配置-短信模板管理-所属应用"中获取。 | 表8CreateAIMTaskResolveResult | 参数 | 参数类型 | 描述 | |:---|:---|:---| | 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个短链。 | 表9CreateSendResolveTaskParam | 参数 | 参数类型 | 描述 | |:---|:---|:---| | cust_flag | String | 创建解析任务时填写用户唯一标识，手机号码或者任何的唯一标识，唯一标识不超过64个字符。 发送智能信息时则必须填客户的手机号码。样例为：130\*\*\*\*0001。 最大长度：**64** | | dync_params | Map\ | 智能信息模板动态参数。 说明： 使用动态参数模板时，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地址，请申请模板时选择变量属性为"金额"。 | 表10CreateResolveTaskResultParam | 参数 | 参数类型 | 描述 | |:---|:---|:---| | cust_flag | String | 创建解析任务时填写用户唯一标识，手机号码或者任何的唯一标识，唯一标识不超过64个字符。 发送智能信息时则必须填客户的手机号码。样例为：130\*\*\*\*0001。 | | cust_id | String | 租户ID。 | | dync_params | Map\ | 动态参数。 | | 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 | 内部错误。 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-koomessage/ErrorCode.html)。