API: aim/template - 创建模板
概览
aim/template
是 SUBMAIL AIM阅信的模板创建 API。
URL
https://api-v4.mysubmail.com/aim/template
接口响应数据格式
格式 | URL |
---|
json | https://api-v4.mysubmail.com/aim/template.json (默认) |
http 请求方式
请求方式 | content-type设置 |
---|
post | multipart/form-data、x-www-form-urlencoded、application/json |
是否需要授权
是
请求参数
参数 | 类型 | 必需/可选 | 默认 | 描述 |
---|
appid | string | 必需 | 无 | 在 SUBMAIL 应用集成中创建的短信应用ID |
cardId | string | 必需 | 无 | 版式ID,可选参数如下: 1. com.hbm.video 视频类<br/>2. com.hbm.imageandtext 图文类<br/>3. com.hbm.standardimageandtext 多图文类<br/>4. com.hbm.videoimageandtext 视频图文<br/>5. com.hbm.videoimageandtext2 图文视频<br/>6. com.hbm.carouse 横滑类1<br/>7. com.hbm.carouseltitle 横滑类2<br/>7. com.hbm.carouseltitle 横滑类2<br/>8. com.hbm.carouselImageSixteenToNine 图片轮播类 16:9<br/>9. com.hbm.carouselQuareImage 图片轮播类 1:1<br/>10. com.hbm.carouselVerticalImage 图片轮播类 48:65<br/>11. com.hbm.pureText 长文本<br/>12. com.hbm.notification 通知类<br/>13. com.hbm.notificationplus 账单<br/>14. com.hbm.trip 行程类<br/>15. com.hbm.redpacket 红包类<br/>16. com.hbm.redpacketPersonal 个性化红包<br/>17. com.hbm.ecimageandtext 电商类<br/>18. com.hbm.ecommerce 多商品类<br/>19. com.hbm.cardVoucher 单卡券类<br/>20. com.hbm.cardVouchers 多卡券类<br/> 具体模板样式和配置要求见【模板配置说明】 |
tplName | strng | 必需 | 无 | 模板名称,不能超过20个字符 参数示例:双十一活动促销 |
scene | string | 必需 | 无 | 使用场景,不能超过10个字符<br/>参数示例:活动促销 |
useId | int | 必需 | 无 | 1: 正式模板<br/>2: 测试模板<br/> 注:测试模板在终端厂商审核环节要求相对比较宽松,但是测试模板必须在标题/正文中携带“测试”两字 |
subType | int | 可选 | 1 | 当版式ID为 com.hbm.notification 通知类时:<br/>1. 增强通知 <br/>2. 一般通知 <br/>当版式ID为 com.hbm.trip 行程类时:<br/>1. 飞机票 <br/>2. 火车票 <br/>3. 汽车票<br/> 其他版式可不填 |
factorys | json array | 可选 | 无 | 需要提交的厂商列表:<br/>指定模板提交的厂商,不填则由运营人员选择提交的厂商。<br/>模板支持厂商列表:<br/>HuaWei 表示华为厂商<br/>XiaoMi 表示小米厂商<br/>OPPO 表示OPPO厂商<br/>VIVO 表示VIVO厂商<br/> 注:<br/>1. 参数区分大小写 <br/>2. 如填写,请注意cardId、actionType是否支持所填厂商,否则接口报错/无法通过厂商模板审核 |
smsExample | string | 必需 | 无 | 所要发送的短信原文的示例,用于模版审核时使用,最大150个字符。 |
pages | json array | 必需 | 无 | 消息内容,最大支持10页消息内容,数据结构见下方 pages 说明 |
params | json array | 可选 | 无 | 模板动参,最大可创建20个动参,动参数据结构见下方 params 说明<br/> pages.contents 中使用动态参数,在文本/链接中插入参数,参数名称需跟 params 中的 name 保持一致。<br/>申请短链接接口中,如果是生成个性化短链接,paramList.dyncParams 的 key 需和 params 中的 name 保持一致。 |
smsSigns | json array | 可选 | 无 | 短信签名,最多可以填写三个,发送时,只要匹配了其中一个即可<br/> 每个签名最多20个字,支持中文、英文、数字、符号,不支持【】符号,如果模板要发送 VIVO,则此参数必填,否则模板无法通过审核 |
smsTemplate | string | 可选 | 无 | 短信原文模板<br/> 正则类型仅支持文本、字母、数字三种,且长度最大为99,切中括号为英文中括号。静态短信文案加正则动态文案最大值的总字数不超过370个字符<br/>如果要下发 VIVO,则此参数必填,否则模板无法通过审核 |
timestamp | int | 可选 | 无 | UNIX 时间戳,参阅 API 授权与验证机制 > timestamp |
signType | string | 可选 | normal | API 授权模式( md5 or sha1 or normal ) 参阅 API 授权与验证机制 > 授权和验证方式 |
signature | string | 必需 | 无 | 应用密匙或数字签名 参阅 API授权与验证机制 > 授权和验证方式。当signType 等于normal 时signature 应传appkey 的值。 |
params 数据结构
参数 | 类型 | 必需/可选 | 默认值 | 描述 |
---|
type | int | 必需 | 无 | 动态参数类型,可选值 1. 表示文本类型 |
name | string | 必需 | 无 | 动态参数名称<br/> 命名规范:${paramN},N=1,2,3... 参数名称保证唯一,不能重复。 |
example | string | 必需 | 无 | 动态参数示例,不能大于100个字符 |
pages 数据结构
参数 | 类型 | 必需/可选 | 默认值 | 描述 |
---|
contents | array | 必需 | 无 | 该 page下的协议内容,内容参数见下方 content 说明 |
contents 数据结构
参数 | 类型 | 必需/可选 | 默认值 | 描述 |
---|
type | string | 必需 | 无 | 资源类型,可选参数如下:
text 表示文本<br/>image 表示图片<br/>video 表示视频<br/>button 表示按钮<br/>参数示例:text |
content | string | 条件可选 | 无 | 当资料类型为 text 或 button 时,该参数必填,文本长度限制请阅读模板版式标准。 |
srcType | int | 条件可选 | 无 | 资源类型为 image 或 video 时,该参数必填,可选参数:<br/>1 资源ID |
src | string | 条件可选 | 无 | 素材的 fodder_id |
cover | string | 条件可选 | 无 | 资源类型为 video 时,该参数必填,填写图片素材的 fodder_id |
isTextTitle | bool | 可选 | false | 是否为文本标题,可选参数:<br/>true 是 <br/>false 不是 |
actionType | string | 条件可选 | 无 | 资源类型为 image 和 button 时,该参数必填,必需绑定事件,其他类型的 type 不需要填,可选参数:<br/>OPEN_URL 表示跳转H5<br/>OPEN_QUICK 表示跳转快应用<br/>OPEN_APP 表示跳转App<br/>DIAL_PHONE 表示拉起拨号盘<br/>OPEN_SMS 表示新建短信息<br/>OPEN_EMAIL 表示打开邮箱<br/>OPEN_SCHEDULE 表示新建日程<br/>OPEN_BROWSER 表示打开浏览器<br/>OPEN_POPUP 表示弹窗<br/>COPY_PARAMETER 表示复制<br/> 1、com.hbm.carouse 横滑类1,com.hbm.carouseltitle 横滑类2 版式的图片不支持绑定事件,默认与按钮事件一致 <br/>2、米 OV支持配置的事件列表见【阅信模板各版式报文示例】 |
action | json | 必填 | 无 | 根据 actionType 设置对应的信息,参照 action 数据结构 |
positionNumber | int | 必填 | 无 | 资源在卡片上相对的位置序号,按照优先从左到右,再从上到下的编排原则,统一编号 |
visible | int | 可选 | 1 | 是否可以见,0:不可见,1:可见,默认可见 |
action 数据结构
1、OPEN_URL(跳转H5)的数据结构
厂商 | 华为 | 小米 | OPPO | VIVO |
---|
是否支持此事件 | √ | √ | √ | √ |
参数 | 类型 | 必需/可选 | 默认值 | 描述 |
---|
target | string | 必填 | 无 | H5访问地址,必需为https,支持动参,最大不能超过3000个字符<br/>参数示例:https://${param1}<br/> 注:建议如果链接包含动参,协议后的整个链接作为参数,否则链接封装可能会失效,导致审核不通过 |
merchantName | string | 必填 | 无 | 用于跳转时提示“正在跳转到xxx(商户名称)”<br/>不能超过20个字符<br/>参数示例:正在跳转到人工客服 |
2、OPEN_QUICK(跳转快应用)的数据结构
厂商 | 华为 | 小米 | OPPO | VIVO |
---|
是否支持此事件 | √ | √ | √ | √ |
参数 | 类型 | 必需/可选 | 默认值 | 描述 |
---|
target | string | 必填 | 无 | 快应用deeplink地址 ,支持含动态参数,不能超过3000个字符<br/>参数示例:hap://app/xxx/${param1} |
merchantName | string | 必填 | 无 | 用于跳转时提示“正在跳转到xxx(商户名称)”<br/>不能超过20个字符<br/>参数示例:xx应用 |
3、OPEN_APP(跳转App)的数据结构
厂商 | 华为 | 小米 | OPPO | VIVO |
---|
是否支持此事件 | √ | √ | √ | √ |
参数 | 类型 | 必需/可选 | 默认值 | 描述 |
---|
target | string | 必填 | 无 | APP的deeplink地址 ,支持含动态参数,不能超过3000个字符<br/>参数示例:weixin:// |
merchantName | string | 必填 | 无 | 用于跳转时提示“正在跳转到xxx(商户名称)”<br/>不能超过20个字符<br/>参数示例:xx应用 |
packageName | array | 必填 | 无 | 包名,不能超过50个字符<br/>参数示例:xx.xx.xx |
floorType | int | 可选 | 0 | 兜底类型:<br/>0:打开应用市场<br/>1:打开H5<br/>2:打开浏览器<br/>3:打开快应用<br/>不填时,默认为0:打开应用市场 |
floorUrl | string | 可选 | 无 | 支持快应用deeplink或H5的HTTPS网址,不能超过3000个字符<br/> 注:兜底类型为0:打开应用市场,可不填 |
4、DIAL_PHONE(拉起拨号盘)的数据结构
参数 | 类型 | 必需/可选 | 默认值 | 描述 |
---|
target | string | 必填 | 无 | 电话号码,不能超过20位<br/>参数示例:18666668888 |
5、OPEN_SMS(新建短信息)的数据结构
参数 | 类型 | 必需/可选 | 默认值 | 描述 |
---|
target | string | 必填 | 无 | 电话号码,不能超过20位<br/>参数示例:18666668888 |
body | string | 必填 | 无 | 短信正文,不能超过100个字符<br/>参数示例:今天回家吃饭吗 |
6、OPEN_EMAIL(打开邮箱)的数据结构
参数 | 类型 | 必需/可选 | 默认值 | 描述 |
---|
target | string | 必填 | 无 | 邮箱地址,不能超过100个字符<br/>参数示例:service@mysubmail.com |
subject | string | 必填 | 无 | 邮件标题,不能超过100个字符<br/>参数示例:618活动促销 |
body | string | 必填 | 无 | 邮件正文,不能超过500个字符<br/>参数示例:您有一张优惠券领取 |
7、OPEN_SCHEDULE(新建日程)的数据结构
参数 | 类型 | 必需/可选 | 默认值 | 描述 |
---|
target | string | 必填 | 无 | 日程标题,不能超过100个字符<br/>参数示例:日常需求评审 |
description | string | 必填 | 无 | 日程内容描述,不能超过100个字符<br/>参数示例:评审这个月版本需求 |
beginTime | string | 必填 | 无 | 日程开始时间,格式为yyyy-MM-dd HH:mm:ss |
endTime | string | 必填 | 无 | 日程结束时间,格式为yyyy-MM-dd HH:mm:ss |
8、OPEN_BROWSER(打开浏览器)的数据结构
厂商 | 华为 | 小米 | OPPO | VIVO |
---|
是否支持此事件 | √ | √ | √ | √ |
参数 | 类型 | 必需/可选 | 默认值 | 描述 |
---|
target | string | 必填 | 无 | 网址,支持HTTPS或HTTP,支持含动态参数,不能超过3000个字符<br/>参数示例:https://${param1}<br/> 注:建议如果链接包含动参,协议后的整个链接作为参数,否则链接封装可能会失效,导致审核不通过 |
merchantName | string | 必填 | 无 | 用于跳转时提示“正在跳转到xxx(商户名称)”<br/>不能超过20个字符<br/>参数示例:人工客服 |
9、OPEN_POPUP(弹窗)的数据结构
参数 | 类型 | 必需/可选 | 默认值 | 描述 |
---|
target | string | 必填 | 无 | 弹窗标题,不能超过30个字符<br/>参数示例:xxx商品 |
content | string | 必填 | 无 | 弹窗内容,不能超过100个字符<br/>参数示例:是否喜欢该商品 |
textButton | string | 必填 | 无 | 按钮展示文本,不能超过12个字符<br/>参数示例:确定 |
mode | int | 必填 | 无 | 弹窗模态:<br/>0:模态(默认) <br/>1:非模态(暂不支持) |
10、COPY_PARAMETER(复制)的数据结构
参数 | 类型 | 必需/可选 | 默认值 | 描述 |
---|
target | string | 必填 | 无 | 复制的内容,支持含动态参数,不能超过20个字符<br/>复制验证码示例:83721 |
代码示例
发送一封测试短信
POST URL
https://api-v4.mysubmail.com/aim/template
POST DATA
{
"appid":"your_app_id",
"signature":"your_app_key",
"cardId": "com.hbm.imageandtext",
"tplName": "图文模板测试",
"scene": "测试",
"useId": 2,
"smsExample": "图文模板测试",
"pages": [{
"contents": [{
"type": "image",
"src": "595787049043271680",
"srcType": 1,
"actionType": "OPEN_URL",
"action": {
"target": "https://www.baidu.com?app=123",
"merchantName": "京东"
},
"positionNumber": 1
},
{
"type": "text",
"content": "图文模板标题",
"isTextTitle": true,
"positionNumber": 2
},
{
"type": "text",
"content": "图文模板正文",
"isTextTitle": false,
"positionNumber": 3
},
{
"type": "button",
"content": "点击按钮",
"actionType": "DIAL_PHONE",
"action": {
"target": "18666826056"
},
"positionNumber": 4
}
]
}]
}
成功返回
{
"status": "success", //请求状态
"id": "ikJvMC", //模板ID
}
失败返回
{
"status":"error", //请求状态
"code":"1xx", //失败码
"msg":"error sms" //失败信息描述
}