Originácia volaní cez API

Pobočkové ústredne UniPBX umožňujú origináciu (zostavenie) volaní prostredníctvom API. Po prijatí povelu cez API pobočková ústredňa najprv zavolá prvej strane volania - označenej ako A - a čaká na zdvihnutie. Keď strana A volanie zdvihne, pobočková ústredňa zavolá strane B a následne obe strany A aj B navzájom spojí. Strana A počuje spájanie so stranou B tak, akoby volala sama, teda počuje aj vyzváňanie pred zdvihnutím alebo hlášku telefónnej siete o nedostupnom alebo neexistujúcom čísle.

Pre používanie originácie je potrebné najprv vytvoriť v administrácii ústredne konto pre origináciu volaní, nastaviť mu prihlasovacie meno, heslo a prípadne tiež ACL (zoznam povolených IP adries). V nastavení konta je možné prednastaviť hodnoty jednotlivých parametrov, ktoré sa použijú pri originácii volaní (hodnoty týchto parametrov potom nie je potrebné odovzdávať cez API). Ak je hodnota parametera nastavená v aj originačnom konte a je odovzdaná aj cez API, prednosť má a použije sa hodnota odovzdaná cez API. Prihlasovacie meno a heslo k originačnému kontu sa pri použití API odovzdáva prostredníctvom HTTP autentifikácie.

Informáciu o skončení volania a jeho dôvode je možné získať prostredníctvom HTTP(S) volania z API na užívateľom zadané URL, nastavené v originačnom konte v poli "Externé URL". Takto je možné získať unikátne ID volania a následne podľa neho cez API stiahnuť aj nahrávku volania (ak bolo nahrávanie zapnuté).

Zostavenie nového volania cez API

Pre zostavenie (originovanie) nového volania je potrebné poslať požiadavku napríklad v takomto tvare:

https://www.mojoperator.sk/api/pbxoriginate/originate-account/originate?anum=%2B421901001122&cid=%2B421850335577&bnum=11&bcid=%2B421901001122&bcname=Meno+Klienta&extid=444


Toto API volanie spôsobí, že ústredňa zavolá strane A na číslo +421901001122 a bude sa prezentovať číslom volajúceho +421850335577. Keď strana A dvihne, ústredňa zavolá stranu B na číslo (klapku) 11, bude sa prezentovať číslom volajúceho +421901001122 a zároveň menom "Meno Klienta". Predpokladajme, že na klapke 11 je callcentrum, ktoré volanie ihneď prevezme, stranu A pozdraví uvítacou hláškou a ďalej vybaví hovor. Keďže tomuto hovoru je cez API nastavené externé ID (444), po skončení volania API pošle detaily volania na Externé URL nastavené v originačnom konte a pre rozlíšenie volania odovzdá aj externé ID (444).

Pre originovanie volania cez API musia byť nastavené tieto povinné parametre (buď prostredníctvom ich nastavenia v originačnom konte, alebo ich odovzdaním pri volaní API):

  • anum - volané číslo na strane A
  • bnum - volané číslo na strane B (bude sa volať, keď A zdvihne)

Pre upresnenie môžu byť použité tieto nepoviné parametre:

  • cid - číslo volajúceho (Caller ID)
  • cname - meno volajúceho (Caller Name)
  • bcid - číslo volajúceho (Caller ID) pre stranu B, ak má byť iné ako cid
  • bcname - meno volajúceho (Caller Name) pre stranu B, ak má byť iné ako cname
  • extid - externé (užívateľské) číselné ID (integer) pre označenie tohto volania; ak je nastavené, API odovzdá stav volania na Externé URL
  • billcode1 / billcode2 / billcode3 - užívateľské hodnoty (alfanumerické) pre rozúčtovanie nákladov
  • waittime - maximálna dĺžka čakania na dvihnutie volania (v sekundách)
  • maxtime - maximálna dĺžka hovoru od momentu dvihnutia stranou A (v sekundách)
  • hangupalert - ak sa nastaví na 0, vypne sa hlasové oznamovanie chýb pri volaní na A-stranu (to urýchli spracovanie volaní napr. na neexistujúce alebo nedostupné čísla)
  • monitor - ak sa nastaví na "a" alebo "b", na zvolenej strane sa zapne nahrávanie volania

Formát volaných telefónnych čísel (parametre anum a bnum) je rovnaký ako pri volaní z ústredne prostredníctvom telefónneho prístroja. Teda ak sa pri volaniach z ústredne do verejnej siete volí pred číslom úvodná 0 (nula), aj pri volaní cez API by mala byť k číslam pridaná úvodná 0. Univerzálne riešenie pri použití API je volať na čísla v medzinárodnom tvare začínajúce znakom "+" (tak ako v príklade vyššie), je však potrebné mať nastavenú ústredňu tak, aby podporovala aj tento tvar čísel. Pamätajte, že znak "+" má v HTTP URL špeciálny význam (znamená medzeru), a preto sa znak "+" musí v URL zakódovať do tvaru %2B, tak ako v príklade vyššie.

Čísla volajúceho (parametre cid a bcid) môžu byť zadané v národnom alebo medzinárodnom tvare, teda 0850335577, 00421850335577 alebo +421850335577. POZOR - pri volaní do verejnej siete musí byť číslo volajúceho priradené k príslušnej zmluve, inak verejná sieť číslo volajúceho odmietne a nahradí ho niektorým z čísel priradených k zmluve. Aj v tomto prípade odporúčame použiť univerzálny medzinárodný tvar s "+" na začiatku.

