HTTPS API v2 / 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.

messages/recived

Dostępne parametry

Parametr	Typ	Przykładowa wartość lub format	Opis
username	String	Login	Login użytkownika API.
password	String	Haslo	Hasło użytkownika API.
phone	String|Array	%2B48500600700	Numer lub numery telefonów przekazane w tablicy.
date_from oraz date_to	DateTime	ISO np. „2014-10-24 17:46:00”	Przedział czasowy, który ma zostać wyświetlony. Jest to data i godzina wysłania wiadomości.
type	String	eco|2way|nd|ndi|pre|mms	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).
read	Boolean	true, false lub brak	Oznacza wiadomość jako przeczytaną (nie będzie więcej zwracana przez API).
show_contact	Boolean	true, false lub brak	Wyświetla szczegóły kontaktu, jeśli numer istnieje w bazie odbiorców.

Parametry oznaczone pogrubieniem są obowiązkowe. Pozostałe są opcjonalne.

Zwrot odpowiedzi

{
   "items":[{
      "id":2477793,
      "type":"eco",
      "phone":"+48500600700",
      "recived":"2014-10-21 11:18:03",
      "message_id":"eba39e4fe1",
      "blacklist":false,
      "text":"Przyjade o 16"
   },
   {
      "id":303023,
      "type":"nd",
      "phone":"+48500600700",
      "recived":"2014-10-21 12:37:43",
      "blacklist":false,
      "text":"SerwerSMS.pl"
   },
   {
      "id":2204974,
      "type":"ndi",
      "phone":"+48500600700",
      "recived":"2014-10-21 16:47:36",
      "blacklist":false,
      "text":"Dziękuję za informację"
   },
   {
      "id":323961872,
      "type":"mms",
      "phone":"+48500600700",
      "recived":"2014-10-21 14:09:15",
      "to_number":"+48664078059",
      "blacklist":false,
      "title":"Temat MMS",
      "attachments":[{
         "id":2518,
         "name":"text_0002.txt",
         "content_type":"text/plain",
         "data":"SmFrYXMgdGFtIGplc3pjemUgd2lhZGFvbW9zYw=="
      }]
   }]
}

Objaśnienie poszczególnych parametrów zwrotnych

Parametr	Opis
id	Numer ID wiadomości.
type	Określa typ otrzymanej wiadomości. Przyjmuje wartości: eco, nd, ndi, pre, mms.
phone	Numer nadawcy wiadomości SMS.
recived	Data wysłania wiadomości.
message_id	Identyfikator wysłanej wiadomości ECO, której dotyczy dana odpowiedź.
to_number	Numer, na który przysłano wiadomość (dotyczy MMS).
blacklist	Informacja, czy numer znajduje się na czarnej liście.
text	Treść wiadomości.
title	Tytuł wiadomości (dotyczy MMS).
attachments	Zawiera listę załączników składającą się z numeru ID, nazwy (name), typu pliku (content_type) oraz jego zawartości zakodowanej w base64 (data).

Przekazywanie wiadomości przychodzących na zdefiniowany adres URL Klienta

Odpowiednie opcje dostępne są w Panelu Klienta:
Odpowiedzi ECO: Ustawienia interfejsów > HTTPS XML API > Odpowiedzi SMS  ECO
ND/SC: Ustawienia wiadomości > Numery ND/SC > [wybrane hasło/prefiks] > Prześlij dalej
NDI/SCI: Ustawienia wiadomości > Numery NDI/SCI > [wybrane hasło/prefiks] > Prześlij dalej
MMS: Odbiór wiadomości > Odebrane MMS > 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 adres 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 po 5, 10, 15 i 60-ciu 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 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. W przypadku niepowodzenia w przekazaniu wiadomości na adres 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.