OMAPI技術開發文檔20180208
上海迅時通信設備有限公司
OM API技術開發文檔(V6.0)
電話:0531-86950915
文檔版本:V6.0
更新時間:20180208
版權所有©上海迅時通信設備有限公司2018。保留一切權利。
非經本公司書面許可,任何單位和個人不得擅自摘抄、復制本文檔內容的部分或全部,并不得以任何形式傳播。
本文主要介紹OM API的作用及使用方法,幫助程序開發人員學習并掌握OM API,最終利用OM API開發出更多更好的應用程序。
點擊這里下載PDF版。
點擊這里下載Word版。
讀前須知
閱讀本文檔之前,您最好對我司的OM系列的IPPBX產品有一定了解。
推薦資料:《OM用戶手冊》、《OM管理員手冊》、《OM 功能學習指導書》。
資料下載:OM相關資料可到迅時官網下載。
說明:所有OM系列產品的OM API都是一樣的,只是版本不同而已。
技術支持與服務
為保障開發者能夠基于OM API順利開發應用產品,我們提供了論壇、QQ群、微信公共號等多渠道的技術支持與服務。
OM API技術咨詢電話:0531-86950915
微信公眾號:
發布時間:2017-02-08
目錄
2.1.5 監聽和插播(Monitor/Talk/Listen)
本章簡單介紹OM API基本概念及應用服務器和OM之間的基本交互原理,手把手教你完成OM API認證配置,并使用測試工具體驗應用服務器和OM之間的消息交互,助您快速入門。
關于OM API
迅時OM系列的IPPBX設備提供統一的開放式接口——OM API,開發者可以通過OM API對OM設備進行控制、監控和數據統計等。
OM API本質上是經過封裝的簡單XML消息,應用服務器和OM設備之間通過HTTP協議進行通信。
1. 應用服務器通過OM API對OM進行操作:參數查詢、參數配置、狀態查詢、呼叫控制、呼叫轉接等。
2. OM實時向應用服務器推送報告:分機狀態變化、呼叫狀態、配置變化、服務啟動、DTMF、語音播放完畢和通話記錄等。
OM API使OM設備具有更大的靈活性和可操作性,開發者可利用OM API開發或對接呼叫中心、計費系統、酒管系統、CRM、OA辦公系統等豐富多彩的應用。
OM API有如下四類本領:
可實現的主要功能有:點擊撥號、來/去電彈屏、通話記錄、錄音、狀態監控、分機組和隊列、IVR語音導航、滿意度調查、酒店叫醒服務、語音信箱、語音驗證碼、來電黑/白名單等。
成功案例和合作共贏
迅時搭建了一個類似于第三方應用市場的平臺—— 企業應用平臺,所有利用OM API開發的應用產品都可以申請上架到該平臺。
上架該平臺至少有兩大好處:
1. 擴展渠道:迅時的渠道就等于你的渠道。迅時在全國大約有1200家渠道和合作伙伴,這些渠道會向用戶推薦你的應用產品。當用戶需要購買時,渠道人員會聯系你。另外,我們也會定期推廣優質的應用產品。
2. 數據統計和分析:迅時會定期將您的應用產品的訪問量、用戶喜歡數量、排名等統計結果以郵件或微信形式發送給你,讓你輕松掌握市場反饋。
迅時歡迎更多合作伙伴的參與,共同解決中小型企業的辦公和通信問題。
簡單認識OM API之后,我們來了解下OM API的通信方式。
傳輸協議
應用服務器和OM之間基于HTTP協議進行通信,API消息封裝在HTTP包體中。
消息內容如:
HTTP請求消息:
POST /xml HTTP/1.0
Content-Type:text/xml
Content-Length:101
xml version="1.0" encoding="utf-8"
<Control attribute="Query">
<DeviceInfo/>
</Control>
HTTP響應消息:
HTTP/1.0 200 OK
xml version="1.0" encoding="utf-8"
<DeviceInfo>
<manufacturer>New Rock Technologies, Inc</manufacturer>
<model>Rev 1.0.1 WROC2000-1S/1</model>
<version>Rev 2.2.5.81.1</version>
<mac>00:0E:A9:00:12:BD </mac>
<devices>
<ext lineid="Phone 1" id="200" />
<ext lineid="IPPhone 50" id="208" />
<line lineid="Line 2" id="02161208234" />
<line lineid="IPLine 21" id="02161204000" />
</devices>
</DeviceInfo>
通信方式
應用服務器和OM之間的交互是雙向的,雙方互為HTTP服務端和客戶端。
正向:應用服務器作為HTTP 客戶端,OM作為HTTP服務端
應用服務器請求OM執行某個功能(如,發起呼叫)或提供某些信息(如,查詢狀態)。此時,采用的是HTTP POST方法、TCP短連接方式(注:OM只支持TCP短連接接收)。
流程為:①請求 ②響應 ③斷開。
交互圖如下:
情況二:OM作為HTTP客戶端,應用服務器作為HTTP服務端
OM主動向應用服務器推送某些消息(如,分機振鈴事件),應用服務器收到消息后斷開TCP連接(注:這里不是標準的HTTP請求響應流程,不需要應用服務器回復響應)。
此時,采用的是HTTP GET或POST方法(默認為GET,若參數API_METHOD = 1,則為POST)。
注:OM默認以短連接方式推送消息,也可通過參數CONTROL_TYPE配置為長連接。建議采用短連接方式。
流程為:①接收消息 ②斷開。
我們提供多種語言(如PHP、JAVA、C#、C)編寫的發送和接收消息的demo,詳情請參考API新編開發指南。
下面,我們用測試工具(相當于一個簡單的應用服務器)來演示OM和API應用服務器的配置方法及收發消息過程。
配置
注:這里我們采用IP認證方式。
步驟一:配置OM設備認證地址
登錄OM設備頁面,點擊應用服務器 > API,在應用服務器一欄選擇自定義(默認選中為儂好,儂好是內置在設備里的小型呼叫中心),填寫應用服務器地址(即測試工具所在的電腦IP:OM發送端口,可自定義)如,192.168.130.27:8989。
步驟二:配置分機和外線的API開關
進入應用服務器 > API,在API功能開關一欄將分機和外線的狀態監控、來電應答前/來電應答后控制開關打開,點擊保存,并重啟設備。
設備配置如下圖所示:
步驟三:配置測試工具
1. 點擊這里下載測試工具及其源代碼,并在電腦桌面打開,填寫一個HTTP監聽端口(該端口與設備上配置的OM發送端口保持一致,應為8989 ),點擊開始監聽。(注:測試工具的源碼可點擊這里下載)。
2. 填寫發送地址(即OM的IP地址和HTTP端口),如192.168.130.219:80。
注:OM的HTTP端口默認為80,可在設備高級設置>安全配置>Web管理處修改。
測試工具配置如下圖所示:
跑個流程
完成了配置以后,接下來我們演示一個分機呼叫分機的流程,為第二章的接口使用和理解奠定基礎。
發送命令
如何通過OM API實現分機呼分機呢?
只需向OM發送一條API消息:
xml version="1.0" encoding="utf-8"
<Transfer attribute="Connect">
<ext id="200"/>
<ext id="201"/>
</Transfer>
說明:
Ÿ 第一行是XML聲明,每個API消息都有且相同。它定義了XML的版本(1.0)和所使用的編碼方式(utf-8)。
Ÿ 第二行是XML的根。根元素Transfer表明這個是一個呼叫轉接類的API。屬性值Connect表示本次轉接的屬性為連接。
Ÿ 第三、第四行中ext是“分機”的英文單詞extension的簡寫,200為主叫分機號碼,201為被叫分機號碼。
Ÿ 第五行為根節點的閉合標簽。
注:更多 XML 的語法參見XML教程,更多OM API語法詳解請參見第二章。
觀察執行結果
執行完該 API 后,后續流程為:
1. 主叫分機200會先振鈴(默認,先呼誰后呼誰由參數API_CALLING控制);
2. 將200摘機后,被叫分機201開始振鈴,并且200可以聽到“嘟嘟”的回鈴音;
3. 將201也摘機后,雙方成功建立通話;
4. 任意一方掛機后通話結束。
觀察收到的API消息
查看測試工具,可以看到接收到很多條API消息。這些消息中,有兩個消息是話單(CDR),其他的為事件(Event)。
Ÿ CDR為通話記錄,在通話結束時產生。2個CDR中一個是主叫分機的通話記錄,另一個是被叫分機的通話記錄;
Ÿ Event表示事件消息,由呼叫過程中OM自動觸發。
1)事件
本次呼叫過程中,收到的事件屬性有這些:BUSY、IDLE、RING、ALERT、ANSWER、ANSWERED、BYE。
其中:
Ÿ BUSY和IDLE是一對,在分機狀態發生變化時產生。BUSY表示分機由空閑變為忙狀態, IDLE 表示分機由忙變為空閑狀態;
Ÿ RING、ALERT、ANSWER、ANSWERED、BYE屬于一個系列,在呼叫過程中產生。其中:
。 RING和ALERT是一對, RING表示分機開始振鈴,ALERT表示收到對方的回鈴(ringback)信號。
。 ANSWER和ANWERED是一對,ANSWER 表示分機應答,ANSWERED表示收到對方應答的信號。
。 BYE表示通話結束。
通過以上事件,你可以實時監控分機的線路狀態和呼叫情況,并可以實現一些應用功能,比如:來/去電彈屏(當分機振鈴時將來電號碼對應的客戶資料彈屏顯示在電腦屏幕上)。
注:更多關于事件的介紹,參見2.5章節。
2)通話記錄(CDR)
通話結束后,OM會立即將通話記錄推送給應用服務器(這里指測試工具)。
消息格式
xml version="1.0" encoding="utf-8"
<Cdr id="13620170308103713-0">
<callid>32820</callid>
<TimeStart>20170308103709</TimeStart>
<Type>IN</Type>
<Route>IC</Route>
<CPN>200</CPN>
<CDPN>201</CDPN>
<TimeEnd>20170308103713</TimeEnd>
<Duration>2</Duration>
<TrunkNumber></TrunkNumber>
<Recording>20170308/200_201_20170308_103711_8034_cd.wav</Recording>
<RecCodec>PCMU</RecCodec>
</Cdr>
參數說明
參數名稱 |
解釋說明 |
---|---|
Cdr id |
通話記錄的編號。格式:系列號+年月日時分秒+固定內容(-0) |
callid |
通話的相對唯一標識符 |
TimeStart |
呼叫起始時間戳,格式:年月日時分秒 |
Type |
話務類型,IN表示呼入,LO表示內部呼叫 |
Route |
路由類型,IC表示內部路由 |
CPN |
主叫號碼 |
CDPN |
被叫號碼 |
TimeEnd |
呼叫釋放時間戳,格式:年月日時分秒 |
Duration |
通話時長,單位:秒。即,從呼叫接通到呼叫釋放的時長,不包括振鈴時間。 |
Trunk |
中繼號碼(本次是內部呼叫,沒有用到中繼,所以值為空) |
Recording |
錄音文件的相對保存路徑,格式:生成日期/錄音文件名稱 |
注:更多關于CDR的介紹,參見2.6章節。
API認證方式包括正向認證和反向認證兩種。
正向認證:應用服務器向OM發送請求命令時,需通過OM的認證。
反向認證:OM向應用服務器發送消息時,需通過應用服務器的認證。
一、正向認證
正向認證分為IP認證和數字簽名認證兩種方式,您可以根據自己的實際場景選擇一種來完成認證。
IP認證
IP認證,只允許某一固定IP地址向OM發送API請求,其他地址統統認為沒有權限。
適用的應用場景:
1. 應用服務器的IP地址/域名固定;
2. 一個應用服務器對接一臺OM;
3. 應用服務器和OM之間網絡互通。
配置
配置方法,如下圖所示:
參數說明:
Ÿ 服務器地址: 應用服務器的IP地址/域名和監聽端口,如:192.168.130.27:8989。如果用戶未指定端口時默認為80端口。
Ÿ URL: 接收API報告的相對路徑(也可不填寫)。格式為:{part1}/{part2}/{part3}/{……},如:omapi/report。
服務器地址和URL組合起來即為應用服務器接收API報告的全路徑,如:192.168.130.27:8989/omapi/report。
應用服務器地址的作用:
1. 接收API報告:OM會將API消息推送給這個地址;
2. 訪問權限控制: OM只受理從該服務器的IP地址(端口不影響)發送的API請求;拒絕受理從其它地址發送的API請求,并對該請求響應Unauthorized。
點擊這里查看更多詳情。
數字簽名認證
數字簽名認證本質上是通過驗證OM和應用服務器雙方持有的秘鑰來完成認證。
版本要求
OM軟件版本:Rev 2.1.5.99及其以上。
適用的應用場景:
1. 應用服務器采用動態域名,IP地址不固定;
2. 一個OM要對接多個API應用服務器;
3. API應用客戶端要直接訪問OM;
4. API消息的源地址容易發生變化;
5. 應用服務器通過迅時云平臺轉發消息給OM。
配置
配置參數:數字簽名認證密碼(接收)和數字簽名有效期。
配置界面,如下圖所示:
參數說明:
1. API數字認證密碼(接收):OM對應用服務器認證的秘鑰,可自定義,需和應用服務器發送請求時攜帶的秘鑰保持一致。
2. API數字認證有效期:可自定義,范圍:0~86400,單位:秒,只有在該有效期內認證參數才有效,0表示永久有效。
點擊這里查看更多詳情。
注:不論是IP認證還是數字簽名認證,都需要在OM頁面配置應用服務器地址,用來接收API消息。
二、反向認證
反向認證,即應用服務器對OM的認證。OM向應用服務器推送API消息時攜帶Auth認證信息,應用服務器根據收到的消息是否滿足認證條件來選擇是否接收該消息。
注:只有應用服務器要求對OM進行認證時才配置,若不要求,可不配置。
版本要求
Rev 2.1.5.116及以上
配置
配置參數:數字簽名認證密碼(發送)和數字簽名有效期。
配置界面,如下圖所示:
參數說明:
1. API數字認證密碼(發送):應用服務器對OM進行認證的秘鑰,可自定義,需和應用服務器接收消息時配置的秘鑰保持一致。
2. API數字認證有效期:可自定義,范圍:0~86400,單位:秒,只有在該有效期內認證參數才有效,0表示永久有效。
點擊這里查看更多詳情。
本章為OM API接口部分,包括API請求命令和API報告兩部分內容。
Ÿ API請求命令,指應用服務器向OM發送的API消息,包括制命令、轉接命令和來電受理命令三種類型。
Ÿ API報告,指OM主動向應用服務器推送的API消息,包括事件報告和通話記錄報告兩種類型。
控制命令包括查詢、配置、呼叫保持與接回、靜音與解除靜音、監聽、強插、強拆。
此類API用于查詢OM設備上指定對象的相關信息(如,配置參數和狀態)。這些對象包括:設備信息(deviceInfo)、分機(ext)、中繼(trunk)、來電(visitor)、去電(outer)、分機組(group)、語音菜單(menu)。
查詢請求的規則說明
Ÿ 最小的查詢單位是對象,即不支持單獨查詢該對象的某一個具體參數。
查詢結果的規則說明
Ÿ 查詢結果中包含該對象的所有可提供的相關參數和狀態信息。
Ÿ 如果查詢結果中沒有攜帶某個參數信息,則可能原因為:
° 該參數值為默認值;
° 該參數不存在;
° 不支持查詢該參數。
該API用于查詢OM設備自身的相關信息,如:生產商、硬件版本、軟件版本,以及所有的分機、分機組和中繼等。
<?xml version="1.0" encoding="utf-8" ?>
<?xml version="1.0" encoding="utf-8" ?>
<manufacturer>New Rock Technologies, Inc</manufacturer>
<model>Rev 6.0.0 OM20-2S/2</model>
<version>Rev 2.1.5.111</version>
<ext lineid="Phone 1" id="200" />
<ext lineid="IPPhone 50" id="208" />
<line lineid="Line 2" id="02161208234" />
<line lineid="IPLine 21" id="02161204000" />
說明:<>表示必選項,[]表示可選項(當參數值為默認值或空時,響應消息可能不攜帶該參數),| 表示或者關系
如 00:0E:A9:00:12:BD(由系統參數API_MAC決定是否攜帶MAC地址) |
|||
[ext] |
object |
分機 |
|
<ext lineid> |
string |
分機的線路編號,是分機的唯一固定標識 |
<Phone | IPPhone> {NO.},如:Phone 1 |
<ext id> |
string |
分機號 |
|
[line] |
object |
中繼(外線) |
line和trunk是指同一個對象,即中繼(外線) |
<line lineid> |
string |
中繼的線路編號,是中繼的唯一固定標識 |
<Line | IPLine> { NO.},如:Line 13 |
[line id] |
string |
中繼號 |
|
[group id] |
int |
分機組的序號 |
1~50 |
注:
Ÿ 響應結果中包含所有的分機線路和中繼線路信息,如果設備線路量很大,注意查詢接收的緩存空間;
Ÿ 設備線路量大時,建議使用web的分頁查詢接口分別獲取分機或中繼線路。
該API用于查詢指定分機的相關信息,如:配置參數、分機狀態、通話方等。
xml version="1.0" encoding="utf-8"
xml version="1.0" encoding="utf-8"
<Call_Pickup>yes</Call_Pickup>
<Fwd_Number>18603752801</Fwd_Number>
<Call_Restriction>3</Call_Restriction>
<Off_Line_Num>200</Off_Line_Num>
<email>admin@hotmail.com</email>
<voicefile>welcome</voicefile>
<outer id="8" from="208" to="13012345678" trunk="02161208234" callid="28680">
說明:<>表示必選項,[]表示可選項(當參數值為默認值或空時,響應消息可能不攜帶該參數),| 表示或者關系
|
|||
[state] |
string |
線路狀態 |
Ready: 空閑可用 |
[outer] |
object |
去電,這里作為該查詢分機的通話方 |
|
[id] |
int |
去電的編號,可依據該參數進行呼叫轉接 |
|
[from] |
string |
原始主叫號碼 |
|
<to> |
string |
原始被叫號碼(對于visitor而言,原始被叫為來電呼入中繼號碼) |
|
[trunk] |
string |
中繼號,即該去電從該中繼呼出 |
|
[callid] |
int |
通話的相對唯一標識符 |
|
[state] |
string |
通話狀態 |
Talk: 通話進行中 |
[visitor] |
object |
來電,這里作為該查詢分機的通話方 |
|
<id> |
int |
來電的編號,可依據該參數進行呼叫轉接等操作 |
|
<from> |
string |
原始主叫號碼 |
|
<to> |
string |
原始被叫號碼(對于visitor而言,原始被叫為來電呼入的中繼號碼) |
|
<callid> |
int |
通話的相對唯一標識符 |
|
[state] |
string |
通話狀態 |
Talk: 通話進行中 |
[ext] |
object |
分機,這里作為該查詢分機的通話方 |
|
<id> |
string |
分機號 |
|
[state] |
string |
通話狀態 |
Talk: 通話進行中 |
查詢中繼
該API用于查詢指定中繼(又稱為外線)的相關信息,如:配置參數、線路狀態、呼叫狀態等。
請求示例
xml version="1.0" encoding="utf-8"
<Control attribute="Query">
<trunk id="2174"/>
</Control>
參數說明
參數名稱 |
類型 |
參數說明 |
參數值說明 |
---|---|---|---|
<trunk id> |
string |
中繼號碼(外線號碼) |
必須為OM上的有效中繼,值不能為空 |
響應示例
xml version="1.0" encoding="utf-8"
<Status>
<trunk id="2174">
<lineid>Line 75</lineid>
<state>active</state>
<visitor id="2" from="202" to="2174" callid="36866">
<state>talk</state>
</visitor>
</trunk>
</Status>
參數說明
說明:<>表示必選項,[]表示可選項(當參數值為默認值或空時,響應消息可能不攜帶該參數),| 表示或者關系
參數名稱 |
類型 |
參數說明 |
參數值說明 |
---|---|---|---|
<trunk id> |
string |
中繼(外線)號 |
數字字符串 |
<lineid> |
string |
中繼的線路編號,是中繼的唯一固定標識 |
IPLine | Line XXX |
<state> |
string |
中繼的線路狀態 |
ready: 可用 |
[outer] |
object |
去電 |
|
<id> |
int |
去電的編號,可通過該參數對去電進行轉接、查詢、掛斷等操作 |
|
<from> |
string |
原始主叫號碼 |
|
<to> |
string |
原始被叫號碼(對于visitor而言,原始被叫為來電呼入中繼號碼) |
|
<trunk> |
string |
中繼號, 該去電通過該中繼呼出 |
|
<callid> |
int |
通話的相對唯一符 |
|
<state> |
string |
通話狀態 |
Talk: 通話進行中 |
[visitor] |
object |
來電 |
|
<id> |
int |
來電的編號,可通過該參數對來電進行轉接、查詢、掛斷等操作 |
|
<from> |
string |
原始主叫號碼 |
|
<to> |
string |
原始被叫號碼(對于visitor而言,原始被叫為來電呼入的中繼號碼) |
|
<callid> |
int |
該路通話的相對唯一的編號 |
|
<state> |
string |
通話狀態 |
Talk: 通話進行中 |
該API用于查詢指定來電的相關信息,如:來電的屬性參數(編號、原始主叫、原始被叫、通話狀態、相對唯一標識符)、來電的通話方、呼叫狀態。
xml version="1.0" encoding="utf-8"
xml version="1.0" encoding="utf-8"
<visitor id="1" from="02167103750" to="02161208234" callid="49189">
解釋: 來電1是由外部電話02167103750通過中繼線02161208234呼入到OM設備,并且當前正在和分機200通話中。
說明:<>表示必選項,[]表示可選項(當參數值為默認值或空時,響應消息可能不攜帶該參數),| 表示或者關系
該API用于查詢指定去電的相關信息,如:去電的編號、主叫方、被叫方、通過的中繼號碼、通話狀態以及通話的相對唯一標識符。
xml version="1.0" encoding="utf-8"
xml version="1.0" encoding="utf-8"
<outer id="5" from="200" to="13012345678" trunk="02161208234" callid="32773">
<outer id="5" from="200" to="13012345678" trunk="02161208234" callid="32773"/>
解釋: 去電5是由分機200對外部電話13012345678發起的呼叫,該路通話所經過的中繼線為02161208234。
說明:<>表示必選項,[]表示可選項(當參數值為默認值或空時,響應消息可能不攜帶該參數)
該API用于查詢分機組的相關信息,如:配置參數(分機成員、呼叫排隊時播放的背景音樂、呼叫分配規則)、正在該分機組隊列中等待的來電。
xml version="1.0" encoding="utf-8"
xml version="1.0" encoding="UTF-8"
<voicefile>NowMorning</voicefile>
<distribution>sequential</distribution>
<visitor id="27" from="02167103750" to="02161208234" callid="49162"/>
<visitor id="28" from="13012345678" to="02161204000" callid="49164"/>
說明:<>表示必選項,[]表示可選項(當參數值為默認值或空時,響應消息可能不攜帶該參數)
該API用于查詢語音菜單的相關信息,如:配置參數(語音文件、撥號檢測長度、按鍵檢查結束符)、轉接到該菜單的呼叫信息等。
xml version="1.0" encoding="utf-8"
xml version="1.0" encoding="utf-8"