語(yǔ)音通知 - API文檔

1、概要

1.1 文檔說(shuō)明

本文檔主要提供給互億平臺(tái)的用戶對(duì)接接口的使用說(shuō)明，開(kāi)發(fā)者可以利用 ihuyi 提供的 HTTP 接口，調(diào)用 ihuyi 的語(yǔ)音通知服務(wù)。

1.2 接口內(nèi)容

本文檔包含語(yǔ)音發(fā)送、余額查詢、發(fā)送回執(zhí)推送等。

1.3 提交方式

GET / POST

1.4 加密方式

1、采用HTTPS協(xié)議提交請(qǐng)求
2、通過(guò)MD5動(dòng)態(tài)簽名方式加密

1.5 API ID / API KEY

登錄用戶中心，進(jìn)入【語(yǔ)音通知】模塊，在【產(chǎn)品總攬】頁(yè)面右上角，如下圖所示：

1.6 語(yǔ)音模版

語(yǔ)音通知模板是對(duì)您將要發(fā)送的語(yǔ)音進(jìn)行相似性提取后的內(nèi)容。舉個(gè)例子，

A 用戶是您的老會(huì)員，即將過(guò)生日，需要發(fā)送一條語(yǔ)音短信，內(nèi)容如下:

您的客戶張茜將于 2 天后過(guò)生日，別忘記注意祝福哦~

同時(shí)，B 用戶是您的老會(huì)員，即將過(guò)生日，發(fā)送了如下語(yǔ)音短信:

您的客戶趙鑫將于 3 天后過(guò)生日，別忘記注意祝福哦~

我們提取相似度以后，可以制作以下語(yǔ)音模板:

您的客戶【變量】將于 【變量】天后過(guò)生日，別忘記注意祝福哦~

其中，變量是可變的，可以是 數(shù)字、字母、漢字。

2、語(yǔ)音通知發(fā)送

2.1 接口描述

通過(guò)POST、 GET 方式提交語(yǔ)音通知，內(nèi)容格式為：Content-Type: application/x-www-form-urlencoded，數(shù)據(jù)編碼采用utf-8格式。

2.2 請(qǐng)求地址

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

2.3 請(qǐng)求參數(shù)

參數(shù)名稱	參數(shù)值描述	必填
account	APIID(用戶中心【語(yǔ)音通知】-【產(chǎn)品總覽】查看)	是
password	1、APIKEY(用戶中心【語(yǔ)音通知】-【產(chǎn)品總覽】查看) 2、動(dòng)態(tài)密碼(生成動(dòng)態(tài)密碼方式請(qǐng)看該文檔末尾的說(shuō)明)	是
mobile	支持中國(guó)內(nèi)地手機(jī)號(hào)碼及固話號(hào)碼。 手機(jī)號(hào)：11位，示例：139****0000。 固話號(hào)碼：{區(qū)號(hào)}{號(hào)碼}，示例：02151****29。 接收手機(jī)號(hào)碼，只能提交一個(gè)號(hào)碼	是
content	語(yǔ)音通知內(nèi)容(編碼格式為 UTF-8) 例如:您的訂單號(hào)是：9633。已由順風(fēng)快遞發(fā)出，請(qǐng)注意查收。	是
time	Unix時(shí)間戳（10位整型數(shù)字，當(dāng)使用動(dòng)態(tài)密碼方式時(shí)為必填）	否
format	返回格式（可選值為：xml或json，系統(tǒng)默認(rèn)為xml）	否

用戶通過(guò)http 或 https提交發(fā)送短信請(qǐng)求到服務(wù)器后，服務(wù)器會(huì)返回一串xml格式的字符串，SubmitResult結(jié)構(gòu)說(shuō)明如下：

參數(shù)名稱	類型	描述
code	int	返回值為2時(shí)，表示提交成功
voiceid	string	當(dāng)提交成功后，此字段為流水號(hào)，否則為0
msg	string	提交結(jié)果描述

2.4 響應(yīng)示例

示例（成功）

    2 提交成功 60495654 

示例（失敗）

    405 account或password不正確 0 

2.5 響應(yīng)參數(shù)

code	msg
0	提交失敗
2	提交成功
400	非法ip訪問(wèn)
401	帳號(hào)不能為空
402	密碼不能為空
403	手機(jī)號(hào)碼不能為空
4030	手機(jī)號(hào)碼已被列入黑名單
404	語(yǔ)音內(nèi)容不能為空
405	用戶名或密碼不正確
4050	賬號(hào)被凍結(jié)
40505	沒(méi)有簽定合同
4051	剩余條數(shù)不足
4052	訪問(wèn) ip 與備案 ip 不符
406	手機(jī)格式不正確
407	短信內(nèi)容含有敏感字符
4071	沒(méi)有提交備案模板
4072	提交的語(yǔ)音內(nèi)容必須與報(bào)備過(guò)的模板格式相匹配
40722	變量?jī)?nèi)容超過(guò)指定的長(zhǎng)度
4077	發(fā)送內(nèi)容未在運(yùn)營(yíng)商報(bào)備
408	您的帳戶疑被惡意利用，已被自動(dòng)凍結(jié)，如有疑問(wèn)請(qǐng)與客服聯(lián)系
4080	同一手機(jī)號(hào)碼同一秒鐘之內(nèi)發(fā)送頻率不能超過(guò)1條
4081	同一手機(jī)號(hào)一分鐘之內(nèi)發(fā)送超過(guò)3條
4082	超出同一手機(jī)號(hào)一天之內(nèi)10條短信限制

