HTTPS API v2 / Wysyłanie wiadomości SMS o jednakowej treści

Wywołanie adresu

Aby przy pomocy Zdalnej obsługi wysłać wiadomość SMS należy przesłać określone zgłoszenie protokołem HTTP lub HTTPS metodą POST.

messages/send_sms

UWAGA! Aby wysłać wiadomość SMS FULL należy wypełnić pole nadawca (nazwa alfanumeryczna lub numer). Jeśli parametr nadawca zostanie pominięty, lub jego wartość będzie pusta, zostanie wysłany SMS typu ECO. Wypełnienie parametru nadawca decyduje o tym czy wysłany zostanie SMS ECO+ czy FULL.

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 +48500600700 Numer lub tablica numerów telefonów.
text String tresc Treść wiadomości.
(W parametrze można użyć znacznika o konstrukcji #URL:http://twojadres.pl#, który spowoduje podmianę adresu www na skrócony, indywidualny link w domenie otworz.to. Szczegóły: https://serwersms.pl/funkcje/funkcje-systemowe#skrocony-link).
flash Boolean true, false lub brak Parametr opcjonalny.
test Boolean true, false lub brak 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 Alfanumeryczna nazwa nadawcy np. „INFORMACJA”, własna nazwa, "2waySMS" lub numer 4 lub 9-cio cyfrowy. Parametr opcjonalny, umożliwia zmianę pola nadawcy wiadomości SMS na niemal dowolną nazwę lub numer. Każda nazwa nadawcy musi zostać najpierw dodana w Panelu lub przez API, a następnie zatwierdzona przez administratora SerwerSMS.pl. Ustawienie nazwy na wartość "2waySMS" spowoduje podmianę nagłówka na losowy numer 9-cio cyfrowy, na który można odesłać odpowiedź zwrotną.
wap_push String Adres URL lub brak Parametr opcjonalny.
utf Boolean true, false lub brak Parametr opcjonalny, umożliwia wysłanie wiadomości FULL SMS zawierającej np. polskie znaki diakrytyczne, cyrylicę itp. Opcja dostępna wyłącznie w SMS FULL. Przy użyciu tej opcji zmienia się maksymalna długość pojedynczej wiadomości SMS z 160 do 70 znaków.
details Boolean true, false lub brak Parametr wyświetlający w odpowiedzi zwrotnej szczegóły wysłanych wiadomości.
vcard Boolean true, false lub brak Parametr opcjonalny, umożliwiający wysłanie wiadomości VCARD.
speed Boolean 1, 0 lub brak Parametr opcjonalny, pozwalający na wysłanie wiadomości niezależnym kanałem o najwyższej jakości (dodatkowa opłata).
date DateTime ISO np.
„2015-02-22 12:25:55”		 Parametr opcjonalny, pozwalający na określenie terminu wysyłki wiadomości.
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 oraz ilość unique_id musi być zgodna z ilością numerów.
group_id String|Array np. 123456789

Identyfikator lub identyfikatory grup w Panelu Klienta. Identyfikatory te można pobrać korzystając z akcji groups/index lub kopiując je z poziomu edycji grupy w Panelu Klienta.
contact_id String|Array np. 123456789

Identyfikator lub identyfikatory kontaktów w Panelu Klienta. Identyfikatory te można pobrać korzystając z akcji contacts/index.
validity Integer np. 1440 (1440 minut to 24 godziny)

Czas ważności wiadomości SMS wyrażony w minutach w trakcie którego będą podejmowane próby dostarczenia wiadomości do odbiorcy. Po tym czasie wiadomość otrzyma status Niedoręczono. W przypadku braku ustawienia parametru, wartość zostanie pobrana z ustawień konta głównego z preferencji. Domyślnie 24 godziny. Minimalna zalecana wartość to 2, maksymalna 4320 (72 godziny). Opcja działa dla SMS FULL.
dlr_url String

http://www.twojadres.pl/skrypt.php?
smsid=#SMSID#&stan=#STAN#&data=#DATA# 

Parametr pozwala na przekazywanie metodą Push raportów doręczenia na URL Klienta. Ustawienie tej opcji w zapytaniu API nadpisuje ew. ustawienia w Panelu Klienta. W przypadku wysyłki metodą GET adres powinien być przekazany w formie zakodowanej przez urlencode(). Adres do przekazania raportów obowiązuje dla wszystkich wiadomości przekazanych do realizacji w ramach jednego zapytania. Jeśli w adresie URL zastosowano port inny niż 80 lub 443, prosimy o kontakt celem aktualizacji ustawień systemu.

Dostępne parametry:

#SMSID# - identyfikator wiadomości
#STAN# - stan doręczenia
#DATA# - data zmiany statusu
#PRZYCZYNA# - ew. przyczyna niedoręczenia wiadomości

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

W przypadku chęci wysłania wiadomości jako wizytówka Vcard (parametr „vcard=true”), struktura wiadomości musi mieć ściśle określony format. Przykład formatu Vcard można znaleźć w ogólnie dostępnej dokumentacji w internecie lub korzystając z Panelu Klienta i formularza wysyłki SMS. Kolejne tagi w wiadomości Vcard powinny być rozdzielone znakiem nowej linii.

Wiadomość SMS FULL, która zawiera polskie znaki specjalne powinna być przed wysłaniem odpowiednio zakodowana w UTF-8. Aby wysłać wiadomość z polskimi znakami musi być ustawiony parametr „utf=true”, abonent musi posiadać uprawnienia do wysyłania wiadomości typu SMS FULL oraz musi być wypełnione pole nadawcy (to oznacza, iż wysłany będzie SMS FULL).

Zwrot odpowiedzi

W zależności od przesłanych danych SerwerSMS.pl wygeneruje w odpowiedzi dokument w formacie JSON/XML z informacją na temat wykonanych akcji. I tak w przypadku prawidłowego wysłania wiadomości SMS klient otrzyma przykładowo następują informację:

{
   "success":true,
   "queued":1,
   "unsent":0
}

W przypadku podania dodatkowego parametru details=true, odpowiedź zwrotna zostanie uzupełniona o szczegóły wysyłanych wiadomości, które można zapisać w bazie danych po stronie oprogramowania klienta:

{
   "success":true,
   "queued":1,
   "unsent":0,
   "items":[{
        "id":"1c142d81c7",
        "phone":"+48500600700",
        "status":"queued",
        "queued":"2014-10-16 16:49:05",
        "parts":1,
        "text":"Test SerwerSMS.pl"
   }]
}

Parametr "success" zawiera informację o powodzeniu przeprowadzonej operacji. W atrybutach "queued" oraz "unset" znajdują się liczby skolejkowanych oraz niewysłanych wiadomości. Sekcja "items" zawiera numery telefonów i ID wiadomości przekazanych do wysłania (oraz wiadomości, których nie skolejkowano z określonego powodu). Unikalny znacznik wiadomości SMS może być wykorzystany później do sprawdzenia w sposób zdalny stanu wysyłki konkretnej wiadomości SMS. W parametrze "text" widnieje treść wysyłanej wiadomości SMS. Numer telefonu jest automatycznie poprawiany i wyświetlany w pełnym formacie wymaganym przez SerwerSMS.pl czyli z numerem kierunkowym kraju (np. +48) na początku. 

W przypadku podania np. złego numeru telefonu zostanie wygenerowana informacja o błędzie jak również ID wiadomości (aby można było później sprawdzić kiedy i dlaczego nie została wysłana). I tak np. w przypadku podania dwóch numerów prawidłowych i dwóch numerów błędnych  system wygeneruje następujący dokument JSON:

{
   "success":true,
   "queued":2,
   "unsent":2,
   "items":[{
      "id":"32039da8e9",
      "phone":"+48500600700",
      "status":"queued",
      "queued":"2014-10-20 12:32:52",
      "parts":1,
      "text":"Test platformy SerwerSMS.pl"
   },
   {
      "id":"844c2b4af0",
      "phone":"+48500600500",
      "status":"queued",
      "queued":"2014-10-20 12:32:52",
      "parts":1,
      "text":"Test platformy SerwerSMS.pl"
   },
   {
      "id":"6e373d7856",
      "phone":"45616",
      "status":"unsent",
      "queued":"2014-10-20 12:32:52",
      "error_code":3103,
      "error_message":"Błędny numer odbiorcy",
      "text":"Test platformy SerwerSMS.pl"
   },
   {
      "id":"bf069fe2c1",
      "phone":"7799123",
      "status":"unsent",
      "queued":"2014-10-20 12:32:52",
      "error_code":3103,
      "error_message":"Błędny numer odbiorcy",
      "text":"Test platformy SerwerSMS.pl"
   }]
}

Oprócz tego może zostać wygenerowany błąd ogólny gdzie nie ma rozgraniczenia na skolejkowane i błędne. Może to nastąpić np. w sytuacji gdy klient nie zdefiniuje treści wiadomości, nie poda numerów telefonów, jego konto nie jest aktywne lub wystąpił inny problem opisany w komunikatach błędów. W przypadku niewpisania treści wiadomości zostanie wygenerowany następujący komunikat:

{
   "error":{
      "code":3101,
      "type":"SendError",
      "message":"Wiadomość jest pusta"
   }
}

oraz analogicznie w przypadku niepodania numerów telefonów:

{
   "error":{
      "code":3104,
      "type":"SendError",
      "message":"Nie podano numerów telefonów"
   }
}

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ń.

W przypadku próby wysyłki wiadomości na dwa lub więcej takie same numery telefonów w jednym zapytaniu, system wyśle wiadomość tylko raz na  ten numer.

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