视频短信接口文档 V1.0
1. 准备工作
1.1 获取接口授权
使用分配的商户帐号登录平台,进入开发者中心-客户端管理,新增客户端,填写回调地址及ip白名单。添加成功后可获得client_id
以及client_secret。注意,客户端的回调地址为平台所有回调场景回调商户系统的地址,填写回调地址时请不要携带参数。每个业务
回调场景的回调完整路径,会在具体回调接口中有说明。请对接方按照文档要求进行接口开发。
使用获得的client_id,client_secret获取授权访问token。此后所有的请求均需将token放入请求header中,header名为token,
值为通过此接口获得的token。token具有时效性,默认过期时间为72小时,客户端需自行缓存token及token有效期,并在token即
将过期时(过期前三十分钟内),重新调用接口获取新的token。
接口地址
http://baseurl/oauth/token
请求方式
post
请求参数
参数名 |
说明 |
必填 |
类型 |
client_id |
客户端id |
Y |
string |
client_secret |
客户端密钥 |
Y |
string |
scope |
授权范围,固定传 videomessage |
Y |
string |
grant_type |
授权方式,固定传 client_credentials |
Y |
string |
返回结果
参数名 |
说明 |
access_token |
授权token |
token_type |
token类型 |
scope |
授权范围 |
expires_in |
token 有效期,单位为秒,临近过期时需要重新获取token |
请求示例
http://127.0.0.1:9500/oauth/token?client_id=03af3e956d224b03b4499946d479a&
client_secret=7437f92a94ae6b5459ce2d4ae1132&scope=sms5g
&grant_type=client_credentials
响应示例
{
"access_token": "22a518db-6446-4200-af5e-48414597ab63",
"token_type": "bearer",
"expires_in": 43199,
"scope": "videomessage"
}
2. 全局说明
2.1 接口响应对象
平台所有业务接口统一返回对象为json格式的CommonResponse,其结构如下:
{
"returnCode": 200,
"returnMessage": "success",
"data": {},
"success": true
}
字段具体说明如下:
参数名 |
说明 |
必填 |
类型 |
returnCode |
返回码,200表示成功,其他为具体错误码 |
Y |
int |
returnMessage |
返回提示信息,当请求失败时返回错误提示 |
Y |
string |
data |
具体业务数据 |
Y |
object |
success |
请求是否成功 |
Y |
boolean |
后续文档对于返回值的说明,只对data的具体内容进行说明,不再对Commonresponse赘述
2.2 消息状态
状态值 |
状态描述 |
0 |
发送成功 |
1 |
发送失败 |
2 |
提交成功,待平台审核 |
3 |
平台审核不通过,发送失败 |
11 |
平台已处理,发送中(针对一次消息发送请求内单个手机号的发送状态) |
12 |
平台已处理,发送中(针对一次请求,对该次请求的状态描述) |
2.3 模板状态
状态值 |
状态描述 |
0 |
正常使用 |
1 |
审核中 |
2 |
审核不通过 |
3 |
模板已禁用 |
4 |
模板不存在 |
5 |
模板已过期 |
3.视频短信
视频短信消息体内可以包含多帧,每帧内内容可以最多包含1段文本+1个文件资源,图片、音频以及视频可以为Url或者BASE64编码。
目前的资源类型只支持:文本(txt),GIF图片(gif),JPG图片(jpg),PNG图片(png),BMP图片(bmp),MP3音频(mp3),MIDI音频(midi),
WAV音频(wav),MP4视频(mp4),3gp视频(3gp)
视频短信标题(title)加上base64解码后视频短信内容(content)总长度不能超过2000K
发送视频短信之前需要先创建模板,待模板审核通过后方可使用模板进行消息发送。模板分为静态模板和动态模板,静态模板一经创建,内容固定;
动态模板支持模板变量,变量具体的值在调用发送消息接口时再提交。
动态模板支持文本和图片内容作为模板变量,模板变量格式为{{您的变量名}},同一个模板变量名称在模板内只允许出现一次;当模板变量对应的
内容为图片时,则该文件资源的content不能包含模板变量之外的字符。例:图片的地址变量为{{imagevar1}},则
提交的数据中该图片的content只能为{{imagevar1}},不能为http://{{imagevar1}}.
第一帧的第一个文本消息必须以商户的签名为开始字符,即 第一帧的文本内容必须为【你的短信签名】你的短信内容
3.1 请求创建视频短信模板
接口地址
http://baseurl/api/v1/videomessage/template
请求方式
post
请求body
ThirdApiVideoMessageRequestDto(视频短信消息请求对象)
参数名 |
说明 |
必填 |
类型 |
merchantNo |
商户号 |
Y |
string |
title |
视频短信标题 |
Y |
string |
name |
模板名称 |
Y |
string |
custTemplateNo |
商户系统模板编号 |
Y |
string |
expire |
模板有效期,单位为天 |
Y |
int |
type |
模板类型,0为静态模板 1为动态模板 |
Y |
int |
remarks |
模板备注 |
N |
string |
customData |
商家自定义数据,该数据在响应中会原样返回 |
N |
string |
contents |
消息对象,为VideoMessageContentDto 集合 |
Y |
list |
VideoMessageContentDto(视频短信帧对象)
参数名 |
说明 |
必填 |
类型 |
sort |
帧的顺序,越小越靠前展示 |
Y |
long |
frames |
帧内容对象,为VideoMessageFrameDto 集合 |
Y |
list |
VideoMessageContentDto(视频短信帧对象)
参数名 |
说明 |
必填 |
类型 |
type |
资源类型,可以为txt,gif,jpg,png,bmp,mp3,midi,wav,mp4,3gp |
Y |
string |
content |
资源内容,当资源类型为文本时,content为文本的值;当资源类型为图片/音频/视频时,若source为url,则content为该资源的url地址;若source为base64,则content为该文件base64字符串 content支持变量占位符,变量格式为{{变量名}},当type为文本时,允许出现多个不重复的变量名;当type为文件时,content不允许出现变量占位符之外的字符 |
Y |
string |
name |
资源内容,当资源类型不为txt时,资源内容为文件的base64值 |
Y |
string |
source |
资源来源,当资源类型为文本时,source为txt;当资源类型为图片/音频/视频时,source可以为url或者base64,分别表示提交的资源文件从url获取/从base64流获取 |
Y |
string |
sort |
资源顺序,越小越靠前 |
Y |
int |
返回结果
data(ThirdApiResponseData)
参数名 |
说明 |
templateNo |
模板编号,后续发送消息时需要使用此编号 |
auditStatus |
模板状态 |
custTemplateNo |
商户系统模板编号 |
customData |
同请求时传入的customData |
请求示例
静态模板
{
"contents": [
{
"frames": [
{
"content": "这是个文本消息,这个消息结束了",
"name": "1.txt",
"sort": 0,
"source": "txt",
"type": "txt"
},
{
"content": "https://www.baidu.com/img/PCfb_5bf082d29588c07f842ccde3f97243ea.png",
"name": "1.jpg",
"sort": 1,
"source": "url",
"type": "jpg"
}
],
"sort": 0
}
],
"custTemplateNo": "202107221171132522",
"expire": 0,
"merchantNo": "1778686954",
"name": "静态模板",
"remarks": "测试静态模板",
"title": "API静态模板",
"type": 1,
"customData":"这是自定义数据"
}
文本+图片 动态模板
{
"contents": [
{
"frames": [
{
"content": "【XX科技】测试您好!尊敬的{{name}},欢迎关注XXX有限公司,现诚邀您于{{date}}来我司参加{{job}}面试!",
"name": "1.txt",
"sort": 0,
"source": "txt",
"type": "txt"
},
{
"content": "{{imagevar1}}",
"name": "1.jpg",
"sort": 1,
"source": "base64",
"type": "jpg"
}
],
"sort": 0
}
],
"custTemplateNo": "20210722117141112",
"expire": 0,
"merchantNo": "1778686954",
"name": "测试-XX面试邀请模板",
"remarks": "测试-XX面试邀请模板,请审核通过",
"title": "测试-XX有限公司面试邀请",
"type": 1,
"customData": "这是自定义数据"
}
响应示例
{
"returnCode": 200,
"returnMessage": "success",
"data": {
"templateNo": "202107221710570444",
"auditStatus": 1,
"custTemplateNo": "202107221171132522",
"customData": "这是自定义数据"
},
"success": true
}
3.2 查询模板状态
接口地址
http://baseurl/api/v1/videomessage/template/status
请求方式
get
请求参数
参数名 |
说明 |
必填 |
类型 |
merchantNo |
商户号 |
Y |
string |
templateNo |
创建模板时返回的模板编号 |
Y |
string |
返回结果
data
参数名 |
说明 |
templateNo |
模板编号 |
custTemplateNo |
商户系统模板编号 |
auditStatus |
模板状态,参考2.3 |
customData |
创建该模板时传入的customData |
请求示例
http://127.0.0.1:9500/api/v1/videomessage/template/status?templateNo=202107221710570444&merchantNo=1778686954
响应示例
{
"returnCode": 200,
"returnMessage": "success",
"data": {
"templateNo": "202107221710570444",
"auditStatus": 0,
"custTemplateNo": "202107221171132522",
"customData": "这是自定义数据"
},
"success": true
}
3.3 接收模板状态变更报告
此接口为平台回调商家系统,完整地址为商户在开发者中心-客户端管理中配置的回调地址/videomessage/callback/template/status;例如客户端配置的地址是http://127.0.0.1/api,则完整的回调地址为http://127.0.0.1/api/videomessage/callback/template/status,所以在配置客户端回调地址时,请勿在地址内携带参数
请求方式
post
请求参数
参数名 |
说明 |
必填 |
templateNo |
模板编号 |
Y |
auditStatus |
模板状态,参考2.3 |
Y |
custTemplateNo |
商户系统模板号 |
N |
customData |
创建该模板时提交的customData |
N |
请求示例
http://callbackurl/videomessage/callback/template/status?templateNo=202107221171132522&auditStatus=0&custTemplateNo=202107023218237134349944&customData=ddddddd
返回示例
{
"returnCode": 200,
"returnMessage": "success",
"data": {},
"success": true
}
4.1 请求发送视频短信
接口地址
http://baseurl/api/v1/videomessage
请求方式
post
请求body
ThirdApiVideoMessageRequestDto(视频短信消息请求对象)
参数名 |
说明 |
必填 |
类型 |
merchantNo |
商户号 |
Y |
string |
templateNo |
模板编号 |
Y |
string |
phoneNumbers |
接收消息的手机号集合,最多为2000个 |
Y |
list |
customData |
商家自定义数据,该数据在响应中会原样返回 |
N |
string |
paramsValues |
变量参数值对象(ParamValuesDto) |
Y |
list |
ParamValuesDto (变量参数键值对对象)
参数名 |
说明 |
必填 |
类型 |
paramName |
模板中的参数名,不带{{}},比如模板中是{{name}},则paramName为 name |
Y |
string |
content |
参数的实际值 |
Y |
string |
返回结果
data(ThirdApiResponseData)
参数名 |
说明 |
messageId |
消息id,后续对于此消息的操作,都以此消息id作为基础 |
status |
消息状态 |
msg |
状态说明 |
customData |
同请求时传入的customData |
请求示例
{
"customData": "customData",
"expire": 24,
"merchantNo": "1778686954",
"paramsValues": [
{
"content": "AA先生",
"paramName": "name"
},
{
"content": "2021-07-26 15:00",
"paramName": "date"
},
{
"content": "移动开发工程师",
"paramName": "job"
},
{
"content": "图片的base64",
"paramName": "imagevar1"
}
],
"phoneNumbers": [
"187xxxxxxxxx"
],
"templateNo": "20210730789388774"
}
响应示例
{
"returnCode": 200,
"returnMessage": "success",
"data": {
"messageId": "202107051816115676211730",
"status": 12,
"msg": "已处理",
"customData": "customData"
},
"success": true
}
4.2 查询消息发送结果
接口地址
http://baseurl/api/v1/videomessage/status
请求方式
get
请求参数
参数名 |
说明 |
必填 |
类型 |
merchantNo |
商户号 |
Y |
string |
messageId |
消息id |
Y |
string |
phone |
接收消息的手机号,非必填,当手机号不为空时,返回向该手机号发送该消息的结果,当手机号为空时,返回该消息针对所有手机号的发送结果 |
N |
string |
返回结果
data(ThirdApiVideoMessageStatusResponseModel)
参数名 |
说明 |
messageId |
查询的消息id |
result |
发送结果, 1为发送失败,12为已处理。失败表示该次消息向所有手机号发送消息失败,且statusResponseModels 不返回数据;12表示提交运运营商处理,每个手机号的消息状态需根据 statusResponseModels 内状态判断 |
statusResponseModels |
该消息发送至每个手机的状态,为 ThirdApiVideoMessagePhoneStatusResponseModel 列表,当result为0时,不返回每个手机号的消息发送状态,即,此字段为空集合 |
customData |
同请求时传入的customData |
ThirdApiVideoMessagePhoneStatusResponseModel(每个手机号接收消息的状态)
参数名 |
说明 |
result |
发送结果,0为成功,1失败,11为发送中,等待运营商确认状态 |
phone |
手机号 |
receiveTime |
接收时间 |
请求示例
http://127.0.0.1:9500/api/v1/videomessage/status?messageId=202107023218237134349944&merchantNo=1216312518&phone=18780100001
响应示例
{
"returnCode": 200,
"returnMessage": "success",
"data": {
"messageId": "202107023218237134349944",
"result": 12,
"customData": "customData",
"statusResponseModels": [
{
"result": 0,
"phone": "187xxxxxxxx",
"receiveTime": 1625219055069
}
]
},
"success": true
}
4.3 接收消息状态报告
此接口为平台回调商家系统,完整地址为商户在开发者中心-客户端管理中配置的回调地址/videomessage/callback/result;例如客户端配置的地址是http://127.0.0.1/api,则完整的回调地址为http://127.0.0.1/api/videomessage/callback/result,所以在配置客户端回调地址时,请勿在地址内携带参数
请求方式
post
请求参数
参数名 |
说明 |
必填 |
messageId |
消息id |
Y |
result |
发送结果,0为成功,1失败 |
Y |
phone |
手机号,当手机号为空时,result标识该次消息向所有手机号发送结果,当手机号不为空时,标识该次消息向该手机号发送结果 |
N |
receiveTime |
该手机号接收消息的时间 |
N |
请求示例
http://callbackurl?messageId=11111&result=0&phone=18780100001&receiveTime=1625478194854
返回示例
{
"returnCode": 200,
"returnMessage": "success",
"data": {},
"success": true
}