Differences

This shows you the differences between two versions of the page.

--- ivr:vzdalene_rizeni_pres_web [2019/03/20 15:50] – [web hook - informace o tom, že byl hovor zdvihnut] root
+++ ivr:vzdalene_rizeni_pres_web [2024/09/13 15:10] (current) – [Názorný příklad použití] root
@@ Line 1: / Line 1: @@
 ====== Vzdálené řízení IVR přes web ======
-Příchozí hovory nyní můžete řídit přímo z Vaší webové aplikace.
+Nastavování URL najdete po přihlášení v menu //Nastavení účtu//-> //IVR - hlasové menu// -> //vzdálené řízení přes web//
-Vaše webová stránka se dozví o příchozím hovoru zavoláním Vašeho URL, které si nastavíte po přihlášení v menu //Nastavení účtu//-> //IVR - hlasové menu// -> //vzdálené řízení přes web// .
-Stačí pak hovor v paralelním zvonění poslat na telefonní číslo *007XX kde XX je číslo URL z rozsahu 1-99.
-Příklad možné URL včetně automaticky přidaných parametrů GET:
+{{:ivr:ivr_vzdalene_rizeni_pres_web.png?nolink|}}
-http://www.mojevlastnidomena.cz/hovor.php?from=00420799799081&to=00420533533005&dtmf=60200&line=300100
+{{: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ě.
-Vaše aplikace se tak dozví, kdo volá (from), kam volá (to), číslo linky Odorik (line), případně i DTMF volbu uživatele.
-Vaše aplikace na základě těchto informací rozhodne, jak dále bude hovor pokračovat, jednoduše vrátí telefonní číslo pro další směrování hovoru.
+===== Názorný příklad použití =====
+Na našem webu si uložíte své URL např. pod číslem 1 - viz obrázek výše.
+<file>
+https://www.mojevlastnidomena.cz/hovor.php
+</file>
+můžete přidat libovolný parametr, např. //pocet_neplatnych_pokusu// pro vaši potřebu.
+<file>
+https://www.mojevlastnidomena.cz/hovor.php?pocet_neplatnych_pokusu=2
+</file>
+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:
+<file>
+https://www.mojevlastnidomena.cz/hovor.php?from=00420799799081&to=00420533533005&dtmf=60200&line=300100
+</file>
+případně
+<file>
+https://www.mojevlastnidomena.cz/hovor.php?pocet_neplatnych_pokusu=2&from=00420799799081&to=00420533533005&dtmf=60200&line=300100
+</file>
-Telefonní číslo pro pokračování může být opět ve tvaru *007XX, tedy může to být pokračování interaktivního hlasového menu ovládaná Vaší webovou aplikací.
-Ono URL vrátí obyčejný text (nikoli HTML).
+Vaše webová aplikace na volaném URL vyhodnotí zadané parametry a jako odpověď vrátí obyčejný text (nikoli HTML).
+Např.
 <file txt test.txt>
+answer # zvedne hovor
 play:http://www.odorik.cz/w/_media/ivr:hallo.sln
-#play:https://www.odorik.cz/w/_media/ivr:cink.sln
+# radky zacinajici znakem # jsou jako poznamky ignorovany
-#play:http://www.odorik.cz/w/_media/ivr:bzzum.sln
+play:https://www.odorik.cz/w/_media/ivr:cink.sln
-play:5
+# play:http://www.odorik.cz/w/_media/ivr:bzzum.sln
+# play:5
 dial:533533619
 </file>
+**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.
-# komentar,prikaz bude ignorovan
+**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: uri stahne soubor z uri a prehraje
+**play**: 1-999 - prehraje soubor ulozeny ve `zprava zvukovych hlasek`
-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.
-play2: uri nebo 1-999, pred prehratim zvedne hovor a hlaska bude moc byt prerusena po zadani libovelneho dtmf.
+**playnumber**: přečte číslo česky 0-100000 .
-Odkazované zvukové soubory pro účely testování existují přímo na naší wiki: {{:ivr:hallo.sln|}} {{:ivr:cink.sln|}} {{:ivr:bzzum.sln|}},
+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í.
-URL s příkazy výše, které je možné pro otestování zadat je http://www.odorik.cz/w/_export/code/ivr:vzdalene_rizeni_pres_web?codeblock=0
+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
-Použít URL s https je také možné, jistější je se ale vyhnout potencionálním problémům s certifikáty v budoucnu a použít jen http.
+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.
@@ Line 54: / Line 72: @@
 </file>
-==== Nepovinný příkaz play a práce se zvukovými soubory ====
+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.
+<file txt test2.txt>
+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
+</file>
+Odorik následně zavolá vaši aplikaci na url např.
+<file>
+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
+</file>
+<file txt test3.txt>
+dial:533534660
+</file>
+Dial příkaz nemusí být poslední, následující příkazy se uplatní, pokud hovor selže (např. volaný má obsazeno)
+<file txt test3.txt>
+dial:*764045
+dial:*300100
+</file>
+==== 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í:
+<file txt test3.txt>
+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
+</file>
+==== Práce se zvukovými soubory ====
-Nově od prosince 2017 podporujemě kromě příkazu dial i příkazy play a hangup.
-Zvukové soubory jsou stahovány z poskytnutého URL a 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 a pod.
-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.
-Optimální je mít soubory ve formátu sln, do kterého si můžete převést libovolný soubor příkazem sox:
+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:
 <code bash>
@@ Line 99: / Line 155: @@
-Další info o pořizování a převádění zvukových souborů viz: http://wiki.4smart.cz/doku.php/stranky_uzivatelu_4smart:vytvareni_ivr?s[]=sox#jak_prevest_do_formatu_vhodneho_pro_asterisk
+Další info o pořizování a převádění zvukových souborů viz:[[:vytvareni_ivr]]
-https://www.youtube.com/embed/t4lSO4R5-h8?hl=cs&fs=1
-==== Kam zadat URL s řídícími příkazy? ====
-Vaše URL s příkazy, které se mají provést, nastavíte zde:
-Nastavování URL najdete po přihlášení v menu //Nastavení účtu//-> //IVR - hlasové menu// -> //vzdálené řízení přes web//
-{{:ivr:vzdalene_rizeni_pres_web.png?nolink|}}
-Otestovat funkčnost příkladu můžete vložením URI přímo na naši wiki např. test.txt  výše:
-http://www.odorik.cz/w/_export/code/ivr:vzdalene_rizeni_pres_web?codeblock=0
 ==== Příklad použití 1 -  směrování hovorů podle PSČ zákazníka ====
@@ Line 120: / Line 164: @@
 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á ====
@@ Line 142: / Line 187: @@
 Ří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 byl hovor zdvihnut  ======
+====== 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ý hovor SIP hovor daného uživatele zdvihnut. 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á.
+Čí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)
 <code>
+ZVONENI
+https://neexistuje.cz/test.php?from=799799799&line=300100&ringing=yes
+ANSWER
 https://neexistuje.cz/test.php?from=799799799&line=300100&answered=yes
 </code>
@@ Line 158: / Line 209: @@
 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 .........