====== Vzdálené řízení IVR přes web ====== Nastavování URL najdete po přihlášení v menu //Nastavení účtu//-> //IVR - hlasové menu// -> //vzdálené řízení přes web// {{:ivr:ivr_vzdalene_rizeni_pres_web.png?nolink|}} {{:ivr:vzdalene_rizeni_pres_web.png?nolink|}} Všechny příklady níže toho co by mohl vrátit vaše url lze přímo vložit. Odkazy lze zkopírovat přímo z wiki test.txt, test1.txt test2.txt a podobně. ===== Názorný příklad použití ===== Na našem webu si uložíte své URL např. pod číslem 1 - viz obrázek výše. https://www.mojevlastnidomena.cz/hovor.php můžete přidat libovolný parametr, např. //pocet_neplatnych_pokusu// pro vaši potřebu. https://www.mojevlastnidomena.cz/hovor.php?pocet_neplatnych_pokusu=2 Dále v paralelním zvonění pošlete hovor na číslo *0071 . V případě příchozího hovoru Odorik nejdříve přečte hlášku dle nastavení, případně si vyžádá DTMF vstup pak zavolá zadané url, kterému přidá informace o hovoru. Tedy volané url může vypadat např. takto: https://www.mojevlastnidomena.cz/hovor.php?from=00420799799081&to=00420533533005&dtmf=60200&line=300100 případně https://www.mojevlastnidomena.cz/hovor.php?pocet_neplatnych_pokusu=2&from=00420799799081&to=00420533533005&dtmf=60200&line=300100 Vaše webová aplikace na volaném URL vyhodnotí zadané parametry a jako odpověď vrátí obyčejný text (nikoli HTML). Např. answer # zvedne hovor play:http://www.odorik.cz/w/_media/ivr:hallo.sln # radky zacinajici znakem # jsou jako poznamky ignorovany play:https://www.odorik.cz/w/_media/ivr:cink.sln # play:http://www.odorik.cz/w/_media/ivr:bzzum.sln # play:5 dial:533533619 **answer** : pokud telefonní číslo neumožňuje přehrávání hlášky místo vyzvánění, nebo pokud chceme, aby uživatel zadal nějakou volbu pomocí DTMF, musí jako první hovor zvednout. **play**: uri stáhne soubor z uri a přehraje - stáhnuté zvukové soubory cashujeme s využitím If-None-Match: http hlavičky. headrem viz https://tools.ietf.org/html/rfc7232#section-3.2, tedy jen vždy zkontrolujeme, že se soubor nezměnil. Pokud se nezměnil, nestahujeme novou kopii. Maximální velikost zvukového souboru je omezena na 2 MB a nesmí se stahovat déle než 5 sekund. V případě nedodržení jedné z těchto podmínek bude voláno na záložní číslo. **play**: 1-999 - prehraje soubor ulozeny ve `zprava zvukovych hlasek` **play2**: uri nebo 1-999, pred prehratim zvedne hovor a hlaska bude moc byt prerusena po zadani libovelneho dtmf. Vybraná DTMF volba se nikam nepřenese, slouží to hlavně proto, aby měl zákazník možnost přerušit dlouhé informační hlášky. **playnumber**: přečte číslo česky 0-100000 . Zvukové soubory jsou přehrávány v pořadí, v jakém jsou zadány. Je možné tak z jednotlivých nahrávek skládat komplikovanější celky, např. číst různé čísla skládáním z jednotlivých číslic či skládat složitější souvětí. Pro generování zvukových souborů z psaného textu můžete použít naše TTS API: http://www.odorik.cz/w/api:tts Odkazované zvukové soubory pro účely testování existují přímo na naší wiki: {{:ivr:hallo.sln|}} {{:ivr:cink.sln|}} {{:ivr:bzzum.sln|}}. Je možné použít i běžné zvukové formáty, v tom případě dojde u nás před přehráním k transkódování příkazem sox (viz níže). Pokud nepoužijete http hlavičku If-None-Match, která umožní cashování zvukových souborů u nás, bude to zvyšovat prodlevu před každým přehráním. Je možné použít jak URL jak s http tak https. Jiný příklad, který demonstruje možnost po přehrání hlášek hovor zavěsit. play:http://mojedomena.cz/soubor1.mp3 play:http://mojedomena.cz/soubor2.sln hangup Poslední příkaz může být kromě **dial** a **hangup** také **url**. Ten říká které url má být zavoláno jako další. Tedy na našem webu stačí mít nastavené jen jediné url zavolané jako první, všechna další url tedy větvení hlasového menu si určí vaše aplikace sama. Jako get parametry jsou předány potřebné údaje - stejné jako by se jinak zadávali u nás na webu(hláška, počet dtmf, timeout, ..). Tyto parametry (plus libovolné vaše vlastní parametry) se předají jako get parametry opět vaší aplikaci, navíc se k nim přidají další parametry jako informace o hovoru. play:http://mojedomena.cz/soubor1.mp3 uri:https://mojedomena.cz/ivr3.php?dtmf_count=1&annoucement_id=http://mojedomena.cz/soubor2.mp3&timeout=10&backup_number=&step=1&error_email=chyby@mojedomena.cz Odorik následně zavolá vaši aplikaci na url např. https://mojedomena.cz/ivr3.php?dtmf_count=1&annoucement_id=http://mojedomena.cz/soubor2.mp3&timeout=10&backup_number=&step=1&error_email=chyby@mojedomena.cz&from=00420799799081&to=00420533533005&dtmf=60200&line=300100 dial:533534660 Dial příkaz nemusí být poslední, následující příkazy se uplatní, pokud hovor selže (např. volaný má obsazeno) dial:*764045 dial:*300100 ==== Možná změna čísla volajícího ==== Od 22.4.2021 byla přidána možnost změny čísla volajícího na libovolné číslo daného účtu. Příkaz `setclip`, hodnota může být clip nastavený u linky nebo veřejné číslo, které musí náležet k danému účtu. Je tak možné před volaným skrýt skutečného číslo volajícího, což může být pro některé aplikace žádoucí. Přitom je možné vytvořit mapování tak, aby spolu mohli libovolně navzájem komunikovat a přitom naznali navzájem svá pravá telefonní čísla, ale jen čísla mapovací. ==== Časově omezené vyzvánění ==== *083*10533533533 - značí, že na číslo 533533533 to bude zvonit maximálně 10 vteřin, pak to bude pokračovat další akcí ve vráceném souboru. Příklad ke změně čísla volajícího i pro časově omezené zvonění: play:http://www.odorik.cz/w/_media/ivr:hallo.sln setclip:514514719 dial:*083*10533533533 play:http://www.odorik.cz/w/_media/ivr:hallo.sln dial:533533619 ==== Práce se zvukovými soubory ==== Optimální je mít soubory ve formátu sln, který používá naše ústředna. Je to důležité pokud se chcete snížit prodlevu před začátkem přehrávání zvukového soubor a nepoužíváte http hlavičku If-None-Match:, která nám umožní cashování hovorů u nás. Do formátu sln můžete převést libovolný zvukový soubor linuxovým příkazem sox: sox zdrojovy_soubor -t raw -r 8000 -e signed-integer -b 16 -c 1 cilovy_soubor.sln Převést všechny soubory v adresáři můžete v Linuxu pomocí následujícího skriptu: #!/bin/bash if [[ "$@" = "" ]] ; then echo " Script převede všechny zvukové soubory předané jako argument do formátu raw sln vhodného pro Asterisk hlasová menu. " echo " příklad, kdy budou převedeny všechny soubory s koncovkou mp3 v adresáři: x2sln *.mp3 " exit fi for file in "$@"; do file_name_without_extension="${file%.*}" sox -V "$file" -t raw -r 8000 -e signed-integer -b 16 -c 1 "$file_name_without_extension.sln" echo "nový soubor $file_name_without_extension.sln " done Příklad použití - převedeme všechny soubory v aktuálním adresáři na formát sln a uložíme jej pod stejnými jmény ale s koncovou .sln: x2sln *.mp3 Hlášky můžete nechat namluvit profesionálem, nebo využít naší služby TTS dostupné přes API. http://www.odorik.cz/w/api:tts URL může odkazovat i na soubor v jiném zvukovém formátu než sln, naše ústředna se jej pokusí zkonvertovat sama stejným příkazem sox. URL tedy může odkazovat na libovolný zvukový formát, který podporuje příkaz sox. Další info o pořizování a převádění zvukových souborů viz:[[:vytvareni_ivr]] ==== Příklad použití 1 - směrování hovorů podle PSČ zákazníka ==== Zákazník zavolá na Vaši infolinku, je mu přečtena hláška vyzývající k vyťukání poštovního směrovacího čísla. Podle PSČ přečte informaci o nejbližších pobočkách a hovor následně přepojíte na prodejce v dané oblasti. Seznam PSČ včetně okresů lze stáhnout odsud. https://www.ceskaposta.cz/ke-stazeni/zakaznicke-vystupy https://www.ceskaposta.cz/documents/10180/3738087/csv_cobce_psc.zip ==== Příklad použití 2 - informace k čísle objednávky, které zákazník zadá ==== Po zadání čísla zakázky bude přečten její stav a kde se zrovna nachází. ==== Příklad použití 3 - přečtení aktuální informace ==== Na Vašem čísle bude čtena často měnící se informace, např. aktuálně evidovaných technických potížích. (např. pokud někomu nejde internet, nelze moc předpokládat, že si to bude zjišťovat online) Převedení psaného textu do hlasové podoby můžete použít TTS přes naše API. ==== Příklad použití 4 - spravedlivé a efektivní rozdělování příchozích hovorů ==== Vaše webové aplikace může spravedlivě rozdělovat příchozí hovory mezi více lidí, tak aby nikdo nebyl přetěžován. Historii hovorů i právě obsazené linky (právě probíhající hovory) lze zjistit v reálném čase přes API a podle toho rozhodnout další směrování hovoru. Pokud volá někdo opakovaně během dne, může se vaše aplikace postarat o to, že bude přednostně spojen s tím stejným člověkem, protože ten má jeho případ pravděpodobně stále ještě v paměti a vyřízení ta bude efektivnější. Jiné směrování hovorů můžete použít pro známé důležité zákazníky, nebo pak věčné potížisty nebo hovory ze skrytých čísel. Hovor je možné směrovat i na SIP jméno, kde je možné provést nastavení jako paralelním zvonění včetně zpožděného paralelního zvonění, aby se nestalo, že hovor zůstane nespojen, např. kvůli tomu, že si vybraný člověk právě někam odskočil. ==== Příklad použití 5 - informační služby - náhrada čísel 906 XXX XXX běžným číslem, zákazník si předplácí přímo u provozovatele služby ==== Lze tak provozovat např. věštírnu, nebo technickou podporu. Spojeny budou jen hovory zákazníků s předplaceným kreditem, z kterého bude strháváno, ostatním bude přečtena hláška o nedostatečném kreditu, nebo nutnosti se registrovat a předplatit. Hovor je možné přerušit přes API. Provoz je tak výrazně levnější, není nutné vyplácet vysokou provizi mobilním operátorům, protože zákazník platí přímo. Vhodné především pro pravidelné zákazníky. ====== web hook - jen informace o existenci příchozího hovoru ====== Řízení přes web můžete použít i v případě, že nepotřebujete nic "řídit" (vždy se zavolá stejné číslo), ale jen se Vaše aplikace potřebuje dozvědět o tom, že příchozí hovor přišel, např. proto, aby měla přehled o zmeškaný/vyřízených hovorech. Nezapomeňte ale pro každou linku zřídit "jiné" url, kde bude použito správné záložní číslo pro případ, že by Vaše webová stránka měla výpadek. ====== web hook - informace o tom, že hovor začal zvonit a byl zdvihnut ====== Číslo URL 99 má zvláštní význam, bude voláno vždy, když bude nějaký SIP hovor daného uživatele začne zvonit a bude zdvednut. Příklad použití. Mám firemní informační systém a chci, aby se telefonistovi, který hovor vyřizuje, otevřelo okno s kartou volajícího zákazníka v okamžiku, kdy hovor zdvihne. Nastavím si tedy URL pod číslem 99, které bude voláno kdykoli, kdy bude zdvihnut hovor na některé z linek tohoto uživatele. Kromě čísla linky v síti Odorik.cz, na které byl hovor přijat, bude předáno i telefonní číslo volajícího. Předáváno je to pomocí GET parametrů. //From// je pro číslo volajícího a //line// je číslo linky, která byla zdvihnutá. Použít se to dá tak, že volaný bude již v době vyzvánění může automaticky vidět informace o volajícím klientovi - např. historii komunikace a jméno. Jiná jednodužší možnost je si tuhle informaci vyžádat přes API. Příklad výsledného URL (pod URL 99 je uloženo jen https://neexistuje.cz/test.php, voláno ale bude níže) ZVONENI https://neexistuje.cz/test.php?from=799799799&line=300100&ringing=yes ANSWER https://neexistuje.cz/test.php?from=799799799&line=300100&answered=yes ==== Informace o zmeškaném hovoru ==== Zmeškaný hovor, je takový příchozí hovor, který nebyl nakonec zdvihnut na konkrétní lince. I takové hovory může Vaše webová aplikace zaevidovat. ====== webhook - informace o tom že byl hovor ukončen ====== po ukonceni hovoru `tukne` do zadaneho uri. s parametrama napr: https://www.neexistuje.cz/56464646?from=00420799799016&to=00420533533016&line=387170&duration=4&status=CANCEL&sip_in_callid=1049390500-15953-2821%40BJC.BGI.C.BAB Použit je url s číslem 98 ====== novinky k 13.10.2020 ====== WebHook - info o začátku zvonění Prepošleme GET parametry zadané ve webovém rozhraní nebo v příkazu uri:. Přidán nový přikaz **uri:**, v, kterém můžete vtátit uri i s parametrama, stejně jako by se vytočilo *007X Očekávané parametry: backup_number error_email dtmf_cout annoucement_id timeour Uri může přijit s libovolnýma paramatrama, které přepošleme. Očekávané parametry, které nepřijdou s příkazem uri: budou nahrazeny původnímy z webového rozhraní. Parametr **annoucement_id** muže být url na soubor stejně jako u př9kazu play: Cachujeme vzdálené audio soubory s If-None-Match: headrem viz [[https://tools.ietf.org/html/rfc7232#section-3.2]], není potřeba při každém volaní soubor stahovat a konvertovat. Nyni muzete libovolne bez omezeni vetvit Vase IVR .........