Meno volajúceho (parametre cname a bcname) má zmysel nastavovať iba pri volaní v rámci pobočkovej ústredne. Cez verejnú sieť sa tieto údaje neprenášajú.

Získanie stavu originovaného volania

Pri originácii volania môže byť zadaný nepovinný číselný parameter extid (externý indentifkátor), napr. poradové číslo volania. Ak je nastavený extid, po skončení volania dôjde k notifikácii cez API na Externé URL, zadané v konfigurácii originačného konta. Ako súčasť URL môžu byť použité značky, ktorých obsah sa pri volaní URL nahradí aktuálnou hodnotou. Celé Externé URL potom môže vyzerať napríklad takto:

https://www.my-server.example.com/originate/response?extid={extid}&hangup={hangup}&astatus={astatus}&acause={acause}&abillsec={abillsec}&bstatus={bstatus}&bcause={bcause}&bbillsec={bbillsec}

V Externom URL môžu byť použité tieto značky:

  • {extid} - externý identifikátor - slúži pre jednoznačné previazanie výsledku s originovaným volaním
  • {hangup} - označenie strany A alebo B, ktorá ukončila originované volanie (položila ako prvá)
  • {astatus} a {bstatus} - stav volania na príslušnej strane, napr. "ANSWER" (volaný zdvihol), "BUSY" (volaný má obsadené), "NOANSWER" (volaný nezdvihol do uplynutia waittime), "CONGESTION" alebo "CHANUNAVAIL" (chyba v spojení)
  • {acause} a {bcause} - číselný kód dôvodu ukončenia volania podľa odporúčania ITU-T Q.850, napr. 1 (volané číslo neexistuje), 16 (normálne ukončenie), 17 (číslo obsadené), 20 (číslo mimo dosahu), 21 (volaný odmietol volanie). Kód sa preberá od cieľovej alebo tranzitnej telefónnej siete, pri volaní do niektorých sietí nie je presný alebo nie je vôbec poskytnutý, odporúčame ho teda používať iba ako doplňujúcu informáciu k {astatus} a {bstatus}.
  • {astart} a {bstart} - timestamp začiatku volania na príslušnej strane
  • {aanswer} a {banswer} - timestamp odpovede na volanie (zdvihnutia volania) na príslušnej strane
  • {aend} a {bend} - timestamp skončenia volania na príslušnej strane
  • {adialsec} a {bdialsec} - trvanie spájania volania (vytáčanie + vyzváňanie) na príslušnej strane, v sekundách
  • {abillsec} a {bbillsec} - trvanie účtovanej časti volania (bez vytáčania a vyzváňania) na príslušnej strane, v sekundách
  • {acallsec} a {bcallsec} - trvanie celého volania (vytáčanie + vyzváňanie + hovor) na príslušnej strane, v sekundách
  • {amonitor} a {bmonitor} - hodnota 1 znamená, že volanie na príslušnej strane bolo nahrávané


Dobré rady k API originácii

Aby originácia volaní fungovala k plnej spokojnosti všetkých strán, pri navrhovaní vašich aplikácií a používaní tejto funkcie pamätajte na to, že strana A po zdvihnutí volania počuje najprv spájanie so stranou B, čo môže byť pre nepoučenú volanú osobu na strane A veľmi zvláštne.

Ak chcete cez API spojiť volanie medzi vašim pracovníkom a zákazníkom, na strane A by mal byť obvykle váš pracovník a na strane B zákazník. Váš pracovník zvolí originovanie hovoru cez API, následne mu zazvoní jeho telefón, pričom pracovník už podľa čísla volajúceho vie, že ide o originovaný hovor z ústredne. Po zdvihnutí bude v telefóne počuť priebeh spájania so zákazníkom a prípadnú hlášku telefónnej siete (ak je zákazník nedostupný, číslo neexistuje a podobne). Pre zákazníka na strane B to bude úplne štandardný hovor a ani nerozozná, že bol originovaný cez API.

Ak chcete obvolať väčší počet zákazníkov a nemáte dosť pracovníkov, ktorí by čakali pri telefóne kým zákazník prijme hovor, je možné strany navzájom prehodiť. Na strane A bude zákazník, a celý priebeh spájania so zákazníkom sa udeje na ústredni, bez účasti vášho pracovníka. Neexistujúce čísla alebo čísla mimo dosahu budú obvolané bez toho, aby to vyžadovalo čo len sekundu času vášho pracovníka (dôvod skončenia hovorov sa dozviete cez API volanie na Externé URL). Avšak v tomto prípade je veľmi dôležité, že strana B musí byť schopná okamžite bez meškania prevziať hovor, pozdraviť stranu A a komunikovať s ňou. Na strane B teda musí byť buď call-centrum s automatickou odpoveďou a uvítacou hláškou, alebo telefónny prístroj so zapnutou funkciou Auto-Answer a človekom pripraveným ihneď komunikovať. Nebol by dobrý nápad použiť v takomto scenári ako stranu B čokoľvek, čo nie je schopné ihneď prevziať hovor - napríklad mobilný telefón, pretože zákazník na strane A by ťažko chápal, prečo po dvihnutí prichádzajúceho volania počuje v telefóne ticho, vyzváňanie, prípadne prečo sa mu pri prichádzajúcom hovore ozvalo, že volané číslo je dočasne nedostupné.