语音通知 - API文档

1、概要

1.1 文档说明

本文档主要提供给互亿平台的用户对接接口的使用说明，开发者可以利用 ihuyi 提供的 HTTP 接口，调用 ihuyi 的语音通知服务。

1.2 接口内容

本文档包含语音发送、余额查询、发送回执推送等。

1.3 提交方式

GET / POST

1.4 加密方式

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

1.5 API ID / API KEY

登录用户中心，进入【语音通知】模块，在【产品总揽】页面右上角，如下图所示：

1.6 语音模版

语音通知模板是对您将要发送的语音进行相似性提取后的内容。举个例子，

A 用户是您的老会员，即将过生日，需要发送一条语音短信，内容如下:

您的客户张茜将于 2 天后过生日，别忘记注意祝福哦~

同时，B 用户是您的老会员，即将过生日，发送了如下语音短信:

您的客户赵鑫将于 3 天后过生日，别忘记注意祝福哦~

我们提取相似度以后，可以制作以下语音模板:

您的客户【变量】将于 【变量】天后过生日，别忘记注意祝福哦~

其中，变量是可变的，可以是 数字、字母、汉字。

2、语音通知发送

2.1 接口描述

语音通知接口支持两种提交方式，用户可根据实际需求任选其一：

• 完整内容方式（推荐）：直接传递完整的语音内容进行发送。
• 模板变量方式：使用预设模板，通过模板ID和变量实现语音发送，更便捷且更安全。

请求支持 POST 和 GET 两种方法，数据格式统一为Content-Type: application/x-www-form-urlencoded ，字符编码为 utf-8。

2.2 请求地址

http://api.vm.ihuyi.com/webservice/voice.php?method=Submit

2.3 请求参数

参数名称	参数值描述	必填
account	APIID(用户中心【语音通知】-【产品总览】查看)	是
password	1、APIKEY(用户中心【语音通知】-【产品总览】查看) 2、动态密码(生成动态密码方式请看该文档末尾的说明)	是
mobile	支持中国内地手机号码及固话号码。 手机号：11位，示例：139****0000。 固话号码：{区号}{号码}，示例：02151****29。 接收手机号码，只能提交一个号码	是
templateid	语音模板ID（使用模板变量方式发送时必填） 调试阶段可使用系统默认模板ID：1361（模板内容为：您的订单号是：【变量】。已由【变量】发出，请注意查收。）	否（使用模板变量方式时为必填）
content	根据发送方式不同： 1、完整内容方式 提交完整的短信内容，如：您的订单号是：9633。已由顺风快递发出，请注意查收。 2、模板变量方式 模板中的变量内容，多个变量以英文竖线（|）隔开 ①单变量示例 模板内容：您的订单已发出，订单号：【变量】，请注意查收。 参数写法：content=1234 最终短信为：您的订单已发出，订单号：1234，请注意查收。 ②多变量示例 模板内容：订单号：【变量1】，联系人：【变量2】，手机号：【变量3】，金额：【变量4】。 参数写法：content=20180515006|张三|136xxxxxxxx|100元 最终短信为：订单号：20180515006，联系人：张三，手机号：136xxxxxxxx，金额：100元。	是
time	Unix时间戳（10位整型数字，当使用动态密码方式时为必填）	否
format	返回格式（可选值为：xml或json，系统默认为xml）	否

用户通过http 或 https提交发送短信请求到服务器后，服务器会返回一串xml格式的字符串，SubmitResult结构说明如下：

参数名称	类型	描述
code	int	返回值为2时，表示提交成功
voiceid	string	当提交成功后，此字段为流水号，否则为0
msg	string	提交结果描述

2.4 响应示例

示例（成功）

    2 提交成功 60495654 

示例（失败）

    405 account或password不正确 0 

2.5 响应参数

code	msg
0	提交失败
2	提交成功
400	非法ip访问
401	帐号不能为空
402	密码不能为空
403	手机号码不能为空
4030	手机号码已被列入黑名单
404	语音内容不能为空
405	用户名或密码不正确
4050	账号被冻结
40505	没有签定合同
4051	剩余条数不足
4052	访问 ip 与备案 ip 不符
406	手机格式不正确
407	短信内容含有敏感字符
4071	没有提交备案模板
4072	提交的语音内容必须与报备过的模板格式相匹配
40722	变量内容超过指定的长度
4077	发送内容未在运营商报备
408	您的帐户疑被恶意利用，已被自动冻结，如有疑问请与客服联系
4080	同一手机号码同一秒钟之内发送频率不能超过1条
4081	同一手机号一分钟之内发送超过3条
4082	超出同一手机号一天之内10条短信限制

