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.