HTTPS XML API / Pobieranie wiadomości przychodzących
Kolejną funkcją dostępną dzięki zdalnemu dostępowi jest możliwość pobierania odpowiedzi nadesłanych od odbiorców klienta, wiadomości SMS nadesłanych w ramach usługi numer dostępowy oraz numer dostępowy indywidualny.
Wywołanie adresu
Aby przy pomocy zdalnej obsługi pobrać odpowiedzi na wiadomości oraz inne wiadomości przychodzące należy wywołać określony adres URL metodą POST lub GET. Przykładowo adres w przeglądarce wyglądać może następująco:
https://api1.serwersms.pl/zdalnie/index.php?login=demo&haslo=demo&akcja=sprawdz_odpowiedzi&data_od=2007-08-26%2013:53&data_do=2007-10-30%2022:05&numer=%2B48500600700,%2B48509693455&typ=1&pokaz_powiazanie=1&odczyt=1
Dostępne parametry
| Parametr | Typ | Przykładowa wartość lub format | Opis |
|---|---|---|---|
| akcja | String | sprawdz_odpowiedzi | Aby sprawdzić stan wiadomości SMS należy umieścić tutaj wartość „sprawdz_odpowiedzi”. |
| login | String | Login | Login klienta używany do logowania się w Panelu Klienta |
| haslo | String | Haslo | Hasło klienta używane do logowania się w Panelu Klienta |
| numer | String | %2B48500600700 | Numer lub numery telefonów oddzielane przecinkami |
| data_od oraz data_do | DateTime | ISO np. „2007-10-24 17:46:00” |
Przedział czasowy który ma zostać wyświetlony. Jest to data i godzina wysłania wiadomości |
| typ | Integer | 1 – odpowiedzi SMS 2 – SMSy z numeru dostępowego 3 – SMSy z NDI 4 – SMSy z Premium SMS 5 – Odbiór MMS 6 - 2waySMS |
Typ wiadomości jakie mają być wyświetlone. Jeśli parametr pozostanie pusty, zwrócone zostaną wiadomości przychodzące z wszystkich kategorii. |
| ndi | String | Numer NDI w formacie +48500600700 | Parametr opcjonalny pozwalający na odfiltrowanie tych wiadomości przychodzących które trafiły na określony numer NDI (jeśli np. klient dysponuje kilkoma numerami na jednym koncie) |
| odczyt | Integer | 1, 0 lub brak | Oznacza wiadomość jako przeczytaną (nie będzie więcej zwracana przez API) |
| tylko_nowe | Integer | 1, 0 lub brak | Zwraca jedynie nowe wiadomości które nie zostały oznaczone jako odczytane (parametr odczyt=1) |
| pokaz_powiazanie | Integer | 1, 0 lub brak | Zwraca dodatkowy atrybut smsid informujący o powiązaniu odpowiedzi na SMS ECO+ z wiadomością wychodzącą SMS ECO+. Opcja dostępna jedynie dla odpowiedzi na SMS ECO+. |
Parametry oznaczone pogrubieniem są obowiązkowe. Pozostałe są opcjonalne.
Zwrot odpowiedzi
Wywołanie powyższego adresu może wygenerować np. taką odpowiedź:
<?xml version="1.0" encoding="UTF-8"?>
<SerwerSMS login="demo">
<SMS id="ECO3445" numer="+48500600700" data="2007-09-26 10:59:36" tresc="Przyjade o 16." smsid="7856df58sd"/>
<SMS id="ND57323" numer="+48500600700" data="2007-09-26 11:20:00" tresc="Bede wczesniej"/>
<SMS id="NDI8873" numer="+48500600700" data="2007-10-27 12:55:09" tresc="Dzieki za informacje"/>
<MMS id="MMS4445" numer="+48500058777" data="2011-06-27 13:31:49" temat="jakis temat MMS">
<Zalacznik id="764" nazwa="text_0002.txt" contenttype="text/plain">SmFrYXMgdGFtIGplc3pjemUgd2lhZGFvbW9zYw==
</Zalacznik>
</MMS>
</SerwerSMS>
Objaśnienie poszczególnych sekcji XML
| Znacznik XML | Opis |
|---|---|
| <SMS numer="NUM" data="DATA" tresc="TRESC"/> | Zawiera numer nadawcy wiadomości SMS (NUM), datę (DATA) oraz treść wiadomości SMS (TRESC) |
| <MMS id="IDMMS" numer="NUM" data="DATA"> <Zalacznik id="ID" nazwa="NAZWA" contenttype="CT"> DANE </Zalacznik> (...) </MMS> | Zawiera numer nadawcy wiadomości MMS (NUM), datę (DATA) oraz załączniki zawarte w tagu „Zalacznik”. Mieści się tam identyfikator załącznika (ID), nazwa pliku (NAZWA), Content-type (CT) oraz dane zakodowane w base64 (DANE) |
Przekazywanie wiadomości przychodzących na zdefiniowany URL Klienta
Odpowiednie opcje dostępne są w Panelu Klienta:
Odpowiedzi ECO: Wyślij wiadomość > HTTPS XML API > Odpowiedzi SMS ECO
ND/SC: Odbiór wiadomości > Numery współdzielone > [wybrane hasło/prefiks] > Prześlij dalej
NDI/SCI: Odbiór wiadomości > Numery indywidualne > [wybrane hasło/prefiks] > Prześlij dalej
MMS: Odbiór wiadomości > Odebrane wiadomości > MMS > Opcje dodatkowe
2waySMS: Odbiór wiadomości > Odebrane wiadomości > 2waySMS > Opcje dodatkowe
Najczęściej wymagana jest jednorazowa konfiguracja.
Przed wysłaniem informacji do klienta, parametry te są podmieniane z danymi dotyczącymi określonej wiadomości. System wywołuje URL klienta podmieniając parametry na odpowiednie wartości i w zależności od ustawień, może zweryfikować czy odbiór wiadomości po stronie Klienta odbył się poprawnie. Jeśli włączona jest opcja weryfikacji a skrypt po stronie Klienta nie zwróci wymaganych wartości, system będzie ponawiał wywołanie URLa kolejno 5, 10, 15 i 60ciu minutach. Jeśli mimo wszystko z jakichś względów wiadomość nie zostanie prawidłowo przekazana, w każdej chwili można pobrać listę nowych wiadomości za pośrednictwem zapytania przez HTTPS XML API. Informacje o odpowiedziach na SMS ECO+, ND/SC oraz NDI/SCI przesyłane są metodą GET. Dla wiadomości MMS dane przesyłane są metodą POST.
Zalecane ustawienia
Zalecane jest, aby wiadomości przychodzące wysyłane były na adres URL Klienta który jest zdefiniowany w Panelu Klienta. Opcja ta dostępna jest dla wszystkich usług czyli odpowiedzi ECO, ND, NDI, SC, SCI, PR, PRI, 2WAY. W przypadku niepowodzenia w przekazaniu wiadomości na URL, ponowienie wysyłki wiadomości do Klienta nastąpi kolejno po 5, 10, 15 i 60 min. Jeśli mimo wszystko nie uda się przekazać wiadomości do Klienta, system nie będzie podejmował więcej prób. Wiadomości są jednak cały czas dostępne z poziomu Panelu Klienta oraz API.