HTTPS API v2 / Wysyłanie spersonalizowanych wiadomości SMS

Wywołanie adresu

Aby przy pomocy zdalnej obsługi wysłać spersonalizowaną wiadomość SMS należy wywołać określony adres URL metodą POST. W wiadomościach spersonalizowanych nie ma dostępnych parametrów takich jak „phone” czy „text”. Zamiast tego jest dodatkowy parametr „messages” który zawiera zbiór numerów oraz przyporządkowanych do nich indywidualnych treści wiadomości. Wartość parametru „messages” składa się z tablicy dwuwymiarowej, w której zawarte są klucze "phone" oraz "text". Limit pojedynczego wywołania takiego zapytania to 10 000 numerów i odpowiadającym im treściom wiadomości (zalecane są znacznie mniejsze porcje danych, po ok. 50-200 numerów w jednym zapytaniu). Przykładowe wywołanie wysyłki może wyglądać następująco:

messages/send_personalized

POST:
{
   messages:[{
      "phone": "+48500600700",
      "text": "wiadomosc1"
   },
   {
      "phone": "+48500600500",
      "text": "wiadomosc2"
   }]
}

Wywołanie powyższej akcji wraz z podanymi parametrami (w przypadku podania prawidłowych danych do zalogowania) spowodowałoby wysłanie wiadomości SMS o treści „wiadomosc1” na numer 500600700 oraz drugą wiadomość SMS o treści „wiadomosc2” na numer 500600500.

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.
messages	Array	[array('phone' => numer, 'text' => wiadomosc), array('phone' => numer, 'text' => wiadomosc)]	Numery telefonów i przypisane do nich treści wiadomości SMS.
details	Boolean	true, false lub brak	Parametr wyświetlający w odpowiedzi zwrotnej szczegóły wysłanych wiadomości.
flash	Boolean	true, false lub brak parametru	Parametr opcjonalny.
test	Boolean	true, false lub brak parametru	Parametr opcjonalny, pozwalający na sprawdzenie zapytania wysyłającego wiadomość SMS. W odpowiedzi generowany jest dokument JSON/XML identyczny jak w przypadku standardowego zapytania jednak wiadomość nie jest wysyłana. Przydatne do testowania aplikacji (debug).
sender	String	Numer w formacie +48500600700 lub nazwa własna (max 11 znaków, duże i małe litery oraz liczby i znak spacji).	Parametr opcjonalny, umożliwia zmianę pola nadawcy wiadomości SMS na dowolny numer lub nazwę. Użyć można wyłącznie nazwy zatwierdzone przez administratorów lub nazwy predefiniowane.
utf	Boolean	true, false lub brak parametru	Parametr opcjonalny, umożliwia wysłanie wiadomości FULL SMS zawierającej m.in. polskie znaki diakrytyczne.
voice	Boolean	true, false lub brak parametru	Parametr opcjonalny, umożliwia wysłanie wiadomości SMS VOICE. Parametr nadawca musi pozostać pusty.
date	DateTime	ISO np: „2010-11-09 15:23”	Parametr opcjonalny pozwalający na określenie terminu wysyłki wiadomości SMS.
unique_id	String|Array	np. 6asTD3fif98gj	Parametr opcjonalny pozwalający na zdefiniowanie własnego identyfikatora wysyłanej wiadomości. Identyfikator może mieć minimalnie 3 znaki i maksymalnie 50 znaków alfanumerycznych (a-z, A-Z, 0-9). Dla grupowych wysyłek, kolejne unique_id muszą być unikalne, podane w formie tablicy oraz ilość unique_id musi być zgodna z ilością wiadomości spersonalizowanych.

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

Zwrot wygenerowany po przesłaniu jest taki sam jak w przypadku zwykłego wysłania wiadomości SMS.

{
   "success":true,
   "queued":2,
   "unsent":2,
   "items":[{
      "id":"98c93cc5f2",
      "phone":"+48500600700",
      "status":"queued",
      "queued":"2014-10-20 13:26:50",
      "parts":1,
      "text":"wiadomosc1"
   },
   {
      "id":"a20ff834c8",
      "phone":"+48500600500",
      "status":"queued",
      "queued":"2014-10-20 13:26:50",
      "parts":1,"text":"wiadomosc2"
   },
   {
      "id":"b25462142e",
      "phone":"45648",
      "status":"unsent",
      "queued":"2014-10-20 13:26:50",
      "error_code":3103,
      "error_message":"Błędny numer odbiorcy",
      "text":"wiadomosc3"
   },
   {
      "id":"d862cc6575",
      "phone":"11999885544",
      "status":"unsent",
      "queued":"2014-10-20 13:26:50",
      "error_code":3103,
      "error_message":"Błędny numer odbiorcy",
      "text":"wiadomosc4"
   }]
}

Zalecane ustawienia

W przypadku średnich i dużych ilości wysyłanych wiadomości rzędu kilku tysięcy lub więcej, zalecane jest przekazywanie wiadomości w „paczkach” po ok 50-200 numerów w jednym zapytaniu. Przyspieszy to znacznie proces przekazywania danych do SerwerSMS.pl i zmniejszy ilość koniecznych do wysłania zapytań.

Zdefiniowanie parametru „messages” nadpisuje wartości parametrów „phone” oraz „text”. 

Zalecana wartość timeout-u dla pojedynczego zapytania wynosi 60 sekund.