视频短信接口文档 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 }

视频短信接口文档 V1.0

1. 准备工作

1.1 获取接口授权

接口地址

请求方式

请求参数

返回结果

请求示例

响应示例

2. 全局说明

2.1 接口响应对象

2.2 消息状态

2.3 模板状态

3.视频短信

3.1 请求创建视频短信模板

接口地址

请求方式

请求body

返回结果

请求示例

静态模板

文本+图片 动态模板

响应示例

3.2 查询模板状态

接口地址

请求方式

请求参数

返回结果

请求示例

响应示例

3.3 接收模板状态变更报告

请求方式

请求参数

请求示例

返回示例

4.1 请求发送视频短信

接口地址

请求方式

请求body

返回结果

请求示例

响应示例

4.2 查询消息发送结果

接口地址

请求方式

请求参数

返回结果

请求示例

响应示例

4.3 接收消息状态报告

请求方式

请求参数

请求示例

返回示例

文本+图片动态模板