2.6 GET 请求示例

（1）完整内容方式示例（推荐）：

http://api.vm.ihuyi.com/webservice/voice.php?method=Submit&account=APIID&password=APIKEY&mobile=手机号码&content=您的订单号是：0648。已由顺风快递发出，请注意查收。

（2）模板变量方式示例：

http://api.vm.ihuyi.com/webservice/voice.php?method=Submit&account=APIID&password=APIKEY&mobile=手机号码&content=0648

示例中使用默认模板（ID=1361），内容为：“您的订单号是：0648。已由顺风快递发出，请注意查收。”

如使用自定义模板，模板含多个变量时，content需以竖线 | 隔开，如下所示：

http://api.vm.ihuyi.com/webservice/voice.php?method=Submit&account=APIID&password=APIKEY&mobile=手机号码&templateid=144219&content=20180515006|张三|136xxxxxxxx|100元

请注意模板中变量与传入参数必须一一对应。

3、余额查询

3.1 接口描述

通过POST、 GET 方式查询你的账户语音通知剩余条数，内容格式为：Content-Type: application/x-www-form-urlencoded，数据编码采用utf-8格式。

3.2 请求地址

http://api.vm.ihuyi.com/webservice/voice.php?method=GetNum

3.3 请求参数

参数名称	参数值描述	是否必填
account	APIID(用户中心【语音通知】-【产品总览】查看)	是
password	1、APIKEY(用户中心【语音通知】-【产品总览】查看) 2、动态密码(生成动态密码方式请看该文档末尾的说明)	是
time	Unix时间戳（10位整型数字，当使用动态密码方式时为必填）	否
format	返回格式（可选值为：xml或json，系统默认为xml）	否

用户通过http 或 https提交帐户余额查询请求到服务器后，服务器会返回一串xml格式的字符串，GetNumResult结构说明如下：

参数名称	类型	描述
code	int	状态返回值
msg	string	查询结果描述
num	string	剩余数量

3.4 响应示例

示例（成功）

    2 查询成功 856 

示例（失败）

    405 account或password不正确 0 

3.5 响应参数

code	msg
2	查询成功
400	非法ip访问
401	帐号不能为空
402	密码不能为空
405	用户名或密码不正确
4050	账号被冻结

3.6 GET请求示例

http://api.vm.ihuyi.com/webservice/voice.php?method=GetNum&account=APIID&password=APIKEY

4、提交模板

4.1 接口描述

通过POST、 GET 方式提交语音通知模板，内容格式为：Content-Type: application/x-www-form-urlencoded，数据编码采用utf-8格式。

4.2 请求地址

http://api.vm.ihuyi.com/webservice/voice.php?method=AddTemplate&account=APIID&password=APIKEY&content=您的订单号是：【变量】。已由顺风快递发出，请注意查收。

4.3 请求参数

参数名称	参数值描述
method	AddTemplate
account	APIID(用户中心【语音通知】-【产品总览】查看)
password	1、APIKEY(用户中心【语音通知】-【产品总览】查看) 2、动态密码(生成动态密码方式请看该文档末尾的说明)
content	模板内容

返回值 AddTemplateResult 结构说明:

参数名称	类型	描述
code	int	返回值为 2 时，表示添加成功
msg	string	提交状态描述
templateid	int	添加成功则返回模板 ID

4.4 响应参数

code	msg
2	添加成功
400	非法ip访问
401	用户名不能为空
402	密码不能为空
404	模板内容不能为空
405	用户名或密码不正确
4050	账号被冻结
407	模板内容含有敏感字符
408	模板己存在

4.5 模板审核状态推送

在遵守 HTTP 协议规范的前提下，通过 POST 方式将回执推送到用户指定的 URL 地址。

注意：接口推送后请记录数据并及时返回结果，业务逻辑采用异步处理，避免接口响应超时而导致重复推送。

参数说明:

参数名称	参数值描述
code	状态值(2 成功 0 驳回)
msg	审核状态描述
templateid	模板 ID

注意:

1.成功接收请输出字符 “success” (不包含引号)结束推送，否则以接收失败处理。

2.每个回执最多推送 3 次。每次间隔叠加 60 秒。

3.code 值说明

