電話語音通知

1、概要

1.1 文檔說明

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

1.2 接口內(nèi)容

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

1.3 提交方式

GET / POST

1.4 加密方式

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

1.5 API ID / API KEY

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

1.6 語音模版

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

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

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

同時，B 用戶是您的老會員，即將過生日，發(fā)送了如下語音短信:

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

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

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

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

2、語音短信發(fā)送

2.1 接口描述

通過POST、 GET 方式進(jìn)行短信提交，數(shù)據(jù)編碼采用utf-8格式，24小時全天發(fā)送。

2.2 請求地址

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

2.3 請求參數(shù)

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

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

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

2.4 響應(yīng)示例

示例（成功）

  2         提交成功 60495654 

示例（失?。?/p>

  405 用戶名或密碼不正確 0     

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

code	msg
0	提交失敗
2	提交成功
400	非法ip訪問
401	帳號不能為空
402	密碼不能為空
403	手機(jī)號碼不能為空
4030	手機(jī)號碼已被列入黑名單
404	語音內(nèi)容不能為空
405	用戶名或密碼不正確
4050	賬號被凍結(jié)
4051	剩余條數(shù)不足
4052	訪問 ip 與備案 ip 不符
406	手機(jī)格式不正確
407	短信內(nèi)容含有敏感字符
4071	沒有提交備案模板
4072	提交的語音內(nèi)容必須與報備過的模板格式相匹配
40722	變量內(nèi)容超過指定的長度
408	您的帳戶疑被惡意利用，已被自動凍結(jié)，如有疑問請與客服聯(lián)系

2.6 GET 請求示例

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

3、余額查詢

3.1 接口描述

通過接口可以方便的查詢你的賬戶驗證碼通知短信剩余條數(shù)。

3.2 請求地址

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

3.3 請求參數(shù)

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

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

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

3.4 響應(yīng)示例

示例（成功）

  2 查詢成功 856         

示例（失?。?/p>

  405 用戶名或密碼不正確 0 

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

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

3.6 GET請求示例

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

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

4.1 接口描述

用戶先提供數(shù)據(jù)接收地址，然后綁定到互億無線系統(tǒng)后臺，平臺會以POST方式實時的將回執(zhí)信息推送到此地址。

4.2 推送參數(shù)

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

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

code 參數(shù)說明

code	msg
2	成功
0	未知錯誤
-1	關(guān)機(jī)
-2	停機(jī)
-3	暫時無法接通
-4	正在通話
-5	空號
-6	無人接聽
-7	開通來電提醒
-8	呼入限制
-9	網(wǎng)絡(luò)忙
-10	呼出限制
-11	線路忙
-12	用戶拒接
-13	呼叫轉(zhuǎn)移
-14	傳真機(jī)摘機(jī)識別
-15	自動應(yīng)答機(jī)摘機(jī)識別
-16	自然人摘機(jī)識別
-17	接通無人回話
-18	呼叫超時
-19	無應(yīng)答
-20	呼叫超時
-21	空白
-22	呼叫失敗

5、生成動態(tài)密碼方式

以PHP為例，提交語音驗證碼的生成方式：

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

例如：

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

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

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

例如：

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

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

6、常見問題

6.1 如何實現(xiàn) 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)
易語言	時間_到時間戳()