2.6 GET 請(qǐng)求示例

http://api.vm.ihuyi.com/webservice/voice.php?method=Submit&account=APIID& password=APIKEY&mobile=手機(jī)號(hào)碼&content=您的訂單號(hào)是：0648。已由順風(fēng)快遞 發(fā)出，請(qǐng)注意查收。

3、余額查詢

3.1 接口描述

通過(guò)POST、 GET 方式查詢你的賬戶語(yǔ)音通知剩余條數(shù)，內(nèi)容格式為：Content-Type: application/x-www-form-urlencoded，數(shù)據(jù)編碼采用utf-8格式。

3.2 請(qǐng)求地址

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

3.3 請(qǐng)求參數(shù)

參數(shù)名稱	參數(shù)值描述	是否必填
account	APIID(用戶中心【語(yǔ)音通知】-【產(chǎn)品總覽】查看)	是
password	1、APIKEY(用戶中心【語(yǔ)音通知】-【產(chǎn)品總覽】查看) 2、動(dòng)態(tài)密碼(生成動(dòng)態(tài)密碼方式請(qǐng)看該文檔末尾的說(shuō)明)	是
time	Unix時(shí)間戳（10位整型數(shù)字，當(dāng)使用動(dòng)態(tài)密碼方式時(shí)為必填）	否
format	返回格式（可選值為：xml或json，系統(tǒng)默認(rèn)為xml）	否

用戶通過(guò)http 或 https提交帳戶余額查詢請(qǐng)求到服務(wù)器后，服務(wù)器會(huì)返回一串xml格式的字符串，GetNumResult結(jié)構(gòu)說(shuō)明如下：

參數(shù)名稱	類型	描述
code	int	狀態(tài)返回值
msg	string	查詢結(jié)果描述
num	string	剩余數(shù)量

3.4 響應(yīng)示例

示例（成功）

    2 查詢成功 856 

示例（失敗）

    405 account或password不正確 0 

3.5 響應(yīng)參數(shù)

code	msg
2	查詢成功
400	非法ip訪問(wèn)
401	帳號(hào)不能為空
402	密碼不能為空
405	用戶名或密碼不正確
4050	賬號(hào)被凍結(jié)

3.6 GET請(qǐng)求示例

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

4、提交模板

4.1 接口描述

通過(guò)POST、 GET 方式提交語(yǔ)音通知模板，內(nèi)容格式為：Content-Type: application/x-www-form-urlencoded，數(shù)據(jù)編碼采用utf-8格式。

4.2 請(qǐng)求地址

http://api.vm.ihuyi.com/webservice/voice.php?method=AddTemplate&account=APIID&password=APIKEY&content=您的訂單號(hào)是：【變量】。已由順風(fēng)快遞發(fā)出，請(qǐng)注意查收。

4.3 請(qǐng)求參數(shù)

參數(shù)名稱	參數(shù)值描述
method	AddTemplate
account	APIID(用戶中心【語(yǔ)音通知】-【產(chǎn)品總覽】查看)
password	1、APIKEY(用戶中心【語(yǔ)音通知】-【產(chǎn)品總覽】查看) 2、動(dòng)態(tài)密碼(生成動(dòng)態(tài)密碼方式請(qǐng)看該文檔末尾的說(shuō)明)
content	模板內(nèi)容

返回值 AddTemplateResult 結(jié)構(gòu)說(shuō)明:

參數(shù)名稱	類型	描述
code	int	返回值為 2 時(shí)，表示添加成功
msg	string	提交狀態(tài)描述
templateid	int	添加成功則返回模板 ID

4.4 響應(yīng)參數(shù)

code	msg
2	添加成功
400	非法ip訪問(wèn)
401	用戶名不能為空
402	密碼不能為空
404	模板內(nèi)容不能為空
405	用戶名或密碼不正確
4050	賬號(hào)被凍結(jié)
407	模板內(nèi)容含有敏感字符
408	模板己存在

4.5 模板審核狀態(tài)推送

在遵守 HTTP 協(xié)議規(guī)范的前提下，通過(guò) POST 方式將回執(zhí)推送到用戶指定的 URL 地址。

注意：接口推送后請(qǐng)記錄數(shù)據(jù)并及時(shí)返回結(jié)果，業(yè)務(wù)邏輯采用異步處理，避免接口響應(yīng)超時(shí)而導(dǎo)致重復(fù)推送。

參數(shù)說(shuō)明:

參數(shù)名稱	參數(shù)值描述
code	狀態(tài)值(2 成功 0 駁回)
msg	審核狀態(tài)描述
templateid	模板 ID

注意:

