Zintegruj – instrukcja konfiguracji dla programistów

Zintegruj to jedna z usług dodanych FCN. Nie jest ona już dostępna w bieżącej wersji platformy (4.0). Przedstawiona instrukcja ma charakter archiwalny i dotyczy jedynie wersji 3.0 platformy, na której nie można już zakładać nowych kont.

UWAGA! Styki API/CTI są dostępne na platformie Datera

Datera Call-X Cloud to wirtualna centrala VoIP naszej firmy zintegrowana z usługą połączeń głosowych SIP Trunk. Jeżeli potrzebujesz profesjonalnego rozwiązania dla contact center lub biur, sprawdź naszą ofertę marki Datera. Centrale telefoniczne Datera mogą zostać zintegrowane z dowolnym systemem zewnętrznym, takim jak np. firmowy system CRM. Dzięki API możliwe jest np. wbudowanie funkcjonalności nawiązywania połączeń bezpośrednio z panelu CRM. Dzięki temu zwiększona zostanie efektywność pracy konsultantów. Styk CTI przekazuje do systemów zewnętrznych informacje o zdarzeniach zachodzących w centralach Datera (np. o nadchodzących połączeniach). Przykładem zastosowania może być integracja z CRM, który wyświetli wszystkie dostępne informacje na temat klienta, w czasie przyjścia połączenia. Dzięki temu konsultant uzyska podstawowe informacje, jeszcze przed rozpoczęciem rozmowy. Przejdź do strony DATERA Call-eX Cloud»

Konfiguracja usługi Zintegruj:

1. Usługa Zintegruj
2. Komunikacja Usługa sieciowa (WebService) – Zintegruj
3. Komunikacja Zintegruj – Usługa sieciowa (WebService)

1. Usługa „Zintegruj”

Usługa Zintegruj cyklicznie wywołuje wskazaną w jej konfiguracji stronę WWW, przesyłając do niej informacje o naciśniętych przez osobę dzwoniącą przyciskach na klawiaturze telefonu oraz odczytując osobie dzwoniącej zwrócony tekst. Usługa pozwala także osobie dzwoniącej nagrać nagranie głosowe oraz zainicjować nowe połączenie telefoniczne na dowolny numer telefonu.

Pod adresem http://webservices.freeconet.pl/kalkulator.php udostępniliśmy przykładową aplikację symulującą prosty kalkulator.

Do jej prawidłowego działania niezbędne jest włączenie głosów Ewy i Jacka. Aby skorzystać z kalkulatora wpisz podany powyżej adres www w pole „Wywołaj aplikację spod adresu”

**** Działanie aplikacji Kalkulator można sprawdzić pod numerem +48 (58) 7311950 ****

 

2. Komunikacja USŁUGA SIECIOWA (WEBSERVICE) – ZINTEGRUJ

Usługa sieciowa komunikuje się z usługą Zintegruj poprzez plik XML zgodny ze standardem 1.0, którego przykład jest następujący:

<?xml version=”1.0″ encoding=”utf-8″ ?>
<service_application xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xsi:noNamespaceSchemaLocation=”http://webservices.freeconet.pl/Aplikacja.xsd”>
<memory></memory>
<info>
<message type=”TTS” voice=”JAC” value=”Witaj. To jest aplikacja prezentacyjna webserwisu. Jest to
kalkulator.”/>
<message type=”TTS” voice=”EWA” value=”Za chwilę zostaniesz poproszony o podanie liczb i rodzaju
działania.”/>
</info>
<action type=”getDTMF” length=”3″ timeout=”3″>
<message type=”TTS” voice=”EWA” value=”Podaj liczbę”/>
</action>
<exit_code>0</exit_code>
</service_application>

Należy zwrócić uwagę na atrybut xsi:NoNamespaceSchemaLocation, który wskazuje na adres URL do schematu XML Schema, z którym będą walidowane zarówno pod względem semantycznym jak i syntaktycznym odpowiedzi XML zwracane przez usługę sieciową. Schemat XSD zamieszczony jest pod adresem:http://webservices.freeconet.pl/Aplikacja.xsd

Sekcja service_application składa się z następujących elementów:

