互亿无线 · 文档中心

彩信/视频短信 - API文档


彩信营销接口文档 点击下载

彩信营销接口接入指南 点击访问

1.概要

1.1 文档说明

本文档主要提供给互亿平台的用户对接接口的使用说明,开发者可以利用 ihuyi 提供的 HTTP 接口,调用 ihuyi 的营销彩信服务。

1.2 接口内容

本文档包含彩信批量提交、余额查询、彩信模板提交、回执推送、上行推送、模板审核推送。

1.3 提交方式

POST

1.4 加密方式

1、采用HTTPS协议提交请求
2、通过MD5动态签名方式加密

1.5 api id / api key

登录用户中心,进入“营销彩信”模块,在产品概览页面右侧获取,如下图所示:

1.6 彩信模版

彩信模板是对您将要发送的彩信进行相似性提取后的内容。

注意:付费用户可以通过左侧导航【营销彩信-彩信发送】-【模版管理】新增彩信模板运营商审核通过之后即可正式使用。

1.7 彩信签名

彩信签名是在【】加上您的公司名称或店铺名称的标识符,例如:【互亿无线】。根据电信基础运营商的规定,每条彩信必须附加彩信签名,否则将无法正常发送。

2. 公共请求参数(json格式)

参数 类型 是否必填 说明
api_id string Api的ID 如:mms*******
signature string 请求验证加密签名(非彩信签名);
签名生成方式:
仅公共参数以ASCII码从小到大排序值,key=value,多值以"&"隔开,拼接之后md5 32位小写; 如:md5(api_id=xxxx&api_key=xxxx&request_id=xxxx×tamp=xxxxxxx)
timestamp int 东八时区;10位时间戳,时间允许相差±60S
golang: time.Now().Unix()
php: time()
request_id string 请求方请求ID,建议使用唯一ID,比如使用uuid;我方系统会2小时内去重验证处理,防止网络重复攻击;

3. 彩信批量提交接口

3.1 协议说明

协议类目 说明
请求方式 POST
编码格式 UTF-8
Content-Type application/json

3.2 请求地址

https://api.ihuyi.com/mms/v1/batchSend

3.3 请求参数(json格式,需要包含公共请求参数)

参数 类型 是否必填 说明
product_id int 产品ID,如:1001
phone Array 手机号数组(最多1万个号码)如:["18800000000","18800000001"]
sign_name string 是/否 彩信签名(template_id未填写则必填)
title string 是/否 彩信标题(template_id未填写则必填)
content array<[][]DataItem> 是/否 彩信内容和模板ID必须传入1个;当彩信内容和模板ID都传入时,传入内容生效,模板ID属性失效 彩信元素DataItem结构:(具体参照文档9.01)
参数 类型 描述
con_type string 内容类型
ext_type string 文件扩展名
data string 数据
template_id int 是/否 模板ID(内容为空则必填)
send_time string 定时发送时间 2020-08-26 16:08:14

3.4 返回参数(json格式)

参数 类型 说明
task_id string 下发批次ID,推送回执相关会用作关联
code string 状态码,OK表示发送成功,其他则是错误
message string 消息内容

4. 余额查询接口

4.1 请求地址

https://api.ihuyi.com/mms/v1/balance

4.2 返回参数(json格式)

参数 类型 说明
task_id string 下发批次ID,推送回执相关会用作关联
code string 状态码,OK表示发送成功,其他则是错误
message string 消息内容
data array 多个数组方式返回
DataItem结构:
参数 类型 描述
product_id int 产品ID
product_name string 产品名称
balance float 余额

示例:

{

    "code": "OK",

    "message": "请求成功",

    "data": [

        {

            "product_id": 1018,

            "product_name": "营销彩信-房产类",

            "balance": 188888

        },

        {

            "product_id": 1020,

            "product_name": "营销彩信-商超类",

            "balance": 200000

        }

    ]

}

5. 彩信模板提交接口

5.1 协议说明

协议类目 说明

请求方式

POST

编码格式

UTF-8

Content-Type

application/json

5.2 请求地址

https://api.ihuyi.com/mms/v1/templateCreate

