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.