Verze z 11. 1. 2017, 11:05

API rozhraní

Ústředna VoIPSUN PBX disponuje mimo Asterisk API rozhraní i jednoduchým API rozhraním, přes které lze jednoduše inicializovat hovor a ukončit (click2call) nebo zobrazit seznam aktivních hovorů. Další funkce lze doprogramovat na přání klienta.

Vytočení čísla

Inicializovat nový hovor je možné čtyřmi způsoby. Liší se jen v informaci, na kterou telefonní linku má ústředna zavolat předtím, než začne spojovat hovor na cílové telefonní číslo. Vytočení čísla funguje tak, že ústředna nejprve zavolá na zvolenou linku a po vyzvednutí hovoru začne okamžitě vytáčet cílové číslo.

Proměnné a jejich hodnoty:

PROMĚNNÁ - HODNOTA - popis

username - autorizační jméno - API uživatelé se nastavují v nabídce Nastavení -> HTTP API uživatelé.

password - autorizační heslo - přihlašovací heslo.

action - originate - ústředně bude předán pokyn na vytvoření nového hovoru.

dstNum - cílové telefonní číslo - číslo, na které bude hovor spojen.

srcExtenPublicNum - veřejné číslo linky - veřejné číslo linky, na kterou ústředna zavolá před vytočením cílového telefonního čísla.

srcExtenInternalNum - interní číslo linky - interní číslo linky, na kterou ústředna zavolá před vytočením cílového telefonního čísla.

srcExtenId - ID linky - ID linky, na kterou ústředna zavolá před vytočením cílového telefonního čísla. ID lze zjistit z databáze z tabulky extensions. Tento způsob je určen především pro vývojáře informačních systémů s přístupem do databáze ústředny.

srcSipUsername - SIP uživatelské jméno - SIP uživatelské jméno linky, na kterou ústředna zavolá před vytočením cílového telefonního čísla.

dialplanName - název číslovacího plánu - pokud používáte v ústředně více interních linek se stejným číslem, tak je nutné upřesnit jméno číslovacího plánu, ze kterého se má vybrat interní linka. Jinak je parametr nepovinný.

customCDR1 - číselná nebo textová hodnota - tato hodnota bude uložena do CDR do sloupce CustomCDR1. Parametr je nepovinný.

customCDR2 - číselná nebo textová hodnota - tato hodnota bude uložena do CDR do sloupce CustomCDR2. Parametr je nepovinný.

customCDR3 - číselná nebo textová hodnota - tato hodnota bude uložena do CDR do sloupce CustomCDR3. Parametr je nepovinný.

customCDR4 - číselná nebo textová hodnota - tato hodnota bude uložena do CDR do sloupce CustomCDR4. Parametr je nepovinný.

dialerCid - telefonní číslo - telefonní číslo, které se zobrazí jako volající číslo volané lince. V případě, že dialerCid není zadán, pak se na telefonu objeví číslo 000 Dialer. Pokud si přejete jako číslo volajícího použít hodnotu z customCDR, pak použijte syntax dialerCid=customCDRX, kde X je hodnota od 1 do 4. Parametr je nepovinný.

dialerName - jméno volajícího dialeru - text, který se zobrazí jako volající jméno volané lince. V případě, že dialerName není zadán, pak se na telefonu objeví jméno Dialer, nebo číslo z parametru dialerCid. Parametr je nepovinný.

monitorFilename - název souboru - název souboru se zvukovým záznamem hovoru. Parametr je nepovinný. Pokud si přejete hovor nahrávat, pak musíte mít zapnuté nahrávání hovoru v nastavení linky.

overrideCallerId - telefonní číslo - telefonní číslo, které se zobrazí, jako číslo volajícího cílovému telefonnímu číslu, které vytočí dialer. Parametr je nepovinný, pokud není zadán, použije se číslo volajícího z dané linky.

checkExten - libovolná hodnota - pokud je vyplněna proměnná checkExten, ústředna před vytočením linky zkontroluje, zda je linka dostupná. Kontroluje se, zda je telefon registrován k ústředně a pokud ano, tak zda je linka volná, nebo obsazena.

checkIpHost - IP adresa - kontrola, zda je vytáčená linka zaregistrována ze stejné IP adresy jako je adresa v proměnné checkIpHost.

checkIpContact - IP adresa - kontrola, zda vytáčená linka obsahuje v kontaktní adrese IP adresu z proměnné checkIpContact.

Vyberte pouze jeden způsob vytočení linky (srcExtenPublicNum,srcExtenInternalNum, srcExtenId, srcSipUsername). Pokud jich vyberete více, ústředna hovor nevytočí a vrátí chybovou hlášku v JSON formátě.