• memory – sekcja, w której możliwe jest zapisanie zawartość pamięci w celu wykorzystania przy kolejnych wywołaniach Zintegruj np. numer wywołania, zapamiętane liczby. Może wystąpić tylko raz.
• info – sekcja informacyjna wiadomości, umożliwia przeczytanie dowolnego teksu na początku wywołania. Nie zawiera dodatkowych atrybutów. Może wystąpić tylko raz. W ramach sekcji info może wystąpić dowolna ilość sekcji message.
• action – sekcja umożliwia wykonanie jednej z trzech akcji (rodzaj akcji określany jest przez atrybut type). Może wystąpić tylko raz. Możliwe są następujące akcje:

1. getDTMF – pobiera znaki podane przez użytkownika z klawiatury telefonu w aktywnym polączeniu. W przypadku sekcji getDTMF konieczne jest wykorzystanie atrybutów length oraz timeout.

Parametry:

• length – maksymalna ilość znaków podanych przez użytkownika na które oczekujemy. W przypadku, gdy wartość atrybutu jest równa 0, to nie nastąpi wykonanie tej akcji. Może przyjmować wartości od 0 do 50.
• timeout – maksymalny czas (w sekundach) na wybranie znaków przez użytkownika. Może przyjmować wartości od 0 do 300.

Znaki pobierane są w trakcie odgrywania komunikatu głosowego a maksymalny czas liczony jest od momentu pobrania pierwszego znaku, bądź (jeśli nic nie wybrano) od zakończenia odgrywania komunikatu głosowego. Jeśli wciśniemy znak # to pobieranie zostanie przerwane i system wyśle do usługi sieciowej aktualnie zapamiętane znaki.

Przykład użycia:

<action type=”getDTMF” length=”3″ timeout=”3″>
<message type=”TTS” voice=”JAC” value=”Podaj liczbę”/>
</action>

2. getVOICE – nagrywa wypowiedź głosową abonenta dzwoniącego (komunikat głosowy) i przekazuje go do usługi sieciowej. W przypadku akcji getVOICE konieczne jest wykorzystanie atrybutu timeout.

Parametry:

• timeout – maksymalny czas (w sekundach) na zostawienia wiadomości głosowej. W przypadku, gdy wartość atrybutu jest równa 0, to nie nastąpi wykonanie tej akcji. Może przyjmować wartości od 0 do 300.

Przykład użycia:

<action type=”getVOICE” timeout=”60″>
<message type=”TTS” voice=”JAC” value=”Zostaw wiadomość po sygnale”/>
</action>
3. callNUMBER – usługa Zintegruj dzwoni na wskazany numer telefonu i łączy abonenta, przerywając dialog z usługą sieciowa do czasu zakończenia połączenia. W przypadku akcji callNUMBER konieczne jest wykorzystanie atrybutówtimeout oraz number.

Parametry:

• timeout – maksymalny czas (w sekundach) na podniesienie słuchawki. W przypadku, gdy wartość atrybutu jest równa 0, to nie nastąpi wykonanie akcji.
• number – numer telefonu na który nastąpi dzwonienie. Format numeru e164.

Atrybuty timeout jest opcjonalny. Dla prawidłowego działania wartość tego atrybutu powinna być ustawiona na 45.

Przykład użycia:

exit_code – Kod wyjścia. (0 – usługa Zintegruj kontynuuje działanie, inny kod – przerwanie działania i wywołanie aplikacji przypisanej do tego kodu w GUI [w ekranie konfiguracji usługi Zintegruj w panelu]). Może wystąpić tylko raz. Może przyjmować tylko nieujemne wartości całkowite.

W ramach sekcji info oraz action możliwe jest stosowanie dowolnej liczby sekcji message, umożliwiającej odegranie użytkownikowi zapowiedzi głosowej opisanej przez atrybuty:

• type – typ, przyjmuje jedną z dwóch wartości:

AUDIO: wiadomość jest pobierana z pliku. Możliwe jest użycie tylko jednej wiadomości typu AUDIO w ramach danej sekcji. Obsługiwane są tylko pliki dźwiękowe WAV o rozmiarze maksymalnie 3MB, zapisane w formacie PCM, 8000hz, 16bit mono