2 成功

0 驳回(原因请看 msg 字段)

5、删除模板

5.1 接口描述

通过POST、 GET 方式删除语音通知模板，内容格式为：Content-Type: application/x-www-form-urlencoded，数据编码采用utf-8格式。

5.2 请求地址

http://api.vm.ihuyi.com/webservice/voice.php?method=DelTemplate&account=APIID&password=APIKEY&templateid=123 

5.3 请求参数

参数名称	参数值描述
method	DelTemplate
account	APIID(用户中心【语音通知】-【产品总览】查看)
password	1、APIKEY(用户中心【语音通知】-【产品总览】查看) 2、动态密码(生成动态密码方式请看该文档末尾的说明)
templateid	模板id

返回值 AddTemplateResult 结构说明:

参数名称	类型	描述
code	int	返回值为 2 时，表示删除成功
msg	string	提交状态描述

5.4 响应参数

code	msg
2	删除成功
400	非法ip访问
401	用户名不能为空
402	密码不能为空
404	模板ID不能为空或模板ID不存在
405	用户名或密码不正确
4050	账号被冻结

6、发送回执推送

6.1 接口描述

用户先提供数据接收地址，然后绑定到互亿无线系统后台，平台会以POST方式实时的将回执信息推送到此地址，内容格式为：Content-Type: application/x-www-form-urlencoded。

注意：接口推送后请记录数据并及时返回结果，业务逻辑采用异步处理，避免接口响应超时而导致重复推送。

6.2 推送参数

参数名称	参数值描述
code	状态值(2 成功 0 失败)
msg	回执状态说明
mobilephone	手机号码
talktime	接听时间(秒)
voiceid	流水号（对应提交时返回的voiceid）
report_time	回执时间 例:2018-05-24 17:46:50

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

code 参数说明

code	msg
2	成功
0	未知错误
-1	关机
-2	停机
-3	暂时无法接通
-4	正在通话
-5	空号
-6	无人接听
-8	呼入限制
-9	网络忙
-10	呼出限制
-11	线路忙
-12	用户拒接
-13	被叫忙

7、生成动态密码方式

以PHP为例，提交语音验证码的生成方式：

$time = time();
$password = md5($account.$apikey.$mobile.$content.$time);

例如：

APIID: test
APIKEY:1q784322ba1d9bb88d50cf5cdfd89k7d
手机号:138xxxxxxxx
内容:1125
time:1451544941
结果: $password=md5("test1q784322ba1d9bb88d50cf5cdfd89k7d138xxxxxxxx11251451 544941");

查询剩余条数的生成方式：

$time = time();
$password = md5($account.$apikey.$time);

例如：

APIID: test
APIKEY:1q784322ba1d9bb88d50cf5cdfd89k7d
手机号:138xxxxxxxx
time:1451544941 结果:$password=md5("test1q784322ba1d9bb88d50cf5cdfd89k7d1451544941");

Unix时间戳参考地址：http://tool.chinaz.com/Tools/unixtime.aspx

8、常见问题

8.1 如何实现 UNIX 时间戳

语言	代码
JAVA	String date = new java.text.SimpleDateFormat("dd/MM/yyyy HH:mm:ss").format(new java.util.Date(Unix timestamp *1000))
Linux	date -d @Unix timestamp
C	strptime(datetime, "%Y-%m-%d %H:%M:%S", &tm_time); unixtime = mktime(&tm_time);
C++	std::time_t t = std::time(0);
DELPHI	uses DateUtils; DateTimeToUnix(Now)
GO	import "time" cur := time.Now() timestamp := cur.UnixNano() / 1000000
Perl	先 my $time = Unix timestamp 然后 my ($sec, $min, $hour, $day, $month, $year) = (localtime($time))[0,1,2,3,4,5,6]
PHP	date("r", Unix timestamp)
Node.js	var date = new Date( time * 1000 ); var time = date.getTime()/1000;
Python	先 import time 然后 time.gmtime(Unix timestamp)
Ruby	Time.at(Unix timestamp)
SHELL	date +%s //UNIX 的时间戳;
VBScript / ASP	DateAdd("s", Unix timestamp, "01/01/1970 00:00:00")
VB6	DateDiff("s", "1970-1-1 0:0:0", ToUnixTime)
易语言	时间_到时间戳()

9、语音通知 DEMO

互亿无线提供各种语言的语音通知接口DEMO，详情请点击：语音通知接口示例