互亿无线 · 文档中心

彩信营销 - API文档


彩信营销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 如:2RYN7CQHL1M*****
signature string 请求验证加密签名(非彩信签名);
签名生成方式:
仅公共参数以ASCII码从小到大排序值,key=value,多值以"&"隔开,拼接之后md5 32位小写; 如:md5(api_id=xxxx&api_key=xxxx&request_id=xxxx&timestamp=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<String> 手机号数组(最多1万个号码)如:["18800000000","18800000001"]
sign_name string 是/否 彩信签名(template_id未填写则必填)
title string 是/否 彩信标题(template_id未填写则必填)
content array<[][]DataItem> 是/否 彩信内容和模板ID必须传入1个;当彩信内容和模板ID都传入时,传入内容生效,模板ID属性失效 彩信元素DataItem结构:(具体参照文档9.01)
参数 类型 描述
con_type int 内容类型
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> 多个数组方式返回
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内容"}]]

服务热线:
400 880 8898
021-51698929