{"success":"false","reason":"Use only one of next variables: srcExtenPublicNum, srcExtenInternalNum, srcExtenId, srcSipUsername"}

Příklady vytočení hovoru

Vytočení čísla se zadáním veřejného čísla linky - proměnná srcExtenPublicNum:

http://IP_PBX/api/api.php?username=voipsun&password=secretpwd&action=originate&srcExtenPublicNum=299299000&dstNum=800123456

Vytočení čísla se zadáním interního čísla linky - proměnná srcExtenInternalNum.

http://IP_PBX/api/api.php?username=voipsun&password=secretpwd&action=originate&srcExtenInternalNum=100&dstNum=800123456

Vytočení čísla se zadáním ID linky - proměnná srcExtenId.

http://IP_PBX/api/api.php?username=voipsun&password=secretpwd&action=originate&srcExtenId=5&dstNum=800123456

Vytočení čísla se zadáním SIP uživatelského jména - proměnná srcSipUsername.

http://IP_PBX/api/api.php?username=voipsun&password=secretpwd&action=originate&srcSipUsername=sip100&dstNum=800123456

Ukončení hovoru

Ukončit lze libovolný probíhající hovor vedený v ústředně. Seznam probíhajících hovorů a jména jejich kanálů lze zjistit pomocí další API metody listcalls.

Proměnné a jejich hodnoty:

PROMĚNNÁ - HODNOTA - popis

username - autorizační jméno - API uživatelé se nastavují v nabídce Nastavení -> HTTP API uživatelé.

password - autorizační heslo - přihlašovací heslo.

action - hangupcall - ústředně bude předán pokyn na ukončení probíhajícího hovoru.

channelName - kanál - jméno kanálu, na kterém probíha hovor.

Příklad ukončení hovoru

http://IP_PBX/api/api.php?username=voipsun&password=secretpwd&action=hangupcall&channelName=SIP\5555-0000b704

Seznam probíjících hovorů

Seznam probíhajících hovorů a jména jejich kanálů lze zjistit pomocí další API metody listcalls.

Proměnné a jejich hodnoty:

PROMĚNNÁ - HODNOTA - popis

username - autorizační jméno - API uživatelé se nastavují v nabídce Nastavení -> HTTP API uživatelé.

password - autorizační heslo - přihlašovací heslo.

action - listcalls - ústředně bude předán pokyn na vrácení seznamu probíhajících hovorů. Seznam je v JSON formátě.

Příklad výpisu probíhajících hovorů

http://IP_PBX/api/api.php?username=voipsun&password=secretpwd&action=listcalls

Vrácené hodnoty v JSON formátě

{"success":"true","total":"4","results":[{"channelName":"SIP/555-0000b70f","context":"incomingRouteApp-1","src":"123456789","dst":"555","duration":"529","status":"Up","accountCode":"SIP_12","sourceType":"extension","idChannel":"12"},{"channelName":"SIP/550-0000b710","context":"incomingRouteApp-1","src":"987654321","dst":"550","duration":"305","status":"Up","accountCode":"SIP_35","sourceType":"extension","idChannel":"35"},{"channelName":"SIP/upc-0000b714","context":"incomingRouteApp-1","src":"123456789","dst":"111222555","duration":"529","status":"Up","accountCode":"SIPTR_1","sourceType":"trunk","idChannel":"1"},{"channelName":"SIP/upc-0000b715","context":"incomingRouteApp-1","src":"987654321","dst":"111222550","duration":"305","status":"Up","accountCode":"SIPTR_1","sourceType":"trunk","idChannel":"1"}]}

Příposlech hovoru

Inicializovat příposlech probíhajícího hovoru je možné různými způsoby. Liší se jen v informaci, na kterou telefonní linku má ústředna zavolat předtím, než spustí příposlech zvolené linky nebo hovorového kanálu. Příposlech hovoru funguje tak, že ústředna nejprve zavolá na zvolenou linku a po vyzvednutí hovoru spustí okamžitě příposlech.

Proměnné a jejich hodnoty:

PROMĚNNÁ - HODNOTA - popis

username - autorizační jméno - API uživatelé se nastavují v nabídce Nastavení -> HTTP API uživatelé.

password - autorizační heslo - přihlašovací heslo.

action - spying - ústředně bude předán pokyn na spuštění příposlechu.

srcExtenPublicNum - veřejné číslo linky - veřejné číslo linky, na kterou ústředna zavolá před spuštěním příposlechu.