TTS: wiadomość jest syntezowana przez syntezator mowy. Możliwe jest użycie dowolniej liczny wiadomości typu TTS (Text To Speech), co daje możliwość czytania różnych wiadomości przy pomocy różnych głosów.

• voice – nazwa głosu. Przyjmuje jedną z 8 wartości:

JAC – synteza głosem polskim Jacka
EWA – synteza głosem polskim Ewy
JAN – synteza głosem polskim Jana
MAJA – synteza głosem polskim Maji
JEN – synteza głosem angielskim Jenifer
ERI – synteza głosem angielskim Eric
CAR – synteza głosem rumuńskim Carmen
NO – w przypadku, gdy wiadomość jest pobierana z pliku (type = AUDIO)

Uwaga! Nie jest możliwe wykorzystanie głosu, jeśli nie jest on włączony w konfiguracji usługi Zintegruj. Aby skorzystać ze znaków specjalnych w treści czytanego komunikatu należy je zakodować zgodnie z tabelką:

&amp &
&apos ’
&quot ”
&lt <
&gt >

• value – treść wiadomości albo adres URL do pliku.

Kolejność odgrywania wiadomości message jest determinowana przez kolejność ich występowania w odpowiedniej sekcji, przy czym wiadomości typu TTS są scalane do jednej wspólnej (wielogłosowej) wiadomości. Na przykład dla sekcji info:

<info>
<message type=”TTS” voice=”JAC” value=”Komunikat odegrany głosem Jaceka”/>
<message type=”AUDIO” voice=”NO” value=”http://adres_servera/zapowiedz.wav”/>
<message type=”TTS” voice=”EWA” value=”Komunikat odegrany głosem Ewy”/>
</info>

zostaną przeczytane najpierw wszystkie wiadomości TTS (w kolejności wystąpienia) a następnie wiadomość typu AUDIO.

3. Komunikacja ZINTEGRUJ – USŁUGA SIECIOWA

Usługa Zintegruj komunikuje się z usługą sieciową przy pomocy metody POST, gdzie przesyłane są następujące zmienne:

• number_from – numer telefoniczny zapisany w formacie e164
• number_to – numer telefoniczny zapisany w formacie e164
• memory – wartość zmiennej pamięć, którą przekazano do serwera albo przez GUI (początkowa zawartość pamięci) albo przez
• znacznik memory podczas komunikacji z usługą sieciową
• action_type – typ akcji dla której generowana jest ta odpowiedź.
• action_result – wynik akcji.

Poniższa tabela zawiera zestawienie typowych akcji oraz opis zwracanych wyników:

Zestawienie typowych akcji oraz opis zwracanych wyników

Zestawienie typowych akcji oraz opis zwracanych wyników
action_type	action_result
getDTMF	Znaki wybrane z klawiatury telefonu. Jeśli usługa kliencka pisana jest w języku PHP to można je pobrać w następujący sposób: if ($_P OST[’action_type’] == 'getDTMF’) { echo „Wybrano z klawiatury telefonu: „.$_P OST[’action_result’]; }
getVOICE	Czas nagrania. [ms] W przypadku akcji typu getVOICE do odpowiedzi dołączany jest także plik z nagraniem. Jeśli usługa kliencka pisana jest w języku PHP to można go pobrać w następujący sposób: if ($_P OST[’action_type’] == 'getVOICE’) { $tmp_name = $_F ILES[’file’][’tmp_name’]; $name = $_F ILES[’file’][’name’]; if (is_up loaded_file($tmp_name) && file_exists($tmp_name)) { if (!move_up loaded_file($tmp_name,”katalog_docelowy/”.$name)) { echo „plik nie został zapisany w katalogu docelowym”; } else { echo „plik zapisano w katalogu docelowym” } } echo „Czas nagrania: „.$_P OST[’action_result’]; }
callNUMBER	Status połączenia: ANSWER – połączenie zostało odebrane NOANSWER – połączenie nie zostało odebrane BUSY – strona docelowa jest zajęta ERROR – nie udało się połączyć