Specyfikacja API bramki SMS/MMS/IVR wersja 1.5 Piotr Isajew (pki@ex.com.pl) 14 września 2011 c 2010-2011 EXPERTUS, http://www.ex.com.pl
Spis treści 1 Wprowadzenie 3 1.1 Parametry konfiguracyjne................................ 3 1.2 Standardy kodowania.................................. 4 1.3 Reprezentacja dat.................................... 4 2 Postać komunikatów 5 2.1 Komunikaty przesyłane od klienta do bramki..................... 5 2.1.1 Walidacja komunikatów............................ 6 2.1.2 Wysyłanie wiadomości SMS.......................... 6 2.1.3 Wysyłanie wiadomości MMS......................... 7 2.1.4 Zapytanie o stan wysyłanej wiadomości.................... 9 2.2 Komunikaty przesyłane od bramki do klienta..................... 9 2.2.1 Odpowiedź na żądanie wysłania wiadomości................. 9 2.2.2 Odpowiedź na zapytanie o stan wiadomości.................. 10 2.3 Dodatkowe uwagi.................................... 10 2.3.1 Ograniczenia czasowe przy wysyłaniu wiadomości.............. 10 2.3.2 Dostarczanie potwierdzeń odebrania wiadomości............... 11 2.3.3 Ograniczenie wielkości komunikatu...................... 11 2.4 Komunikacja dwukierunkowa............................. 11 2.4.1 Odbieranie odpowiedzi na wysłane wiadomości................ 11 3 Obsługa wiadomości głosowych 13 3.1 Zlecenie wysłania wiadomości TTS/IVR........................ 13 3.1.1 Wysyłanie prostej wiadomości TTS...................... 13 3.1.2 Zlecanie połączenia IVR............................ 14 3.2 Otrzymywanie informacji o połączeniu IVR...................... 14 3.2.1 Dostarczanie nagrania rozmowy........................ 14 4 Diagnostyka błędów 15 4.1 Błędy o charakterze ogólnym.............................. 15 4.2 Błędy o charakterze szczegółowym........................... 15 1
5 Wykorzystanie do komunikacji poczty elektronicznej 17 5.1 Błędy i retransmisje................................... 17 6 Zabezpieczenie komunikacji 18 6.1 Komunikacja HTTP................................... 18 6.2 Komunikacja z użyciem poczty elektronicznej..................... 18 7 Przykłady 19 7.1 Wysyłanie wiadomości SMS za pomocą programu wget................ 19 7.2 Wysyłanie wiadomości SMS za pomocą PHP..................... 20 7.3 Odbiór wiadomości przychodzących za pomocą PHP................. 20 7.4 Wysyłanie komunikatów do bramki za pomocą poczty elektronicznej......... 21 8 Historia zmian 22 8.1 Zmiany w wersji 1.5.................................. 22 8.2 Zmiany w wersji 1.4.................................. 22 2
1. Wprowadzenie API działa w oparciu o proste komunikaty XML przekazywane za pomocą metody HTTP POST. Komunikaty XML mogą być również przekazywane za pomocą internetowej poczty elektronicznej. API umożliwia: wysyłanie wiadomości SMS z losowych numerów 9-cyfrowych wysyłanie wiadomości SMS z predefiniowanego numeru, w tym numeru alfanumerycznego (tzw. nadpis ) wysyłanie wiadomości MMS z losowych numerów 9-cyfrowych wysyłanie wiadomości głosowych w przypadku, gdy wiadomość SMS jest kierowana na numer stacjonarny otrzymywanie informacji o stanie wiadomości zleconych do wysłania otrzymywanie wiadomości SMS przesłanych w odpowiedzi na wiadomości wysłane z systemu wysyłanie wiadomości głosowych (TTS), oraz realizacja sesji IVR W zależności od wariantu podpisanej umowy nie wszystkie z powyższych funkcji mogą być dostępne. Domyślnie komunikacja z wykorzystaniem API jest jednokierunkowa transakcje są inicjowane przez klienta i potwierdzane synchronicznie przez bramkę. Przy tego typu dostępie nie ma możliwości odbierania odpowiedzi na wysłane SMSy. Na życzenie klienta istnieje możliwość skonfigurowania komunikacji dwukierunkowej, umożliwiającej asynchroniczne powiadamianie klienta o zmianie stanu wysyłanych wiadomości oraz otrzymywanie wiadomości SMS przesyłanych w odpowiedzi na wysłane wiadomości (patrz też 2.4). 1.1 Parametry konfiguracyjne Konfiguracja dostępu HTTP wymaga określenia dla klienta następujących parametrów: nazwa użytkownika i hasło klienta wykorzystywane do uwierzytelniania żądań. adres IP, z którego będą przesyłane żądania. Ponadto, jeśli dla klienta została aktywowana funkcja przekazywania potwierdzeń dostarczenia wiadomości lub odpowiedzi, konieczne jest określenie adresu URL po stronie klienta, na który będą przekazywane potwierdzenia dostarczenia wiadomości (por. 2.4). 3
W przypadku dostępu e-mail klient powinien określić adres poczty elektronicznej, który będzie obsługiwał komunikację z API. Dodatkowo skonfigurowanie dostępu będzie wymagało określenia parametrów, o których mowa w części 6. 1.2 Standardy kodowania Ilekroć w komunikatach API przekazywane są teksty, oczekuje się, że będą one kodowane z użyciem kodowania UTF-8. 1.3 Reprezentacja dat Jeżeli nie zostało jednoznacznie podane, że jest inaczej, wszystkie daty są podawane z wykorzystaniem czasu lokalnego dla bramki (CET/CEST). 4
2. Postać komunikatów Komunikaty przekazywane są w postaci obiektów XML, przekazywanych jako dane w metodzie HTTP POST na docelowy adres URL. 2.1 Komunikaty przesyłane od klienta do bramki Wszystkie komunikaty przekazywane od klienta do bramki mają następującą postać: <?xml version="1.0" encoding="utf-8"?> <gateway-request type="..."> <request-auth> <partnerlogin>testuser</partnerlogin> <partnerpassword>testpassword</partnerpassword> </request-auth> <request-data>......... </request-data> </gateway-request> Atrybut type określa rodzaj przesyłanego komunikatu, determinujący, jakie elementy mogą się pojawić w części request-data. Rodzaje przesyłanych komunikatów pokazane są w tablicy 2.1. Jeżeli żądanie POST przesłane do serwera nie zawiera komunikatu o podanej wcześniej postaci, przesyłany komunikat ma błędy składniowe, czy też dane uwierzytelniające nie są poprawne, to brama odpowiada komunikatem ERROR, po którym opcjonalnie następuje informacja o rodzaju błędu. Typ komunikatu sms-send-request mms-send-request ivr-send-request sms-status-request mms-status-request ivr-status-request Znaczenie żądanie wysłania wiadomości SMS żądanie wysłania wiadomości MMS żądanie wysłania wiadomści TTS/zainicjowania sesji IVR zapytanie o stan wiadomości SMS, których wysłanie zostało wcześniej zlecone zapytanie o stan wiadomości MMS, których wysłanie zostało wcześniej zlecone zapytanie o stan zleconego połączenia TTS/IVR Tablica 2.1: Komunikaty przesyłane od klienta 5
Komunikat sms-send-request sms-status-request mms-send-request mms-status-request Lokalizacja schematu http://www.superbramka.pl/ns/1_3/sms-send-request.xsd http://www.superbramka.pl/ns/1_3/sms-status-request.xsd http://www.superbramka.pl/ns/1_3/mms-send-request.xsd http://www.superbramka.pl/ns/1_3/mms-status-request.xsd Tablica 2.2: Lokalizacja schematów umożliwiających weryfikację przesyłanych dokumentów W przypadku, kiedy żądanie przesłane do bramki jest poprawne, bramka odpowiada komunikatem o postaci: <?xml version="1.0" encoding="utf-8"?> <gateway-response type="...">......... </gateway-response> Element gateway-response zawiera elementy odnoszące się do poszczególnych elementów zawartych w części request-data, którego dotyczy odpowiedź. Atrybut type determinuje rodzaj elementów które zawarte są w odpowiedzi i obecnie może przyjmować następujące wartości: sms-send-response tj. odpowiedź dotyczy żądania wysłania SMSów sms-status-response tj. odpowiedź dotyczy zapytania o stan wcześniej wysłanych SMSów mms-send-response odpowiedź dotyczy żądanie wysłania MMSów, oraz mms-status-response odpowiedź dotyczy zapytania o stan wcześniej wysłanych MMSów ivr-send-response odpowiedź na zlecenie wysłania komunikatu IVR ivr-status-response odpowiedź dotyczy zapytania o stan zleceonego połączenia IVR 2.1.1 Walidacja komunikatów Poprawność składniowa komunikatów przesyłanych od klienta do bramki może być zweryfikowana przy użyciu walidatora XML pozwalającego na walidację z użyciem schematów XML rekomendowanych przez W3C (xsd). Adresy, pod którymi opublikowano odpowiednie schematy zawiera tablica 2.2. 2.1.2 Wysyłanie wiadomości SMS W przypadku wysyłania wiadomości SMS żądanie gateway-request powinno być typu sms-sendrequest. Wówczas część request-data zawiera jeden lub więcej elementów sms-send-request, o postaci: <sms-send-request> <!-- elementy wymagane --> <message-id>12346562</message-id> <msisdn>601601601</msisdn> <sms-text>example of very simple send-request</sms-text> 6
<!-- elementy opcjonalne --> <dont-send-before>2010-03-01 17:00</dont-send-before> <tts-text>text</tts-text> <src-addr>test</src-addr> </sms-send-request> W żądaniu muszą wystąpić wszystkie elementy oznaczone jako elementy wymagane, a ponadto mogą wystąpić dowolne z elementów oznaczonych jako elementy opcjonalne. Znaczenie poszczególnych elementów jest następujące: message-id liczba naturalna jednoznacznie identyfikująca wiadomość w systemie klienta msisdn numer telefonu, na który ma być dostarczona wiadomość, w formacie 123456789 lub +48123456789 sms-text treść wiadomości (dopuszcza się znaki z zestawu ASCII, oraz polskie znaki diakrytyczne) dont-send-before pozwala na wskazanie najwcześniejszego momentu, w którym system może wysłać wiadomość tts-text alternatywna treść wiadomości, którą należy odczytać przez system TTS jeżeli numer docelowy zostanie zidentyfikowany jako numer stacjonarny (maks. 4000 znaków) src-addr wskazanie numeru, z którego ma zostać wysłana wiadomość (brak tego elementu jest tożsamy z wysłaniem wiadomości z dowolnego numeru 9-cyfrowego) 2.1.3 Wysyłanie wiadomości MMS Postać komunikatu wykorzystywanego do wysłania wiadomości MMS zależy od sposobu jego definicji. Ogólna struktura żądania przedstawiona została poniżej: <mms-send-request> <message-id>4444</message-id> <msisdn>48501501501</msisdn> <message-template> <!-- specyfikacja szablonu wiadomości --> </message-template> <message-subject>temat</message-subject> <message-data> <!-- specyfikacja zawartości wiadomości --> </message-data> </mms-send-request> Szablon wiadomości System umożliwia wysyłanie wyłącznie wiadomości ze zdefiniowanym szablonem SMIL. Może to być jeden z szablonów zdefiniowanych w webowym interfejsie administracyjnym, bądź szablon zdefiniowany w treści MMS a. W przypadku użycia szablonu zdefiniowanego w interfejsie administracyjnym element message-template powinien zawierać identyfikator tego szablonu, np.: <message-template> <template-id>11</template-id> </message-template> 7
Możliwe jest również podanie treści szablonu SMIL bezpośrednio w komunikacie, np.: <message-template> <smil-data> <smil> <head> <layout> <region id="a" top="0" left="0" height="100%" fit="meet"/> </layout> </head> <body> <par> <img src="obrazek_1.jpg" region="a"/> </par> </body> </smil> </smil-data> </message-template> Oczekuje się, że w zdefiniowanym szablonie źródła poszczególnych elementów będą podane jako nazwy plików (bez katalogów) z rozszerzeniem odpowiadającym typom plików. Nazwy plików nie muszą odnosić się do istniejących plików w systemie klienta mają charakter wirtualny. Zawartość wiadomości Dla każdego z obiektów zdefiniowanych w szablonie SMIL w części message-data musi zostać określona zawartość tego obiektu. Zawartości poszczególnych obiektów określa się w odpowiadających im elementach message-part: <message-data> <message-part type="rodzaj specyfikacji" name="nazwa obiektu"> <!-- zawartość obiektu --> </message-part> </message-data> Atrybut name określa obiekt szablonu, którego dotyczy dany element message-part (np.: obrazek1.jpg). Nazwa powinna być podana jako nazwa pliku (bez ścieżki katalogów). Rozszerzenie powinno umożliwiać ustalenie typu MIME zawartości pliku. Atrybut type określa sposób określenia zawartości obiektu i może przyjmować następujące wartości: base64 zawartość binarna obiektu jest podana bezpośrednio wewnątrz elementu message-part kodowana zgodnie z base64. href wewnątrz elementu message-part znajduje się adres URL z pod którego można pobrać zawartość binarną obiektu text obiekt jest obiektem tekstowym i wewnątrz elementu message-part znajduje się treść tego obiektu System nie limituje w żaden sposób ilości oraz wielkości poszczególnych obiektów, należy jednak pamiętać, że całkowita wielkość jednej wiadomości MMS jest ograniczona do 280KB. 8
2.1.4 Zapytanie o stan wysyłanej wiadomości Zapytanie o stan wysłanej wiadomości powinno, w części request-data zawierać jeden lub więcej elementów sms-status-request, (lub mms-status-request) o postaci: <sms-status-request> <message-id>1243124314</message-id> </sms-status-request> gdzie message-id jest liczbą naturalną jednoznacznie identyfikującą wiadomość w systemie klienta. 2.2 Komunikaty przesyłane od bramki do klienta Wszystkie komunikaty przesyłane przez serwer do klienta mają postać: <?xml version="1.0" encoding="utf-8"?> <gateway-response type="...">...... </gateway-response> Atrybut type determinuje zawartość elementów odpowiedzi. Może on obecnie przyjmować następujące wartości: sms-send-response oznacza, że gateway-response zawiera elementy typu sms-send-response sms-status-response oznacza, że gateway-response zawiera elementy typu sms-status-response mms-send-response zawiera odpowiedź na żądanie wysłania MMS a (mms-status-response) mms-status-response element gateway-response zawiera elementy mms-status-response status-notification jest używany przy powiadomieniach asynchronicznych; w tym przypadku element gateway-response może zawierać zarówno elementy mms-status-response jak i smsstatus-response 2.2.1 Odpowiedź na żadanie wysłania wiadomości W odpowiedzi na żądanie wysłania wiadomości generowana jest odpowiedź typu sms-send-response, składająca się z elementów sms-send-response (analogicznie dla MMS i IVR) o postaci: <sms-send-response> <message-id>121212</message-id> <result>ok ERROR</result> </sms-send-response> Zawartość elementu result informuje o wyniku żądania wysłania w odniesieniu do danej wiadomości: OK oznacza, że wiadomość została przyjęta do wysłania ERROR oznacza, że wiadomość nie została zaakceptowana do wysłania; może to być wynikiem awarii systemu lub błędu w żądaniu wysłania wiadomości (np. brak wymaganych elementów, zła postać numeru, wykorzystanie id wykorzystanego wcześniej do wysłania innej wiadomości) 9
2.2.2 Odpowiedź na zapytanie o stan wiadomości Odpowiedź na zapytanie o stan wysłania wiadomości zawiera elementy sms-status-response (analogiczna sytuacja dla wiadomości MMS), o postaci: <gateway-response type="sms-status-response"> <sms-status-response> <message-id>12346562</message-id> <part>0</part> <status>pending processing sent confirmed paused failed not found</status> <status-time>yyyy-mm-dd HH:MM</status-time> <sent-time>yyyy-mm-dd HH:MM</sent-time> <delivered-time>yyyy-mm-dd HH:MM</delivered-time> </sms-status-response> </gateway-response> Element part podaje numer kolejny części wiadomości (wartość istotna w przypadku gdy dochodzi do podziału wiadomości na części). Element status określa stan wiadomości. Dozwolone wartości: pending wiadomość została przyjęta przez system do wysłania ale jeszcze nie została wysłana processing jest podejmowana próba wysłania wiadomości sent wiadomość została wysłana do sieci GSM confirmed otrzymano potwierdzenie dostarczenia wiadomości paused administracyjnie wstrzymano przetwarzanie wiadomości przez system failed próba wysłania wiadomości zakończyła się niepowodzeniem i nie będą podejmowane kolejne próby wysłania tej wiadomości not found wiadomość o podanym message-id nie została znaleziona w systemie Elementy status-time, sent-time, delivered-time zawierają znaczniki czasowe dotyczące wiadomości. Ich znaczenie jest następujące: status-time określa moment ostatniej zmiany stanu wiadomości sent-time określa moment wysłania wiadomości delivered-time określa moment dostarczenia wiadomości do odbiorcy (w przypadku jeżeli wiadomość była wysłana z żądaniem potwierdzenia i otrzymano potwierdzenie) 2.3 Dodatkowe uwagi 2.3.1 Ograniczenia czasowe przy wysyłaniu wiadomości W przypadku, jeżeli w żądaniu wysłania wiadomości nie wystąpi żadne graniczenie czasu, system, będzie próbował wysłać wiadomość od momentu przyjęcia zgłoszenia, do skutku lub wystąpienia nieodwracalnego błędu. Jeżeli w żądaniu ograniczenie dont-send-before ma wartość wcześniejszą niż moment wysyłania żądania, to jego wartość zostanie skorygowana na moment wysyłania żądania. 10
2.3.2 Dostarczanie potwierdzeń odebrania wiadomości System umożliwia wysyłanie wiadomości z żądaniem potwierdzenia ich dostarczenia. Należy przy tym zwrócić uwagę na to, że techniczna implementacja potwierdzenia zależy od sieci i telefonu odbiorcy wiadomości. W szczególności nie otrzymanie potwierdzenia pomimo żądania nie oznacza, że wiadomość nie została dostarczona do odbiorcy. Na życzenie klienta istnieje możliwość skonfigurowania komunikacji dwukierunkowej. Przy takiej konfiguracji system dostarcza powiadomienia o zmianie stanu poszczególnych wiadomości. Powiadomienia są wysyłane za pomocą metody HTTP POST na adres URL wskazany przez klienta. W treści żądania przesyłany jest komunikat gateway-response typu sms-status-response. W przypadku komunikacji dwukierunkowej dopuszczalna jest sytuacja, w której bramka wysyła do systemu klienta komunikat z potwierdzeniem tylko raz. W przypadku, gdy system klienta jest nieosiągalny lub komunikacja zostanie przerwana bramka nie ma obowiązku ponawiać próby przesłania potwierdzenia. System klienta powinien jednak móc obsłużyć sytuację, w której w ramach komunikatu gateway-response otrzyma potwierdzenie tej samej wiadomości więcej niż jeden raz. 2.3.3 Ograniczenie wielkości komunikatu Ze względów wydajnościowych, w komunikatach zawierających żądania przesyłane od klienta do bramki, wprowadzone jest odgórne ograniczenie ilości elementów zawartych w części request-data. Na dzień tworzenia niniejszego dokumentu to ograniczenie wynosi 1000. W przypadku przekroczenia tego ograniczenia, bramka odpowie komunikatem ERROR i całe żądanie zostanie nieprzetworzone. 2.4 Komunikacja dwukierunkowa Do skonfigurowania komunikacji dwukierunkowej konieczne jest podanie przez klienta adresu URL, na który bramka będzie przekazywać komunikaty. Bramka będzie wówczas przesyłać komunikaty opisane w 2.2 w treści żądania HTTP POST przesłanego na wskazany przez klienta adres. Jeżeli serwer HTTP obsługujący połączenie ze strony klienta wygeneruje w odpowiedzi kod HTTP 200, to uznaje się, że dane zostały dostarczone i ich transmisja nie będzie ponawiana. 2.4.1 Odbieranie odpowiedzi na wysłane wiadomości Przekazywanie do klienta odpowiedzi na wysłane wiadomości odbywa się poprzez użycie dodatkowego typu komunikatu gateway-response incoming-message. Komunikat gateway-response typu incoming-message zawiera elementy dla poszczególnych wiaodmości przychodzących. W ramach jednego komunikatu gateway-response mogą być przesyłane różne rodzaje wiadomości przychodzących. Obecnie mogą to być elementy: incoming-sms-message dla przychodzących wiadomości SMS incoming-ivr-message wysyłany w celu przekazania akcji wykonanych przez rozmówcę w trakcie sesji IVR Każdy z elementów tego komunikatu reprezentuje jedną wiadomość odebraną przez system i zawiera następujące elementy: message-id liczba naturalna jednoznacznie identyfikująca przekazywaną wiadomość w systemie SMS 11
msisdn numer telefonu, z którego odebrano wiadomość received-time moment odebrania wiadomości przez system SMS sms-text treść wiadomości 12
3. Obsługa wiadomości głosowych Począwszy od wersji 1.4 API obsługuje przesyłanie wiadomości głosowych z wykorzystaniem systemu IVR. Wiadomości tego typu mogą być przesyłane zarówno na numery komórkowe jak i stacjonarne w Polsce. System może być wykorzystany do wysyłania zarówno prostych komunikatów TTS (tj. odpowiednik wiadomości SMS) jak i do zlecania wykonania połączeń w ramach bardziej rozbudowanej komunikacji IVR. Ten drugi przypadek wymaga wcześniejszej konfiguracji odpowiedniego scenariusza IVR po stronie bramki. Dla sesji IVR możliwe jest otrzymywanie informacji o akcjach wykonanych przez rozmówcę (ściślej o ścieżce, przez którą przeszedł użytkownik w menu IVR), oraz nagrania z rozmowy. Dalsza treść tego rozdziału zakłada znajomość ogólnych zasad funkcjonowania API dla wiadomości SMS i MMS, zgodnie z ich opisem w rozdziale 2. 3.1 Zlecenie wysłania wiadomości TTS/IVR Zlecenie wysłania wiadomości IVR odbywa się poprzez przesłanie do bramki komunikatu gatewayrequest typu ivr-send-request. W skład elementów ivr-send-request wchodzą następujące elementy: message-id, msisdn, dont-send-before o znaczeniu takim samym jak dla innych komunikatów wysyłania wiadomości wykorzystywanych w API scenario-id opcjonalny identyfikator scenariusza IVR (przydzielany przez dostawcę) tts-argument argument tekstowy do wykorzystania przez syntetyzator mowy 3.1.1 Wysyłanie prostej wiadomości TTS Przy wysyłaniu prostej wiadomości TTS należy: 1. Pominąć w komunikacie element scenario-id. 2. Podać dokładnie jeden element tts-argument. System zadzwoni na wskazany numer telefonu i odczyta treść komunikatu podanego w elemencie tts-argument. 13
3.1.2 Zlecanie połaczenia IVR W celu wykorzystania tej funkcji konieczne jest wcześniejsze skonfigurowanie przez dostawcę scenariusza IVR o charakterystyce uzgodnionej z klientem. Po skonfigurowaniu scenariusza dostawca przydziela identyfikator scenariusza, który należy przekazywać jako wartość elementu scenario-id w komunikacie ivr-send-request. W zależności od scenariusza komunikat może zawierać sekwencję jednego lub więcej elementów tts-argument, których treść jest odtwarzana przez syntetyzator mowy w ustalonych punktach scenariusza. 3.2 Otrzymywanie informacji o połaczeniu IVR W celu otrzymywania informacji o połączeniu IVR 1 konieczne jest przygotowanie przez klienta skryptu do odbierania komunikatów zgodnie z procedurą opisaną w części 2.4.1. Nie ma możliwości uzyskania tych informacji poprzez wysyłanie do serwera zapytań ivr-status-request. Do klienta kierowane są wówczas komunikaty incoming-ivr-message zawierające następujące elementy: message-id liczba naturalna jednoznacznie identyfikująca wiadomość z punktu widzenia bramki IVR client-message-id liczba naturalna jednoznacznie identyfikująca wiadomość w systemie klienta (odpowiada wartości message-id w komunikacie ivr-send-request received-time moment odebrania wiadomości (tj. moment wykonania połączenia do klienta) ivr-path (element opcjonalny) węzły w systemie IVR przez które przeszedł użytkownik w trakcie rozmowy (w postaci NAZWA1->NAZWA2->...->NAZWAn, gdzie NAZWAn to nazwa n-tego węzła drzewa IVR w uzgodnionym scenariuszu) voice-recording (element opcjonalny) umożliwia przesyłanie nagrania rozmowy (więcej w p. 3.2.1) 3.2.1 Dostarczanie nagrania rozmowy Informacje odnośnie nagrania połączenia są dostarczane w elemencie voice-recording. Sposób dostarczenia nagrania wynika z wartości atrybutu type elementu voice-recording. Obecnie jedyna dopuszczalna wartość tego atrybutu to base64 która oznacza, że nagranie dostarczone jest bezpośrednio jako wartość elementu voice-recording, jako dane WAV reprezentowane w kodowaniu Base64. W kolejnych wersjach API dopuszcza się wprowadzenie innych wartości atrybutu type, które będą się odnosić do innych sposobów dostarczania nagrania do systemu klienta. 1 Dotyczy wyłącznie zdefiniowanych scenariuszy IVR. Nie ma możliwości otrzymywania tej informacji dla prostych komunikatów TTS. 14
4. Diagnostyka błędów Błędy aplikacji lub przetwarzania danych są raportowane do systemu klienta na dwóch poziomach: ogólnym, oraz szczegółowym. 4.1 Błędy o charakterze ogólnym Błędy o charakterze ogólnym dotyczą następujących sytuacji: próba komunikacji z niedozwolonego adresu IP, lub przy użyciu niepoprawnych danych logowania niemożliwość poprawnej interpretacji całości komunikatu przesłanego do serwera (np. komunikat nie zawiera wymaganych elementów) błąd w oprogramowaniu API W przypadku wystąpienia błędu o charakterze ogólnym bramka odpowiada na żądanie HTTP POST klienta przesyłając komunikat tekstowy ERROR, po którym opcjonalnie, w nowej linii następuje treść informująca o charakterze błędu. Jeżeli z treści błędu nie wynika sposób postępowania w celu jego usunięcia i błąd ma charakter powtarzalny, należy skontaktować się z dostawcą celem ustalenia przyczyny i usunięcia błędu. 4.2 Błędy o charakterze szczegółowym Błędy o charakterze szczegółowym dotyczą poszczególnych elementów *-send-request komunikatu i są raportowane w odpowiednim elemencie *-send-response. W przypadku wystąpienia takiego błędu element result odpowiedniego komunikatu *-send-response będzie miał wartość ERROR. Dodatkowo w treści komunikatu może pojawić się dodatkowy element error zawierający dodatkowe informacje odnośnie charakteru błędu który wystąpił. Przykład: <gateway-response type="ivr-send-response"> <ivr-send-response> <message-id>21</message-id> <result>error</result> <error> <code>201</code> </error> </ivr-send-response> </gateway-response> 15
Kod Znaczenie 100 nieznana przyczyna wystąpienia błędu (w razie powtarzalnego występowania tego błędu prosimy o kontakt z działem technicznym w celu ustalenia przyczyny) trwałe odrzucenie żądania 200 nie należy ponawiać próby wysłania, brak bardziej szczegółowych informacji o przyczynach odrzucenia 201 nieprawidłowy adres docelowy (np. numer telefonu) 202 nieprawidłowy adres źródłowy (np. próba wysłania wiadomości z nadpisu, który nie został aktywowany dla danego klienta) 203 treść wiadomości zawiera niedozwolone znaki 204 przekroczona dozwolona ilość znaków w treści wiadomości 205 nieprawidłowa wartość elementu campaign-id 206 przekroczony rozmiar wiadomości (dla wiadomości MMS) 207 ponowna próba wysłania wiadomości z tym samym id 210 typ wiadomości nie dozwolony dla danego klienta 220 w treści żądania brak parametru wymaganego do zrealizowania zlecenia tymczasowe odrzucenie wiadomości 300 brak szczegółowych informacji o przyczynach odrzucenia, można ponowić próbę wysłania w późniejszym terminie 301 przekroczony miesięczny limit wysyłanych wiadomości, prosimy skoncentrować się z działem sprzedaży w celu zwiększenia limitu Tablica 4.1: Wykaz kodów błędów wykorzystywanych przez XML API W ramach elementu error występuje zawsze element code zawierający liczbowy kod informujący o rodzaju błędu. Dodatkowo może wystąpić element info zawierający tekstowy opis przyczyny wystąpienia błędu. Kod błędu jest trzycyfrową liczbą dodatnią. W zależności od wartości kodu, błąd może mieć charakter przejściowy (tj. wystąpienie błędu nie oznacza, że ponowne próby wysłania tej samej wiadomości w niezmienionej postaci również zakończy się błędem), lub ostateczny (tj. kolejna próba wysłania tej samej, niezmienionej wiadomości, również zostanie odrzucona). Błędy, które mają charakter tymczasowy, to błędy, których najbardziej znacząca cyfra kodu błędu to 3. Wszystkie pozostałe błędy mają charakter ostateczny. Szczegółowa lista kodów wraz z ich znaczeniem została przedstawiona w tablicy 4.1. Pozostałe wartości kodów są zarezerwowane do użycia w przyszłości i ich wystąpienie należy traktować jak wystąpienie błędu ostatecznego (za wyjątkiem kodów 3xx). 16
5. Wykorzystanie do komunikacji poczty elektronicznej Na życzenie klienta może zostać skonfigurowany dostęp do API wykorzystujący, jako nośnik komunikatów API, internetową pocztę elektroniczną. Postać wykorzystywanych komunikatów jest zgodna z opisem zamieszczonym w rozdziale 2. Jeżeli wykorzystywany jest ten rodzaj dostępu, komunikaty API powinny być przekazywane w treści wiadomości pocztowych przesyłanych między ustalonymi adresami poczty elektronicznej systemu i klienta. Treść wiadomości nie powinna zawierać żadnych dodatkowych elementów poza komunikatem XML i podpisem cyfrowym. Temat wiadomości nie jest istotny (jest ignorowany). API przesyła komunikaty do klienta z pustym polem tematu. W celu uruchomienia dostępu z wykorzystaniem poczty elektronicznej klient powinien podać adres e- mail, z którego będą przesyłane komunikaty do API. System klienta powinien być skonfigurowany w taki sposób, żeby wiadomości przesyłane przez API na ten adres były w sposób poprawny odbierane. Ponadto, dla tego rodzaju dostępu wymagane jest zabezpieczenie komunikacji zgodnie z regułami określonymi na stronie??. 5.1 Błędy i retransmisje Ponieważ komunikacja z wykorzystaniem poczty elektronicznej ma charakter asynchroniczny, należy wziąć pod uwagę, że opóźnienia w przekazywaniu potwierdzeń do klienta mogą być rzędu pojedynczych minut. Dlatego ewentualne retransmisje wiadomości, których wysłanie zostało zlecone API, ale dla których klient nie otrzymał komunikatu potwierdzającego przyjęcie przez API, powinny odbywać się w rozsądnych, uwzględniających bezwładność poczty elektronicznej, interwałach czasowych. Nie wydaje się, żeby interwały krótsze niż 30 minut były w tym przypadku uzasadnione. API nigdy nie oczekuje potwierdzenia komunikatów przesłanych na adres poczty elektronicznej systemu klienta. Ewentualne retransmisje, w przypadku zakłócenia komunikacji na poziomie IP, odbywają się zgodnie ze specyfikacją protokołu SMTP. Klient odpowiada za takie skonfigurowanie swojego systemu pocztowego, żeby komunikaty dostarczone przez API były poprawnie odbierane. 17
6. Zabezpieczenie komunikacji 6.1 Komunikacja HTTP W celu zabezpieczenia komunikacji dostęp do bramki będzie możliwy tylko za pośrednictwem tunelu IPsec. W związku z tym w celu udostępnienia połączenia konieczne będzie określenie przez klienta adresu IP zakończenia tunelu po stronie klienta, oraz skonfigurowanie firewalla i routingu w taki sposób, żeby był możliwy dostęp do bramki SMS. 6.2 Komunikacja z użyciem poczty elektronicznej W przypadku gdy dostęp do API odbywa się z wykorzystaniem poczty elektronicznej wymagane jest zabezpieczenie komunikacji poprzez podpisanie cyfrowe komunikatu API (dokumentu XML) za pomocą PGP. Podpis powinien być weryfikowalny przy użyciu klucza publicznego przekazanego do dostawcy na etapie konfiguracji usługi. Podpis powinien być wykonany przy użyciu klucza wygenerowanego dla adresu e-mail, z którego wysłano komunikat API. Obecna wersja API nie obsługuje standardu PGP/Mime. Podpisy cyfrowe powinny być składane bezpośrednio w treści wiadomości e-mail. Podpisy na komunikatach wysyłanych przez bramkę są weryfikowalne przy użyciu klucza publicznego opublikowanego pod adresem http://api.superbramka.pl/gpg/api_pubkey.asc. Na życzenie klienta komunikaty mogą być szyfrowane przy użyciu PGP. 18
7. Przykłady Niniejszy rozdział zawiera przykłady związane z testowaniem i integracją API. Dla uproszczenia i maksymalnej przejrzystości przykłady nie zawierają żadnej obsługi błędów. W przykładach, które tego wymagają nie uwzględniono również specjalnego kodowania znaków specjalnych, które mogą się pojawić w treści SMS a podczas rzeczywistej eksploatacji. Autorzy rozwiązań bazujących na przykładach z tego rozdziału powinni wziąć powyższe pod uwagę. 7.1 Wysyłanie wiadomości SMS za pomoca programu wget Do przesłania bramce SMS żądania wykorzystującego API można się posłużyć programami takimi jak wget czy curl. Na przykład polecenie: wget -O- -q --post-file=req.xml http://api-test/rbroker powoduje przesłanie do serwisu testowego bramki żądania zawartego w pliku req.xml, i wypisanie na standardowym wyjściu odpowiedzi bramki. Jeżeli plik req.xml ma postać: <?xml version="1.0" encoding="utf-8"?> <gateway-request type="sms-send-request"> <request-auth> <partnerlogin>test</partnerlogin> <partnerpassword>test</partnerpassword> </request-auth> <request-data> <sms-send-request> <message-id>5</message-id> <msisdn>+48601601601</msisdn> <sms-text>przykladowy sms</sms-text> </sms-send-request> </request-data> </gateway-request> to przykładowa odpowiedź systemu będzie miała postać: <?xml version="1.0" encoding="utf-8" standalone="no"?> <gateway-response type="sms-send-response"> <sms-send-response> <message-id>5</message-id> <result>ok</result> </sms-send-response> </gateway-response> Co oznacza, że system przyjął wiadomość i będzie podejmował próby jej wysłania. 19