srcExtenInternalNum - interní číslo linky - interní číslo linky, na kterou ústředna zavolá před spuštěním příposlechu.

srcExtenId - ID linky - ID linky, na kterou ústředna zavolá před spuštěním příposlechu. ID lze zjistit z databáze z tabulky extensions. Tento způsob je určen především pro vývojáře informačních systémů s přístupem do databáze ústředny.

srcSipUsername - SIP uživatelské jméno - SIP uživatelské jméno linky, na kterou ústředna zavolá před spuštěním příposlechu.

srcDialplanName - název číslovacího plánu - pokud používáte v ústředně více interních linek se stejným číslem, tak je nutné upřesnit jméno číslovacího plánu, ze kterého se má vybrat interní linka. Jinak je parametr nepovinný.

dstExtenPublicNum - veřejné číslo linky - veřejné číslo linky, na které bude prováděn příposlech.

dstExtenInternalNum - interní číslo linky - interní číslo linky, na které bude prováděn příposlech.

dstExtenId - ID linky - ID linky, na které bude prováděn příposlech. ID lze zjistit z databáze z tabulky extensions. Tento způsob je určen především pro vývojáře informačních systémů s přístupem do databáze ústředny.

dstSipUsername - SIP uživatelské jméno - SIP uživatelské jméno linky, na které bude prováděn příposlech.

dstDialplanName - název číslovacího plánu - pokud používáte v ústředně více interních linek se stejným číslem, tak je nutné upřesnit jméno číslovacího plánu, ze kterého se má vybrat interní linka. Jinak je parametr nepovinný.

dstChannelName - kanál - název kanálu, na kterém probíha hovor, na kterým se bude provádět příposlech.

spyCid - telefonní číslo - telefonní číslo, které se zobrazí jako volající číslo volané lince. V případě, že spyCid není zadán, pak se na telefonu objeví číslo 000 Spy. Parametr je nepovinný.

spyName - jméno volajícího - text, který se zobrazí jako volající jméno volané lince. V případě, že spyName není zadán, pak se na telefonu objeví jméno Spy, nebo číslo z parametru spyCid. Parametr je nepovinný.

Vyberte pouze jeden způsob vytočení linky (srcExtenPublicNum,srcExtenInternalNum, srcExtenId, srcSipUsername). Pokud jich vyberete více, ústředna hovor nevytočí a vrátí chybovou hlášku v JSON formátě.

{"success":"false","reason":"Use only one of next variables: srcExtenPublicNum, srcExtenInternalNum, srcExtenId, srcSipUsername"}

Vyberte pouze jeden způsob příposlechu (dstExtenPublicNum,dstExtenInternalNum, dstExtenId, dstSipUsername, dstChannelName). Pokud jich vyberete více, ústředna hovor nevytočí a vrátí chybovou hlášku v JSON formátě.

{"success":"false","reason":"Use only one of next variables: dstExtenPublicNum, dstExtenInternalNum, dstExtenId, dstSipUsername, dstChannelName"}

Příklady příposlechu hovoru

Příposlech hovoru se zadáním veřejných čísel linek - proměnné srcExtenPublicNum a dstExtenPublicNum:

http://IP_PBX/api/api.php?username=voipsun&password=secretpwd&action=spying&srcExtenPublicNum=299299000&dstExtenPublicNum=299299555

Příposlech hovoru se zadáním interního čísla linky a veřejného čísla odposlouchávané linky - proměnné srcExtenInternalNum a dstExtenPublicNum.

http://IP_PBX/api/api.php?username=voipsun&password=secretpwd&action=spying&srcExtenInternalNum=100&dstExtenPublicNum=299299555

Příposlech hovoru se zadáním ID linky a SIP uživatelského jména odposlouchávané linky - proměnné srcExtenId a dstSipUsername.

http://IP_PBX/api/api.php?username=voipsun&password=secretpwd&action=spying&srcExtenId=5&dstSipUsernamem=sip102

Příposlech hovoru se zadáním veřejného čísla linky a názvu kanálu probíhajícího hovoru - proměnné srcSipUsername a dstChannelName.

http://IP_PBX/api/api.php?username=voipsun&password=secretpwd&action=spying&srcSipUsername=sip100&dstChannelName=SIP/102-00000001

Stav registrací SIP kanálů

Seznam zaregistrovaných SIP kanálů lze zjistit pomocí další API metody sipstatus.

Proměnné a jejich hodnoty:

PROMĚNNÁ - HODNOTA - popis

username - autorizační jméno - API uživatelé se nastavují v nabídce Nastavení -> HTTP API uživatelé.

password - autorizační heslo - přihlašovací heslo.

