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 klienta używany do logowania się w Panelu Klienta.
password String Haslo Hasło klienta używane do logowania się w Panelu Klienta.
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|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.