1.成功接收請(qǐng)輸出字符 “success” (不包含引號(hào))結(jié)束推送，否則以接收失敗處理。

2.每個(gè)回執(zhí)最多推送 3 次。每次間隔疊加 60 秒。

3.code 值說(shuō)明

2 成功

0 駁回(原因請(qǐng)看 msg 字段)

5、刪除模板

5.1 接口描述

通過(guò)POST、 GET 方式刪除語(yǔ)音通知模板，內(nèi)容格式為：Content-Type: application/x-www-form-urlencoded，數(shù)據(jù)編碼采用utf-8格式。

5.2 請(qǐng)求地址

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

5.3 請(qǐng)求參數(shù)

參數(shù)名稱	參數(shù)值描述
method	DelTemplate
account	APIID(用戶中心【語(yǔ)音通知】-【產(chǎn)品總覽】查看)
password	1、APIKEY(用戶中心【語(yǔ)音通知】-【產(chǎn)品總覽】查看) 2、動(dòng)態(tài)密碼(生成動(dòng)態(tài)密碼方式請(qǐng)看該文檔末尾的說(shuō)明)
templateid	模板id

返回值 AddTemplateResult 結(jié)構(gòu)說(shuō)明:

參數(shù)名稱	類型	描述
code	int	返回值為 2 時(shí)，表示刪除成功
msg	string	提交狀態(tài)描述

5.4 響應(yīng)參數(shù)

code	msg
2	刪除成功
400	非法ip訪問(wèn)
401	用戶名不能為空
402	密碼不能為空
404	模板ID不能為空或模板ID不存在
405	用戶名或密碼不正確
4050	賬號(hào)被凍結(jié)

6、發(fā)送回執(zhí)推送

6.1 接口描述

用戶先提供數(shù)據(jù)接收地址，然后綁定到互億無(wú)線系統(tǒng)后臺(tái)，平臺(tái)會(huì)以POST方式實(shí)時(shí)的將回執(zhí)信息推送到此地址，內(nèi)容格式為：Content-Type: application/x-www-form-urlencoded。

注意：接口推送后請(qǐng)記錄數(shù)據(jù)并及時(shí)返回結(jié)果，業(yè)務(wù)邏輯采用異步處理，避免接口響應(yīng)超時(shí)而導(dǎo)致重復(fù)推送。

6.2 推送參數(shù)

參數(shù)名稱	參數(shù)值描述
code	狀態(tài)值(2 成功 0 失敗)
msg	回執(zhí)狀態(tài)說(shuō)明
mobilephone	手機(jī)號(hào)碼
talktime	接聽(tīng)時(shí)間(秒)
voiceid	流水號(hào)（對(duì)應(yīng)提交時(shí)返回的voiceid）
report_time	回執(zhí)時(shí)間 例:2018-05-24 17:46:50

注意: 成功接收請(qǐng)輸出字符 “success” (不包含引號(hào))結(jié)束推送，否則以接收失敗處理。 每個(gè)回執(zhí)最多推送 3 次。每次間隔疊加 60 秒。

code 參數(shù)說(shuō)明

code	msg
2	成功
0	未知錯(cuò)誤
-1	關(guān)機(jī)
-2	停機(jī)
-3	暫時(shí)無(wú)法接通
-4	正在通話
-5	空號(hào)
-6	無(wú)人接聽(tīng)
-8	呼入限制
-9	網(wǎng)絡(luò)忙
-10	呼出限制
-11	線路忙
-12	用戶拒接

7、生成動(dòng)態(tài)密碼方式

以PHP為例，提交語(yǔ)音驗(yàn)證碼的生成方式：

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

例如：

APIID: test
APIKEY:1q784322ba1d9bb88d50cf5cdfd89k7d
手機(jī)號(hào):138xxxxxxxx
內(nèi)容:1125
time:1451544941
結(jié)果: $password=md5('test1q784322ba1d9bb88d50cf5cdfd89k7d138xxxxxxxx11251451 544941');

查詢剩余條數(shù)的生成方式：

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

例如：

APIID: test
APIKEY:1q784322ba1d9bb88d50cf5cdfd89k7d
手機(jī)號(hào):138xxxxxxxx
time:1451544941 結(jié)果:$password=md5('test1q784322ba1d9bb88d50cf5cdfd89k7d1451544941');

Unix時(shí)間戳參考地址：http://tool.chinaz.com/Tools/unixtime.aspx

8、常見(jiàn)問(wèn)題

8.1 如何實(shí)現(xiàn) UNIX 時(shí)間戳

語(yǔ)言	代碼
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 的時(shí)間戳;
VBScript / ASP	DateAdd("s", Unix timestamp, "01/01/1970 00:00:00")
VB6	DateDiff("s", "1970-1-1 0:0:0", ToUnixTime)
易語(yǔ)言	時(shí)間_到時(shí)間戳()

9、語(yǔ)音通知 DEMO

互億無(wú)線提供各種語(yǔ)言的語(yǔ)音通知接口DEMO，詳情請(qǐng)點(diǎn)擊：語(yǔ)音通知接口示例