5.3 请求参数(json格式,需要包含公共请求参数)

参数 类型 是否必填 说明
title string 模板标题(用于标识,不会出现在彩信内容中)
content array<[][]DataItem> 彩信元素内容DataItem结构:(具体参照文档9.01)
参数 类型 描述
con_type int 内容类型
ext_type string 文件扩展名
data string 数据
purpose string 应用场景描述
sign_name string 短信签名

5.4返回参数(json格式)

参数 类型 说明
template_id int 模板ID
code string 状态码,OK表示发送成功,其他则是错误
message string 消息内容

6. 回执推送

6.1 协议说明

协议类目 说明
调用方式 主动回调
请求方式 POST
编码格式 UTF-8
Content-Type application/json
数据格式 json

6.2 回执数据定义

参数 类型 说明
task_id string 下发批次ID
phone string 手机号码
code string 状态码,DELIVERED则是成功,其他则是失败
message string 返回消息,用户接收成功
send_time string 发送时间
report_time string 回执时间

响应说明:

成功接收请输出字符 “success” (不包含引号)结束推送,否则以接收失败处理。每个回执最多推送3次。每次间隔叠加60秒。

7. 上行推送

7.1 协议说明

协议类目 说明
调用方式 主动回调
请求方式 POST
编码格式 UTF-8
Content-Type application/json
数据格式 json

 

 

7.2 回执数据定义

参数 类型 说明
task_id string 下发批次ID
phone string 手机号码
content string 上行内容
dest_code string 上行通道扩展号
send_time string 发送时间
receive_time string 收取时间

响应说明:

成功接收请输出字符 “success” (不包含引号)结束推送,否则以接收失败处理。每个回执最多推送3次。每次间隔叠加60秒。

8. 模板审核推送

8.1 协议说明

协议类目 说明
调用方式 主动回调
请求方式 POST
编码格式 UTF-8
Content-Type application/json
数据格式 json

8.2 模板审核数据定义

参数 类型 说明
template_id int 模板ID
code string 状态值(SUCCESS审核通过,FAIL审核失败)
message string 审核消息

9. 参数示例说明

9.1 内容格式定义

1) 支持视频、图片、音频和文字,图片编码格式为二进制后base64,文字编码格式为utf-8;
2) 彩信由多帧组成,同一帧中元素最多允许一段文字和一种媒体文件(即同一帧中只允许展现视频、图片、音频中的一种媒体文件),多个媒体文件请分别放置在多帧中;
3) 内容类型(con_type)支持:text(文本)、image(图片)、audio(音频)、video(视频);
4) 文件扩展名(ext_type)支持:jpg、jpeg、png、gif、mp3、mp4。

内容格式json格式参考如下:

[[{"con_type":"text","ext_type":"txt","data":"这是测试文本内容1"},{"con_type":"image","ext_type":"jpg","data":"这是base64内容"}],[{"con_type":"text","ext_type":"txt","data":"这是测试文本内容2"},{"con_type":"video","ext_type":"mp4","data":"这是base64内容"}],[{"con_type":"image","ext_type":"jpg","data":"这是base64内容"},{"con_type":"text","ext_type":"txt","data":"这是测试文本内容3"}],[{"con_type":"audio","ext_type":"mp3","data":"test"},{"con_type":"text","ext_type":"txt","data":"这是base64内容"}]]

 

10.错误码查询

Code 说明
Success 请求成功
ParamError 参数错误
AccessKeyIDNotExist AccessKeyID不存在
UserIDNotExist 用户ID不存在
AmountError 数额错误(超出许可范围)
TimestampError 时间错误(超出许可范围)
ProductIDNotExist 产品ID不存在
TypeNotExist 类型不存在
RemarkError 备注错误
RequestIDExisted 请求ID已存在
NonceExisted 随机数已存在
SingError 签名错误
SignExpired 签名过期
BalanceNotEnough 余额不足
PackIDExisted 资源包ID已存在
SystemError 系统异常
InputDataInvalid 请求参数异常

现在注册,即享新用户礼包!

请输入验证码免费体验产品

收不到短信验证码?
×
服务热线:
4008 808 898