API rozhraní

VoIPSUN PBX poskytuje jednoduché HTTP API pro iniciaci hovorů (click2call), ukončování hovorů, zobrazení aktivních hovorů a správu callcentra. Další funkce lze přizpůsobit na míru požadavkům klienta.

Autentizace

Všechny API požadavky vyžadují:

• username — přihlašovací údaje API uživatele (konfigurace v Nastavení → HTTP API uživatelé)
• password — heslo pro autentizaci

Operace s hovory

Akce originate

Iniciuje nový hovor — nejprve vytočí vybranou klapku, poté spojí s cílovým číslem.

Parametry:

Parametr	Popis
action	originate
dstNum	Cílové telefonní číslo
srcExtenPublicNum	Veřejné číslo zdrojové linky (použijte pouze jeden z parametrů src*)
srcExtenInternalNum	Interní číslo zdrojové linky
srcExtenId	ID zdrojové linky
srcSipUsername	SIP uživatelské jméno zdrojové linky
dialplanName	Povinné pokud více linek sdílí stejné interní číslo
customCDR1-4	Volitelná vlastní pole v CDR záznamu
dialerCid, dialerName	Vlastní CallerID
monitorFilename, monitorPath	Konfigurace nahrávání hovoru
checkExten, checkIpHost, checkIpContact	Ověření dostupnosti linky

Příklad požadavku:

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

Akce dial

Směruje hovory přes předdefinované odchozí směrovací kontexty.

Parametry:

Parametr	Popis
action	dial
outrouteName nebo outrouteId	Výběr odchozího směrování
context	Povinný Asterisk dialplan kontext
hangupContext	Volitelný kontext při selhání hovoru

Příklad požadavku:

http://IP_PBX/api/api.php?username=voipsun&password=secretpwd&action=dial&dstNum=800123456&outrouteName=outgoing&context=processing

Ukončení hovoru

Ukončí aktivní hovor podle názvu kanálu.

Parametry:

Parametr	Popis
action	hangupcall
channelName	Identifikátor kanálu ze seznamu aktivních hovorů

Příklad požadavku:

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

Monitoring hovorů

Seznam aktivních hovorů

Vrací JSON seznam probíhajících hovorů s názvy kanálů, trváním, stavem a identifikátory.

Parametry:

Parametr	Popis
action	listcalls

Pole JSON odpovědi:

Pole	Popis
channelName	Identifikátor kanálu
context	Dialplan kontext
src, dst	Zdrojové a cílové číslo
duration	Délka hovoru v sekundách
status	Stav spojení (Up)
accountCode	Identifikátor účtu

Odposlech hovorů

Iniciuje monitoring aktivních hovorů připojením supervizora k poslechu.

Parametry:

Parametr	Popis
action	spying
srcExtenPublicNum / srcExtenInternalNum / srcExtenId / srcSipUsername	Zdrojová linka supervizora (pouze jeden)
dstExtenPublicNum / dstExtenInternalNum / dstExtenId / dstSipUsername / dstChannelName	Cílový hovor (pouze jeden)
spyCid, spyName	CallerID supervizora

Upozornění

Použijte pouze jeden parametr z každé skupiny (src*, dst*), jinak systém vrátí chybu 300/301.

Stav SIP kanálů

Parametry:

Parametr	Popis
action	sipstatus

Pole odpovědi:

Pole	Popis
user	SIP uživatelské jméno
host	IP adresa registrace
status	Stav spojení (OK, UNKNOWN, Unmonitored)
useragent	Informace o zařízení
regcontact	Registrační kontaktní adresa

Správa agentů callcentra

Přihlášení agenta

http://IP_PBX/api/api.php?username=voipsun&password=secretpwd&action=agentlogin&srcExtenInternalNum=100&agentNumber=1000&agentPin=1234

Parametry:

Parametr	Popis
action	agentlogin
agentNumber	Identifikátor agenta
agentPin	PIN pro autentizaci

Odhlášení agenta

Parametr	Popis
action	agentlogout
agentNumber, agentPin	Identifikace agenta

Pauza / Zrušení pauzy

Parametr	Popis
action	agentpause nebo agentunpause
agentNumber, agentPin	Identifikace agenta

Přidání do fronty

Parametr	Popis
action	agentadd
queueName	Identifikátor fronty
penalty	Úroveň priority

Odebrání z fronty

Parametr	Popis
action	agentremove
queueName	Identifikátor fronty

Stav agenta

Vrací stav agenta: přihlášen/odhlášen, volný/obsazený/v hovoru/na hold/nedostupný.

Parametr	Popis
action	agentstatus
agentNumber, agentPin	Identifikace agenta

Stav fronty

Poskytuje kompletní metriky fronty včetně detailů agentů, čekacích dob, úrovně služeb a čekajících volajících.

Parametr	Popis
action	queuestatus
queueName	Cílová fronta

Správa nahrávek

Přesunutí nahrávky

Přesune a volitelně přejmenuje nahrávku hovoru.

Parametr	Popis
action	moverecord
cdrId	Identifikátor CDR záznamu
filename	Nový název souboru (volitelné)
path	Cílový adresář (volitelné, alespoň jeden z filename/path je povinný)

Příklad požadavku:

http://IP_PBX/api/api.php?username=voipsun&password=secretpwd&action=moverecord&cdrId=10000&filename=record.wav&path=/archive/2024

Chybové kódy

Obecné chyby

Kód	Popis
100	Neautorizovaný uživatel nebo nedostatečná oprávnění
110	Neznámý parametr action
120	Chybějící povinné parametry

Chyby originate (200–228)

Kód	Popis
200	Konfliktní parametry výběru linky
201–203	Linka, dialplan nebo konfigurace nenalezena
210–211	Nesouhlasí IP adresa
220–228	Stavy nedostupnosti linky (nedostupná, obsazená, vyzvání atd.)

Chyby dial (250)

Kód	Popis
250	Odchozí směrování nenalezeno

Chyby spying (300–312)

Kód	Popis
300	Konfliktní zdrojové parametry
301	Konfliktní cílové parametry
302–304	Problémy se zdrojovou linkou/dialplanem
310–312	Problémy s cílovou linkou/dialplanem

Chyby agenta (500–636)

Kód	Popis
500–504	Autentizace agenta nebo vyhledání linky
550	Selhání autentizace při odhlášení
580, 590	Selhání autentizace při pauze/zrušení pauzy
600–601	Selhání správy fronty
610–636	Chyby ověření stavu a dostupnosti agenta

Chyby nahrávek (800–812)

Kód	Popis
800	CDR záznam nenalezen
801	Žádná data nahrávky v CDR
810–812	Problémy s oprávněním nebo přístupem k souborům

Formát JSON odpovědí

Úspěšná odpověď:

{"success":"true"}

Chybová odpověď:

{"success":"false","errno":"100","reason":"Unauthorized user or bad permissions"}