注册送短信

API: aim/template - 创建模板


概览


aim/template 是 SUBMAIL AIM阅信的模板创建 API。



URL


https://api-v4.mysubmail.com/aim/template


接口响应数据格式


格式URL
jsonhttps://api-v4.mysubmail.com/aim/template.json(默认)


http 请求方式


请求方式content-type设置
postmultipart/form-data、x-www-form-urlencoded、application/json


是否需要授权


参阅 API 授权和验证机制


请求参数


参数类型必需/可选默认描述
appidstring必需在 SUBMAIL 应用集成中创建的短信应用ID
cardIdstring必需版式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/> 具体模板样式和配置要求见【模板配置说明】
tplNamestrng必需模板名称,不能超过20个字符
参数示例:双十一活动促销
scenestring必需使用场景,不能超过10个字符<br/>参数示例:活动促销
useIdint必需1: 正式模板<br/>2: 测试模板<br/> 注:测试模板在终端厂商审核环节要求相对比较宽松,但是测试模板必须在标题/正文中携带“测试”两字
subTypeint可选1当版式ID为 com.hbm.notification 通知类时:<br/>1. 增强通知 <br/>2. 一般通知 <br/>当版式ID为 com.hbm.trip 行程类时:<br/>1. 飞机票 <br/>2. 火车票 <br/>3. 汽车票<br/> 其他版式可不填
factorysjson array可选需要提交的厂商列表:<br/>指定模板提交的厂商,不填则由运营人员选择提交的厂商。<br/>模板支持厂商列表:<br/>HuaWei 表示华为厂商<br/>XiaoMi 表示小米厂商<br/>OPPO 表示OPPO厂商<br/>VIVO 表示VIVO厂商<br/> 注:<br/>1. 参数区分大小写 <br/>2. 如填写,请注意cardId、actionType是否支持所填厂商,否则接口报错/无法通过厂商模板审核
smsExamplestring必需所要发送的短信原文的示例,用于模版审核时使用,最大150个字符。
pagesjson array必需消息内容,最大支持10页消息内容,数据结构见下方 pages 说明
paramsjson array可选模板动参,最大可创建20个动参,动参数据结构见下方 params 说明<br/> pages.contents 中使用动态参数,在文本/链接中插入参数,参数名称需跟 params 中的 name 保持一致。<br/>申请短链接接口中,如果是生成个性化短链接,paramList.dyncParamskey需和 params 中的 name 保持一致。
smsSignsjson array可选短信签名,最多可以填写三个,发送时,只要匹配了其中一个即可<br/> 每个签名最多20个字,支持中文、英文、数字、符号,不支持【】符号,如果模板要发送 VIVO,则此参数必填,否则模板无法通过审核
smsTemplatestring可选短信原文模板<br/> 正则类型仅支持文本、字母、数字三种,且长度最大为99,切中括号为英文中括号。静态短信文案加正则动态文案最大值的总字数不超过370个字符<br/>如果要下发 VIVO,则此参数必填,否则模板无法通过审核
timestampint可选UNIX 时间戳,参阅 API 授权与验证机制 > timestamp
signTypestring可选normalAPI 授权模式( md5 or sha1 or normal
参阅 API 授权与验证机制 > 授权和验证方式
signaturestring必需应用密匙或数字签名
参阅 API授权与验证机制 > 授权和验证方式。当signType等于normalsignature应传appkey的值。



params 数据结构

参数类型必需/可选默认值描述
typeint必需动态参数类型,可选值
1. 表示文本类型
namestring必需动态参数名称<br/> 命名规范:${paramN},N=1,2,3... 参数名称保证唯一,不能重复。
examplestring必需动态参数示例,不能大于100个字符



pages 数据结构

参数类型必需/可选默认值描述
contentsarray必需该 page下的协议内容,内容参数见下方 content 说明



contents 数据结构

参数类型必需/可选默认值描述
typestring必需资源类型,可选参数如下:
text 表示文本<br/>image 表示图片<br/>video 表示视频<br/>button 表示按钮<br/>参数示例:text
contentstring条件可选当资料类型为 textbutton 时,该参数必填,文本长度限制请阅读模板版式标准。
srcTypeint条件可选资源类型为 imagevideo 时,该参数必填,可选参数:<br/>1 资源ID
srcstring条件可选素材的 fodder_id
coverstring条件可选资源类型为 video时,该参数必填,填写图片素材的 fodder_id
isTextTitlebool可选false是否为文本标题,可选参数:<br/>true 是 <br/>false 不是
actionTypestring条件可选资源类型为 imagebutton 时,该参数必填,必需绑定事件,其他类型的 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支持配置的事件列表见【阅信模板各版式报文示例】
actionjson必填根据 actionType 设置对应的信息,参照 action 数据结构
positionNumberint必填资源在卡片上相对的位置序号,按照优先从左到右,再从上到下的编排原则,统一编号
visibleint可选1是否可以见,0:不可见,1:可见,默认可见

action 数据结构

1、OPEN_URL(跳转H5)的数据结构

厂商华为小米OPPOVIVO
是否支持此事件
参数类型必需/可选默认值描述
targetstring必填H5访问地址,必需为https,支持动参,最大不能超过3000个字符<br/>参数示例:https://${param1}<br/> 注:建议如果链接包含动参,协议后的整个链接作为参数,否则链接封装可能会失效,导致审核不通过
merchantNamestring必填用于跳转时提示“正在跳转到xxx(商户名称)”<br/>不能超过20个字符<br/>参数示例:正在跳转到人工客服

2、OPEN_QUICK(跳转快应用)的数据结构

厂商华为小米OPPOVIVO
是否支持此事件
参数类型必需/可选默认值描述
targetstring必填快应用deeplink地址 ,支持含动态参数,不能超过3000个字符<br/>参数示例:hap://app/xxx/${param1}
merchantNamestring必填用于跳转时提示“正在跳转到xxx(商户名称)”<br/>不能超过20个字符<br/>参数示例:xx应用

3、OPEN_APP(跳转App)的数据结构

厂商华为小米OPPOVIVO
是否支持此事件
参数类型必需/可选默认值描述
targetstring必填APP的deeplink地址 ,支持含动态参数,不能超过3000个字符<br/>参数示例:weixin://
merchantNamestring必填用于跳转时提示“正在跳转到xxx(商户名称)”<br/>不能超过20个字符<br/>参数示例:xx应用
packageNamearray必填包名,不能超过50个字符<br/>参数示例:xx.xx.xx
floorTypeint可选0兜底类型:<br/>0:打开应用市场<br/>1:打开H5<br/>2:打开浏览器<br/>3:打开快应用<br/>不填时,默认为0:打开应用市场
floorUrlstring可选支持快应用deeplink或H5的HTTPS网址,不能超过3000个字符<br/> 注:兜底类型为0:打开应用市场,可不填

4、DIAL_PHONE(拉起拨号盘)的数据结构

厂商华为小米OPPOVIVO
是否支持此事件
参数类型必需/可选默认值描述
targetstring必填电话号码,不能超过20位<br/>参数示例:18666668888

5、OPEN_SMS(新建短信息)的数据结构

厂商华为小米OPPOVIVO
知否支持此事件
参数类型必需/可选默认值描述
targetstring必填电话号码,不能超过20位<br/>参数示例:18666668888
bodystring必填短信正文,不能超过100个字符<br/>参数示例:今天回家吃饭吗

6、OPEN_EMAIL(打开邮箱)的数据结构

厂商华为小米OPPOVIVO
是否支持此事件
参数类型必需/可选默认值描述
targetstring必填邮箱地址,不能超过100个字符<br/>参数示例:service@mysubmail.com
subjectstring必填邮件标题,不能超过100个字符<br/>参数示例:618活动促销
bodystring必填邮件正文,不能超过500个字符<br/>参数示例:您有一张优惠券领取

7、OPEN_SCHEDULE(新建日程)的数据结构

厂商华为小米OPPOVIVO
是否支持此事件
参数类型必需/可选默认值描述
targetstring必填日程标题,不能超过100个字符<br/>参数示例:日常需求评审
descriptionstring必填日程内容描述,不能超过100个字符<br/>参数示例:评审这个月版本需求
beginTimestring必填日程开始时间,格式为yyyy-MM-dd HH:mm:ss
endTimestring必填日程结束时间,格式为yyyy-MM-dd HH:mm:ss

8、OPEN_BROWSER(打开浏览器)的数据结构

厂商华为小米OPPOVIVO
是否支持此事件
参数类型必需/可选默认值描述
targetstring必填网址,支持HTTPS或HTTP,支持含动态参数,不能超过3000个字符<br/>参数示例:https://${param1}<br/> 注:建议如果链接包含动参,协议后的整个链接作为参数,否则链接封装可能会失效,导致审核不通过
merchantNamestring必填用于跳转时提示“正在跳转到xxx(商户名称)”<br/>不能超过20个字符<br/>参数示例:人工客服

9、OPEN_POPUP(弹窗)的数据结构

厂商华为小米OPPOVIVO
是否支持此事件
参数类型必需/可选默认值描述
targetstring必填弹窗标题,不能超过30个字符<br/>参数示例:xxx商品
contentstring必填弹窗内容,不能超过100个字符<br/>参数示例:是否喜欢该商品
textButtonstring必填按钮展示文本,不能超过12个字符<br/>参数示例:确定
modeint必填弹窗模态:<br/>0:模态(默认) <br/>1:非模态(暂不支持)

10、COPY_PARAMETER(复制)的数据结构

厂商华为小米OPPOVIVO
是否支持此事件
参数类型必需/可选默认值描述
targetstring必填复制的内容,支持含动态参数,不能超过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"  //失败信息描述
}