action - sipstatus - ústředně bude předán pokyn na vrácení seznamu stavu registrací SIP kanálů. Seznam je v JSON formátě.

Příklad výpisu probíhajících hovorů

http://IP_PBX/api/api.php?username=voipsun&password=secretpwd&action=sipstatus

Vrácené hodnoty v JSON formátě

{"total":19,"results":[{"id":12,"type":"extension_line","user":"100a","host":"(Unspecified)","port":"0","status":"UNKNOWN","useragent":"","regcontact":"","registry":null,"extension_line_id":"1"},{"id":22,"type":"extension_line","user":"101a","host":"(Unspecified)","port":"0","status":"UNKNOWN","useragent":"Linphone\/3.6.1 (eXosip2\/4.1.0)","regcontact":"sip:101a@XXX.XXX.XXX.XXX:5096;line=c5979f655562d46","registry":null,"extension_line_id":"2"},{"id":42,"type":"extension_line","user":"102a","host":"XXX.XXX.XXX.XXX","port":"5060","status":"OK (35 ms)","useragent":"snom870\/8.7.3.25.9","regcontact":"sip:102a@XXX.XXX.XXX.XXX:5060","registry":null,"extension_line_id":"4"},{"id":132,"type":"extension_line","user":"200","host":"(Unspecified)","port":"0","status":"UNKNOWN","useragent":"","regcontact":"","registry":null,"extension_line_id":"13"},{"id":142,"type":"extension_line","user":"201","host":"(Unspecified)","port":"0","status":"UNKNOWN","useragent":"","regcontact":"","registry":null,"extension_line_id":"14"},{"id":162,"type":"extension_line","user":"201b","host":"(Unspecified)","port":"0","status":"Unmonitored","useragent":"","regcontact":"","registry":null,"extension_line_id":"16"},{"id":152,"type":"extension_line","user":"202","host":"(Unspecified)","port":"0","status":"UNKNOWN","useragent":"","regcontact":"","registry":null,"extension_line_id":"15"},{"id":121,"type":"sip","user":"222998150","host":"XXX.XXX.XXX.XXX","port":"5060","status":"Unmonitored","useragent":"","regcontact":"","registry":null,"sip_id":"12"},{"id":141,"type":"sip","user":"homer","host":"XXX.XXX.XXX.XXX","port":"5060","status":"Unmonitored","useragent":"","regcontact":"","registry":null,"sip_id":"14"},{"id":122,"type":"extension_line","user":"line102b","host":"(Unspecified)","port":"0","status":"Unmonitored","useragent":"","regcontact":"","registry":null,"extension_line_id":"12"},{"id":52,"type":"extension_line","user":"tel100","host":"XXX.XXX.XXX.XXX","port":"5060","status":"Unmonitored","useragent":"SFLphone\/1.4.1","regcontact":"sip:tel100@XXX.XXX.XXX.XXX:5060","registry":null,"extension_line_id":"5"},{"id":62,"type":"extension_line","user":"tel101","host":"(Unspecified)","port":"0","status":"Unmonitored","useragent":"","regcontact":"","registry":null,"extension_line_id":"6"},{"id":72,"type":"extension_line","user":"tel102","host":"(Unspecified)","port":"0","status":"Unmonitored","useragent":"","regcontact":"","registry":null,"extension_line_id":"7"},{"id":82,"type":"extension_line","user":"tel103","host":"(Unspecified)","port":"0","status":"Unmonitored","useragent":"","regcontact":"","registry":null,"extension_line_id":"8"},{"id":92,"type":"extension_line","user":"tel104","host":"(Unspecified)","port":"0","status":"Unmonitored","useragent":"","regcontact":"","registry":null,"extension_line_id":"9"},{"id":102,"type":"extension_line","user":"tel105","host":"(Unspecified)","port":"0","status":"Unmonitored","useragent":"","regcontact":"","registry":null,"extension_line_id":"10"},{"id":111,"type":"sip","user":"siptrunk1","host":"XXX.XXX.XXX.XXX","port":"5060","status":"OK (98 ms)","useragent":"","regcontact":"","registry":null,"sip_id":"11"},{"id":11,"type":"sip","user":"siptrunk2","host":"(Unspecified)","port":"0","status":"Unmonitored","useragent":"","regcontact":"","registry":null,"sip_id":"1"},{"id":131,"type":"sip","user":"siptrunk3","host":"XXX.XXX.XXX.XXX","port":"5060","status":"OK (141 ms)","useragent":"","regcontact":"","registry":null,"sip_id":"13"}],"success":true,"_debug":false}