HTTPS XML API / 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 lub GET. W wiadomościach spersonalizowanych nie ma dostępnych parametrów takich jak „numer” czy „wiadomosc”. Zamiast tego jest dodatkowy parametr „spersonalizowane” który zawiera zbiór numerów oraz przyporządkowanych do nich indywidualnych treści wiadomości. Wartość parametru „spersonalizowane” składa się z oddzielonych od siebie dwukropkiem numeru oraz wiadomości (np. „500600700:wiadomosc spersonalizowana”). Kolejne człony, czyli „numer+treść” oddzielone są od siebie znakami „]|[„. Limit pojedynczego wywołania takie go 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ładowo adres w przeglądarce wyglądać może następująco:
https://api1.serwersms.pl/zdalnie/index.php?login=demo&haslo=demo&akcja=wyslij_sms&spersonalizowane=+48500600700:wiadomosc1]|[+48500600500:wiadomosc2]|[
Wywołanie powyższego adresu (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 |
|---|---|---|---|
| akcja | String | wyslij_sms | Aby wysłać wiadomość SMS należy umieścić tutaj wartość „wyslij_sms”. |
| login | String | login | Login konta używanego do wysyłki |
| haslo | String | haslo | Hasło do konta |
| spersonalizowane | String | +48500600700:tresc1]|[ +48500600500:tresc2]|[ itp. | Numery telefonów i przypisane do nich treści wiadomości SMS powinny być oddzielone znakiem dwukropka „:” natomiast kolejne człony „numer:wiadomosc” powinny być oddzielone od siebie znakami „]|[„. |
| flash | Integer | 1, 0 lub brak parametru | Parametr opcjonalny. |
| test | Integer | 1, 0 lub brak parametru | Parametr opcjonalny, pozwalający na sprawdzenie zapytania wysyłającego wiadomość SMS. W odpowiedzi generowany jest dokument XML identyczny jak w przypadku standardowego zapytania jednak wiadomość nie jest wysyłana. Przydatne do testowania aplikacji. |
| nadawca | 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 |
| kodowanie | String | UTF-8 lub brak | Parametr opcjonalny, umożliwia wysłanie wiadomości FULL SMS zawierającej m.in. polskie znaki diakrytyczne. |
| glosowy | Integer | 1 lub 0 | Parametr opcjonalny, umożliwia wysłanie wiadomości SMS VOICE. Parametr nadawca musi pozostać pusty. |
| data_wysylki | DateTime | ISO np: „2010-11-09 15:23” |
Parametr opcjonalny pozwalający na określenie terminu wysyłki wiadomości SMS. |
| usmsid | String | 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 usmsid muszą być unikalne, podane po przecinku oraz ilość usmsid musi być zgodna z ilością wiadomości spersonalizowanych. |
| 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. 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. Dostępne parametry: #SMSID# - identyfikator wiadomości |
| waznosc | Integer | np. 1440 (1440 minut to 24 godziny) | Czas ważności wiadomości SMS wyrażony w minutach w trakcie którego będa 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. |
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. Rożnica polega jedynie na wyświetlanej wartości w znacznikach
„<Wiadomosc>Wiadomosc spersonalizowana</Wiadomosc>„. Wartość ta jest stała i niezależna od treści przesyłanych wiadomości SMS.
<?xml version="1.0" encoding="UTF-8"?>
<SerwerSMS login="demo">
<Wiadomosc>Wiadomosc spersonalizowana</Wiadomosc>
<Odbiorcy>
<Skolejkowane>
<SMS id="e1389bc4f6" numer="+48500600700" godzina_skolejkowania="2008-07-10 12:42:45"/>
<SMS id="3ko9iuytdf" numer="+48500600500" godzina_skolejkowania="2008-07-10 12:42:45"/>
</Skolejkowane>
<Niewyslane>
<SMS id="dedb71cd72" numer="6043440" przyczyna="bledny numer odbiorcy"/>
<SMS id="765dk6109s" numer="+420777099123" przyczyna="niedozwolone wysyłanie SMSow do sieci zagranicznych"/>
</Niewyslane>
</Odbiorcy>
</SerwerSMS>
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 „spersonalizowane” nadpisuje wartości parametrów „numer” oraz „wiadomosc”.
Zalecana wartość timeout-u dla pojedynczego zapytania wynosi 60 sekund.