1. Wprowadzenie
Platforma SMSAPI została skierowana do użytkowników chcących rozbudować swoje aplikacje o system wysyłania i odbierania SMS-ów oraz MMS-ów oraz wysyłki wiadomości głosowych VMS. Aplikacja ta w prosty sposób umożliwia integrację dowolnego serwisu z bramką SMS, MMS i/lub VMS. Głównymi atutami naszego serwisu oprócz prostej implementacji jest możliwość nadawania wiadomości z własnej nazwy (maksymalnie 11 znaków). Każdy wysłany SMS, MMS oraz VMS za pośrednictwem systemu posiada unikalny numer identyfikacyjny pozwalając na sprawdzenie raportu doręczenia wiadomości.
1.1 Rozpoczęcie współpracy
W celu rozpoczęcia współpracy należy utworzyć konto w serwisie SMSAPI . Utworzone konto jest gotowe do użytku, jednak zalecamy ustawienie własnego pola nadawcy. Jako domyślne ustawione jest pole nadawcy „Info”. Dodanie pola nadawcy jest usługą całkowicie darmową.
1.2 Filtr IP dla interfejsu API
W celu dodatkowego zabezpieczenie interfejsu API w Filtr adresów IP ustawić można adresy IP z których możliwa będzie wysyłka wiadomości (w przypadku próby dokonania wysyłki z innego IP system zwróci błąd: ERROR:105
). Adresy należy oddzielić przecinkami.
1.3 Autoryzacja
Przykład:
POST /sms.do HTTP/1.1
Host: api.smsapi.pl
Authorization: Bearer <access_token>
Rekomendujemy autoryzację OAuth 2.0. Genrowanie tokenu z dostępem do wybranych stref można zrealizować w naszym panelu klienta Tokeny API .
W odwołaniu do API wymagany jest dodatkowy nagłówek autoryzacyjny.
Jeżeli wykorzystywane środowisko nie pozwala na modyfikację nagłówków opcjonalnie można dodać parametr access_token w którym zostanie przekazany token. Jest to jednak rozwiązanie nierekomendowane oraz obniżające poziom bezpieczeństwa.
1.4 Adresy URL
Adresy URL do połączenia z aplikacją - zwane dalej "Adresem połączenia":
https://api.smsapi.pl/
- dla połączeń szyfrowanych SSLhttps://api2.smsapi.pl/
- backup dla połączeń szyfrowanych SSL
1.5 Biblioteki
Wykorzystanie gotowych bibliotek SMSAPI pozawala na przyśpieszenie oraz uproszczenie prac związanych z integracją z naszą platformą. Wszystkie dostępne biblioteki są dostępne na GitHub.
Język programowania | Github link: |
---|---|
PHP | Biblioteka PHP |
C# .net | Biblioteka C# |
Bash | Biblioteka Bash |
Python | Biblioteka Python |
JavaScript (node.js) | Biblioteka JavaScript (node.js) |
Java | Biblioteka Java |
2. Pojedynczy SMS
curl -H "Authorization Bearer access_token" \
"https://api.smsapi.pl/sms.do?\
from=pole_nadawcy&\
to=48500000000&\
message=treść_wiadomości&\
format=json"
<?php
function sms_send($params, $token, $backup = false)
{
static $content;
if ($backup == true) {
$url = 'https://api2.smsapi.pl/sms.do';
} else {
$url = 'https://api.smsapi.pl/sms.do';
}
$c = curl_init();
curl_setopt($c, CURLOPT_URL, $url);
curl_setopt($c, CURLOPT_POST, true);
curl_setopt($c, CURLOPT_POSTFIELDS, $params);
curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
curl_setopt($c, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer $token"
));
$content = curl_exec($c);
$http_status = curl_getinfo($c, CURLINFO_HTTP_CODE);
if ($http_status != 200 && $backup == false) {
$backup = true;
sms_send($params, $token, $backup);
}
curl_close($c);
return $content;
}
$token = "wygenerowany_token"; //https://ssl.smsapi.com/webapp#/oauth/manage
$params = array(
'to' => '500000000', //numery odbiorców rozdzielone przecinkami
'from' => 'Info', //pole nadawcy
'message' => "Hello world!" //treść wiadomości
);
echo sms_send($params, $token);
?>
I. Przykład odpowiedzi kiedy &format = json jest użyty:
a) W przypadku sukcesu:
{
"count":1,
"list": [
{
"id":"1460969715572091219", //id wiadomości
"points":0.16, //cena wiadomości
"number":"44123456789", //numer odbiorczy z prefixem
"date_sent":1460969712, //data wysyłki
"submitted_number":"44123456789", //numer odbiorczy podany w zapytaniu
"status":"QUEUE" //status wiadomości
}
]
}
b) w przypadku niepowodzenia:
{
"invalid_numbers":[
{
"number":"44123456789", //numer odbiorczy z prefixem
"submitted_number":"44123456789", //numer odbiorczy podany w zapytaniu
"message":"Invalid phone number" //opis błędu
}
],
"error":13, //kod błędu
"message":"No correct phone numbers" //opis błędu
}
}
II. Przykład odpowiedzi bez parametru &format :
a) W przypadku sukcesu:
OK:<ID>:<POINTS>
OK:1460969715572091219:0.16
b) w przypadku niepowodzenia:
ERROR:<ERR>
ERROR:13
Wysyłanie SMS-ów odbywa się przez wysłanie metodą GET lub POST danych do adresu połączenia:
Parametr | Opis |
---|---|
access_token | OAuth token wygenerowany w Panelu SMSAPI |
to | Numer odbiorcy wiadomości w formacie 48xxxxxxxxx lub xxxxxxxxx. Np. 48505602702 lub 505602702. |
group | Nazwa grupy kontaktów z książki telefonicznej, do których ma zostać wysłana wiadomość |
message | Treść wiadomości. Standardowo do 160 znaków lub 70 znaków w przypadku wystąpienia chociaż jednego znaku specjalnego (polskie znaki uważane są za specjalne). Maksymalna długość wiadomości wynosi 918 znaków (lub 402 ze znakami specjalnymi) i jest wysyłana/ jako 6 połączonych SMS-ów, obciążając konto zgodnie z aktualnym |
from | Parametr from definiuje rodzaj wysłanej wiadomości (Pro / Eco / 2way) jednocześnie dla wiadomości Pro określając Pole Nadawcy z jakim wiadomość ma być wysłana: &from=Nazwa – spowoduje wysłanie wiadomości Pro z polem nadawcy „Nazwa” &from=2way – spowoduje wysłanie wiadomości 2WAY - &from=Eco – spowoduje wysłanie wiadomości ECO. Pozostawienie pola pustego powoduje wysłanie domyślnego rodzaju wiadomości z domyślnym polem nadawcy. Przyjmowane są tylko nazwy zweryfikowane. (&from=aktywna_nazwa). Pole nadawcy należy dodać po zalogowaniu na stronie SMSAPI, Pola Nadawcy . |
encoding | Parametr określa kodowanie polskich znaków w SMS-ie. Domyślne kodowanie jest windows-1250. Jeżeli występuje konieczność zmiany kodowania, należy użyć parametru encoding z danymi: Interfejs HTTP/S API - wersja 2.34-dla iso-8859-2 (latin2) – należy podać wartość „iso-8859-2”,-dla utf-8 – należy podać wartość „utf-8”. |
flash | Wysyłanie wiadomości trybem „flash”, odbywa się poprzez podanie parametru flash o wartości „1”. SMS-y flash są automatycznie wyświetlane na ekranie głównym telefonu komórkowego i nie są przechowywane w skrzynce odbiorczej (jeśli nie zostaną zapisane). |
test | Wiadomość nie jest wysyłana, wyświetlana jest jedynie odpowiedź (w celach testowych). (&test=1) |
details | W odpowiedzi zawarte jest więcej szczegółów. (Treść wiadomości, długość wiadomość, ilość części z jakich składa się wiadomość). (&details=1) |
date | Data w formacie unixtime (&date=1287734110) lub ISO 8601 (&date=2012-05-10T08:40:27+00:00). Określa kiedy wiadomość ma być wysłana. W przypadku wstawieniadaty przeszłej wiadomość zostanie wysłana od razu. Wiadomość można zaplanować na maksymalnie 3 miesiące do przodu. |
date_validate | Ustawienie „1” sprawdza poprawność formatu podanej daty. W przypadku wystąpienia błędnej daty zwrócony zostanie błąd ERROR:54 |
datacoding | Parametr pozwalający na wysyłanie wiadomości binarnych. (&datacoding=bin) Parametry udh oraz message muszą być wysyłane w postaci ciągu HEX (np. message=616263 dla treści abc) |
udh | Nagłówek UDH wiadomości SMS wymagany podczas korzystania z parametru &datacoding=bin (np. &udh=0605040b8423f0 dla WAP PUSH) |
skip_foreign | Ustawienie tego parametru (&skip_foreign=1) powoduje pominięcie numerów nie-polskich jeżeli takie pojawią się w odwołaniu |
allow_duplicates | Pozwala na wysłanie wiadomości na numery zduplikowane w danym odwołaniu (przydatne np. przy wykorzystywaniu sparametryzowanych treści) |
idx | Opcjonalny parametr użytkownika wysyłany z wiadomością a następnie zwracany przy wywołaniu zwrotnym CALLBACK. Parametr idx może mieć maksymalnie 255 znaków dopuszczalne są cyfry 0 - 9 oraz litery a – z (wielkość liter nie jest rozróżniana). (&idx=123) |
check_idx | Pozwala zabezpieczyć przed wysłanie dwóch wiadomości z identyczną wartością parametru idx w trakcie ostatnich 24h. W przypadku ustawienia parametru (&check_idx=1)system sprawdza czy wiadomość z podanym idx nie została wysłana w ostatnich czterechdniach lub czy nie jest zaplanowana do wysłania w przyszłości, jeżeli jest zwracany jest błąd 53. |
nounicode | Ustawienie 1 zabezpiecza przed wysłaniem wiadomości ze znakami specjalnymi (w tym polskimi) (ERROR:11 ). |
normalize | Opcja spowoduje zastąpienie w wiadomości SMS znaków specjalnych na ich odpowiedniki (np. ą-a, ć-c, ę-e...). (&normalize=1) |
fast | Ustawienie 1 spowoduje wysłanie wiadomości przy wykorzystaniu osobnego kanału zapewniającego szybkie doręczenie wiadomości Fast. Z parametru korzystać można podczas wysyłania wiadomości Pro oraz Eco, Ilość punktów za wysyłkę pomnożona będzie przez 1.5 Uwaga! Dla tego parametru zabronione jest prowadzenie wysyłek masowych i marketingowych. |
partner_id | Kod partnerski, który otrzymać można po podpisaniu umowy partnerskiej. Kod nie będzie brany pod uwagę jeżeli użytkownik wysyłający polecony jest przez innego klienta lub podaje swój kod. |
max_parts | Parametr określa maksymalną ilość części z jakich może składać się wiadomość. Maksymalna wartość to 6. W przypadku gdy wiadomość składa się z większej ilości części zwrócony zostanie błąd ERROR:12 Domyślna ilość części ustawiana jest w panelu klienta. |
expiration_date | Różnica pomiędzy datą wysyłki a datą wygaśnięcia musi być większa niż 15 minut i mniejsza niż 72 godzin (zaleca się aby było to minimum 1 godzina i maksymalnie 12 godzin).Data może zostać podana w formacie unixtime (&date=1287734110) lub ISO 8601 (&date=2012-05-10T08:40:27+00:00). |
discount_group | Nazwa grupy kodów rabatowych do załączenia w wysyłce. Grupy można dodawać oraz edytować w panelu klienta. |
notify_url | Parametr pozwalający na ustawienie adresu URL do skryptu callback odbierającego raporty doręczenia dla danej wiadomości. Adres ten jest brany w pierwszej kolejności (przed globalnym adresem ustawionym na koncie). |
format | Dla &format=json powoduje, że zwrotka z API wysyłana jest w formacie JSON. |
2.1 Wiadomość FAST
https://api.smsapi.pl/sms.do
- dla połączeń szyfrowanych SSL
curl -H "Authorization: Bearer access_token" \
"https://api.smsapi.pl/sms.do?\
from=pole_nadawcy&\
to=44123456789&\
message=tresc_wiadomosci&\
fast=1&\
format=json"
<?php
$params = array(
'access_token' => 'token SMSAPI' //token SMSAPI
'to' => '48500000000', //numer odbiorczy
'from' => 'SMSAPI', //pole nadawcy
'message' => 'treść wiadomości', //treść wiadomości
'fast' => '1',
);
?>
Przykład odpowiedzi :
a) W przypadku sukcesu:
OK:<ID>:<POINTS>
OK:17101000090360359:0.16
b) w przypadku niepowodzenia:
ERROR:<ERR>
ERROR:13
ID | Unikalne ID wiadomości |
POINTS | Ilośc punktów wykorzystanych do wysyłki |
ERR | Kod błędu (sprawdź kody błędów) |
Ustawienie parametru fast=1
spowoduje wysłanie wiadomości przy wykorzystaniu osobnego kanału zapewniającego najwyższy priorytet wysyłki. Z parametru korzystać można podczas wysyłania wiadomości Pro oraz Eco, Ilość punktów za wysyłkę pomnożona będzie przez 1.5
W razie problemów podczas odwoływania się do podstawowego adresu URL można wykorzystać adres URL backup https://api2.smsapi.pl/
2.2 Planowanie SMS
https://api.smsapi.pl/sms.do
- dla połączeń szyfrowanych SSL
<?php
$params = array(
'access_token' => 'token SMSAPI' //token SMSAPI
'to' => '48500000000', //numer odbiorczy
'from' => 'SMSAPI', //pole nadawcy
'message' => 'treść wiadomości', //treść wiadomości
'date' => '1577878200', //data wysyłki UNIXTIME / ISO 8601
);
?>
curl -H "Authorization: Bearer access_token" \
"https://api.smsapi.pl/sms.do?\
from=pole_nadawcy&\
to=44123456789&\
message=tresc_wiadomosci&\
date=1577878200&\
format=json"
W celu wysłania wiadomości o określonej godzinie/dacie musi zostać użyty parametr date
, dopuszczalne formaty daty to unixtime i ISO 8601.
Usuwanie zaplanowanej wiadomości :
<?php
$params = array(
'access_token' => 'token SMSAPI' //token SMSAPI
'sch_del' => '9040616088106874', //id wysyłki
);
?>
curl -H "Authorization: Bearer access_token" \
"https://api.smsapi.pl/sms.do?\
sch_del=09040616088106874&\
format=json"
3. Masowe wysyłanie SMSów
https://api.smsapi.pl/sms.do
- dla połączeń szyfrowanych SSL
curl -H "Authorization: Bearer access_token" \
"https://api.smsapi.pl/sms.do?\
from=pole_nadawcy&\
to=48500500500,48501501501,48502502502&\
message=tresc_wiadomosci&\
format=json"
<?php
$params = array(
'access_token' => 'token SMSAPI' //token SMSAPI
'to' => '48500500500,48501501501,48502502502', //numery odbiorcze
'from' => 'SMSAPI', //pole nadawcy
'message' => 'content of message', //treść wiadomości
);
?>
I. Przykład odpowiedzi kiedy użyto parametru &format=json :
a) W przypadku sukcesu:
{
"count": 3,
"list": [
{
"id":"1460978572913968440",
"points":0.16,
"number":"48500500500",
"date_sent":1460978579,
"submitted_number":"48500500500",
"status":"QUEUE"
},
{
"id":"1460978572913968450",
"points":0.16,
"number":"48501501501",
"date_sent":1460978579,
"submitted_number":"48501501501",
"status":"QUEUE"
},
{
"id":"1460978572913968460",
"points":0.16,
"number":"48502502502",
"date_sent":1460978579,
"submitted_number":"48502502502",
"status":"QUEUE"
}
]
}
b) w przypadku niepowodzenia:
{
"invalid_numbers": [
{
"number":"456456456",
"submitted_number":"456456456",
"message":"Invalid phone number"
},
{
"number":"321321321",
"submitted_number":"321321321",
"message":"Invalid phone number"
}
],
"error":13,
"message":"No correct phone numbers"
}
Przykład odpowiedzi bez parametru format :
a) W przypadku sukcesu:
OK:<ID>:<POINTS>
OK:1460978572913968440:0.16:500500500;OK:1460978572913968450:0.16:501500501;OK:1460978572913968460:0.16:501500502
b) w przypadku niepowodzenia:
ERROR:<ERR>
ERROR:13
Wysyłanie SMS-ów do grupy odbiorców odbywa się tak jak do pojedynczego odbiorcy (opis w punkcie 2) lecz z podaniem wielu numerów telefonów w parametrze to
. Dodatkowo cała wysyłka powinna odbywać się metodą POST do adresu połączenia. W przypadku wysyłki metodą GET przy większej ilości numerów, część parametrów może zostać ucięta i w efekcie niedostarczona w całości doserwisu SMSAPI.
Jeżeli cena za wysłanie wszystkich SMS-ów jest większa od ilości punktów dostępnych w serwisie, zostanie zwrócony komunikat o błędzie (103) i SMS-y nie zostaną wysłane. Jeżeli zostały podane błędne numery (nierozpoznane przez serwis SMSAPI ze względu na błędny prefiks), wszystkie SMS-y zostaną wysłane z pominięciem tych numerów, wówczas ilość otrzymanych raportów będzie różnić się od ilości wysłanych SMS-ów. Sytuacja ta nie dotyczy numerów z poprawnym prefiksem (np. 500000000), gdzie SMS zostanie wysłany, a następnie odrzucony gdyż numer nie istnieje (punkty za wysłanie SMS-a zostaną pobrane). Numery, które się powtarzają zostaną wysłane tylko 1 raz.
Warto zauważyć, że przy wysyłce SMS-ów do grupy odbiorców dodatkowo zwracany jest numer telefonu oraz każdy SMS jest zakończany średnikiem (oprócz ostatniego. Nie dotyczy wysyłki z parametrem &format=json).
Zalecana maksymalna ilość jednorazowej wysyłki (jedno wywołanie) wynosi 10 000 wiadomości metodą POST oraz do 200 wiadomości metodą GET.
W razie problemów podczas odwoływania się do podstawowego adresu URL można wykorzystać adres URL backup https://api2.smsapi.pl/
3.1 SMS do grupy z bazy kontaktów
https://api.smsapi.pl/sms.do
- dla połączeń szyfrowanych SSL
curl -H "Authorization: Bearer access_token" \
"https://api.smsapi.pl/sms.do?\
from=pole_nadawcy&\
group=grupa_testowa&\
message=treść z parametrami [%imie%]&\
format=json"
<?php
$params = array(
'access_token' => 'token SMSAPI' //token SMSAPI
'group' => 'grupa_testowa', //grupa odbiorców
'from' => 'SMSAPI', //pole nadawcy
'message' => 'treść z parametrami [%imie%]', //treść wiadomości
);
?>
Przykład odpowiedzi:
OK:<ID>:<POINTS>:<PHONE>;...;...;...
OK:17101000090567759:0.14:500500500;OK:171010000903455357:0.14:501500501;OK:17101000096577326:0.14:502502502;
W celu wysłania wiadomości do określonej grupy należy w pierwszej kolejności stworzyć ją w panelu WWW Grupy.
Istnieje możliwość wstawienia pola własnego do treści wiadomości. Pola własne mogą być definiowane w panelu WWW Pola własne. Aby wstawić pole, w treści wiadomości należy wpisać [%kontakt.nazwa pola%]. Podczas wysyłki pole zostanie zastąpione odpowiednią wartością przypisaną do danego kontaktu. Istnieje także możliwość użycia standardowych pól, takich jak:
Parametr | Opis |
---|---|
[%imie%] | Imię przypisane do kontaktu |
[%imie_w%] | Wołacz imienia przypisanego do kontaktu |
[%nazwisko%] | Nazwisko przypisane do kontaktu |
[%kontakt.kraj%] | Kraj |
[%kontakt.opis%] | Opis kontaktu |
[%kontakt.email%] | |
[%kontakt.urzadzenie%] | Urządzenie użytkownika (przypisywany automatycznie w przypadku kliknięcia odbiorcy w skrócony link) |
[%kontakt.miejscowosc%] | Miejscowość |
[%kontakt.przegladarka%] | Przeglądarka (przypisywana automatycznie w przypadku kliknięcia odbiorcy w skrócony link) |
[%kontakt.system operacyjny%] | System operacyjny użytkownika (przypisywany automatycznie w przypadku kliknięcia odbiorcy w skrócony link) |
[%kontakt.nazwa_pola%] | Niestandardowe pole własne |
3.2 Wykorzystanie parametrów
https://api.smsapi.pl/sms.do
- dla połączeń szyfrowanych SSL
curl -H "Authorization: Bearer access_token" \
"https://api.smsapi.pl/sms.do?\
from=pole_nadawcy&\
to=48600111222,48500111222&\
message=test wiadomości, parametr1:[%1%] parametr2:[%2%]&\
param1=Jan|Ania&\
param2=30|40&\
format=json"
<?php
$params = array(
'access_token' => 'token SMSAPI' //token SMSAPI
'to' => '8600111222,48500111222', //numery odbiorców
'from' => 'SMSAPI', //pole nadawcy
'message' => 'test wiadomości, parametr1:[%1%] parametr2:[%2%]', //treść wiadomości
'param1' => 'Jan|Ania',
'param2' => '30|40'
);
?>
Wiadomości będą miały następującą treść:
Wiadomość 1: Test wiadomosci, parametr1: Jan parametr2: 30
Wiadomość 2: Test wiadomosci, parametr1: Ania parametr2: 40
Istnieje możliwość wysłania do 100 spersonalizowanych wiadomości przy pomocy jednego wywołania wykorzystując parametry. W razie potrzeby wysłania większej ilości wiadomości można wywołać równolegle kilka odwołań.Parametry powinny być zdefiniowane w wywołaniu jako param1, param2, param3, param4, które zastępowały będą [%1%], [%2%], [%3%] oraz [%4%] w treści wiadomości. Wartości parametrów muszą być oddzielone znakiem pipe „|” według wzoru:
param1=Ania|Michal|Andrzej¶m2=Nowak|Kowalski|Nowakowski
Liczba parametrów musi być identyczna z liczbą numerów do których wysłane mają być wiadomości w innym przypadku zwrócony będzie błąd: ERROR:18
i wiadomość nie zostanie wysłana.
Jeżeli jeden z numerów będzie błędny zostanie on pominięty i wiadomości zostaną wysłane z pominięciem tego numeru.
Parametry
Parametry wykorzystane mogą być po zdefiniowaniu ich miejsca w wiadomości:
Parametr | Opis |
---|---|
[%1%] | Tekst parametru 1 (param1) |
[%2%] | Tekst parametru 2 (param2) |
[%3%] | Tekst parametru 3 (param3) |
[%4%] | Tekst parametru 4 (param4) |
3.3 Parametry IDX
Istnieje możliwość wysyłania masowych wiadomości z parametrem użytkownika IDX różnym dla każdej wiadomości. Parametr ten zwracany jest w wywołaniu zwrotnym CALLBACK z raportem doręczenia. Parametr IDX może mieć dowolną wartość, może on być wykorzystywany np. jako flaga użytkownika lub wewnętrzne ID z systemu klienckiego. Dodatkowo przy użyciu parametru IDX możliwe jest użycie parametry check_idx (&check_idx=1), użycie tego parametru nie pozwoli na wysłanie więcej niż jednej wiadomości z tym samym parametrem IDX w trakcie ostatnich 24h. W przypadku próby wysłania wiadomości z wartością parametru IDX która już pojawiła się dla danego użytkownika zostanie zwrócony błąd ERROR: 53
. W celu przypisania różnych parametrów rożnym wiadomością należy oddzielić je znakiem “pipe” co przedstawia poniższy przykład:
idx=idx1|idx2|idx3|idx4
Liczba parametrów IDX musi być identyczna z liczbą wysyłanych wiadomości
3.4 Kody rabatowe
https://api.smsapi.pl/sms.do
- dla połączeń szyfrowanych SSL
curl -H "Authorization: Bearer access_token" \
"https://api.smsapi.pl/sms.do?\
from=pole_nadawcy&\
to=48600111222,48500111222&\
discount_group=kody&\
message=Test wiadomości z kodem rabatowym [%kod%]&\
format=json"
<?php
$params = array(
'access_token' => 'token SMSAPI' //token SMSAPI
'discount_group'=> 'kody', //grupa kodów
'to' => '8500500500,48501501501,48502502502', //grupa odbiorców
'from' => 'SMSAPI', //pole nadawcy
'message' => 'treść z kodem rabatowym [%kod%]', //treść wiadomości
);
?>
SMSAPI umożliwia wysyłanie wiadomości z kodami rabatowymi. Aby wysyłać takie wiadomości trzeba najpierw przygotować listę kodów rabatowych w panelu klienta Kody rabatowe. Kody rabatowe mogą być wczytane z uprzednio przygotowanego pliku csv lub skorzystać z wbudowanego generatora kodów.
Podczas wysyłki system pobiera kody z podanej listy jednocześnie oznaczając je jako wykorzystane (jeden kod może być wykorzystany tylko raz). Aby móc wykorzystać grupę kodów do wysyłki musi być ona aktywna (data ważności nie minęła) oraz zawierać odpowiednią liczbę kodów
3.5 Wiadomości z idz.do
https://api.smsapi.pl/sms.do
- dla połączeń szyfrowanych SSL
curl -H "Authorization: Bearer access_token" \
"https://api.smsapi.pl/sms.do?\
from=pole_nadawcy&\
to=48600111222&\
message=test wiadomości z skróconym linkiem [%idzdo:www.smsapi.pl%] &\
format=json"
<?php
$params = array(
'access_token' => 'token SMSAPI' //token SMSAPI
'to' => '48500500500', //grupa odbiorców
'from' => 'SMSAPI', //pole nadawcy
'message' => 'test wiadomości z skróconym linkiem [%idzdo:www.smsapi.pl%]', //treść wiadomości
);
?>
W celu wysłania wiadomości zawierającej skrócony link, SMSAPI udostępnia „skracacz” idz.do. Linki wygenerowane przy pomocy skracacza mają format http://idz.do/ABCD. Aby w treści wiadomości umieścić skrócony link należy w parametrze message dodać [%idzdo:adres_url%]. Każdy kolejny numer w wysyłce otrzyma unikalny link na podstawie którego możliwe jest śledzenie kliknięć oraz informacji m.in. o czasie wywołania linku, typie urządzenia, systemie operacyjnym.
4. Wykorzystanie szablonów
https://api.smsapi.pl/sms.do
- dla połączeń szyfrowanych SSL >Przykład
Nazwa Szablonu: Powiadomienie
Treść Szablonu: Witaj [%1%], Twoje zamówienie zostało wysłane.
curl -H "Authorization: Bearer access_token" \
"https://api.smsapi.pl/sms.do?\
from=pole_nadawcy&\
to=48500500500&\
template=Powiadomienie&\
param1=Marek&\
format=json"
<?php
$params = array(
'access_token' => 'token_smsapi', //token sms api
'to' => '48500500500' //numer odbiorczy
'from' => 'SMSAPI', //pole nadawcy
'template' => 'Powiadomienie' //nazwa szablonu
'param1' => 'Marek'
);
?>
Treść wysłanej wiadomości:
Witaj Marek, Twoje zamówienie zostało wysłane.
Przy wykorzystaniu szablonów w bardzo prosty sposób zmienić można treść SMS-ów powiadamiających (w sklepach, serwisach internetowych, klinikach itp.) bez ingerencji w kod skryptu odpowiedzialnego za wysyłanie wiadomości SMS.
W celu skorzystania z szablonów należy :
- Po zalogowaniu na stronie http://www.smsapi.pl dodać szablon w menu Wiadomości Szablony.
- W miejsce, w którym ma występować parametr należy wpisać [%N%] gdzie N to liczba od 1 do 4.
- W celu wykorzystania szablonu w interfejsie API należy wybrać jeden z szablonów poprzez wpisanie parametru &template=nazwa_szablonu
- Prócz podstawowych parametrów w trakcie używania szablonów dostępne są parametry
Parametr | Opis |
---|---|
template | Nazwa szablonu |
paramN | Parametr wstawiany w miejsce [%N%] w szablonie gdzie N to liczba od 1 do 4 |
single | Jeżeli wiadomość będzie składała się z więcej niż 160 znaków nie zostanie wysłana i zwrócony zostanie ERROR:12 (&single=1) |
W razie problemów podczas odwoływania się do podstawowego adresu URL można wykorzystać adres URL backup https://api2.smsapi.pl/
5. mail2SMS
Aby wysłać SMS-a za pomocą maila należy wysłać maila według schematu:
ADRES: | sms.do@smsapi.pl |
TEMAT: | login@haslo_32znaki_w_md5 |
TREŚĆ: | from=nadawca&to=numer&message=tresc wiadomosci |
ADRES: | sms.do@smsapi.pl |
TEMAT: | login@8456fkty567gb3bg37b357b3457b3457 |
TREŚĆ: | from=nadawca&to=numer&message=tresc wiadomosci |
Dodanie parametru raport=1 spowoduje odsyłanie maila z raportem (potwierdzenie wysłania wiadomości lub błąd – jest to przydatne w trakcie testowania usługi):
ADRES: | sms.do@smsapi.pl |
TEMAT: | login@8456fkty567gb3bg37b357b3457b3457 |
TREŚĆ: | from=nadawca&to=numer&raport=1&message=tresc wiadomosci |
Wiadomości mogą być wysyłane w kodowaniu plain / quotedprintable / base64. Oprócz parametrów wymienionych w powyższych przykładach w mail2sms dostępne są wszystkie parametry wymienione w Punkcie 2. Wysyłanie pojedynczych SMS'ów. W celu wysłania wiadomości Eco przez mail2SMS podać jako wartość parametru from ustawić Eco (from=Eco). W celu wysłania wiadomości 2way przez mail2SMS podać jako wartość parametru from ustawić 2way (from=2way). Nazwa nadawcy (zmienna &from=) musi być aktywna.
6. Sprawdzenie ilości punktów
https://api.smsapi.pl/user.do
- dla połączeń szyfrowanych SSL
Przykład:
curl -H "Authorization: Bearer access_token" \
"https://api.smsapi.pl/user.do?\
credits=1\
format=json"
I. Przykład odpowiedzi kiedy parametr &format=json został użyty:
w przypadku powodzenia:
{
"points":100.00, // Ilość punktów dostępnych na koncie SMSAPI
}
II. Przykład odpowiedzi bez użycia parametru &format:
a) w przypadku powodzenia:
Response : Credits: <CREDITS>
b) w przypadku niepowodzenia:
Response : ERROR: <ERR>
<CREDITS> Liczba punktów
Example : Credits: 100.000
Poniżej przedstawiona jest funkcja dodatkowa służąca do sprawdzenia stanu środków pozostałych na koncie klienta.
Parametr | Opis |
---|---|
access_token | token przypisany do konta w serwisie SMSAPI |
credits | Należy podać wartość „1” |
details | Dodatkowo wyświetlana jest ilość wiadomości Pro oraz Eco |
format | Dla &format=json powoduje, że zwrotka z API wysyłana jest w formacie JSON |
W razie problemów podczas odwoływania się do podstawowego adresu URL można wykorzystać adres URL backup https://api2.smsapi.pl/
7. Wiadomości MMS
https://api.smsapi.pl/mms.do
- dla połączeń szyfrowanych SSL
curl -H "Authorization Bearer access_token" \
"https://api.smsapi.pl/mms.do?\
to=48500000000&\
subject=Testowy_MMS&\
smil=[smil]&\
format=json"
<?php
$params = array(
'acces_token' => 'smsapi_token', //token SMSAPI
'to' => '48500000000', //numer odbiorcy
'subject' => 'Testowy_MMS', //pole nadawcy
'smil' => 'smil', //treść wiadomości
);
?>
Przykładowa wiadomość MMS w formacie SMIL z wykorzystaniem kodowania BASE64
<smil>
<head>
<layout>
<root-layoutbackgroundColor="#FFFFFF"height="100%"width="100%"/>
<region id="Text"top="50%"height="50%"left="0"width="100%" fit="scroll"/>
</layout>
</head>
<body>
<par>
<img
src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAKgAAAAbCAYAAADoFcRvAAAAAXNSR0IArs4c6QAAA
AZiS0dEAP8A/wD/oL2nkwAACw9JREFUeNrtW2tQVdcVBr0gIATkeamKr1SjJGYiaLDUkvJQBNKmEgyOptWpGqQRbHwQg
xFUFBSMo8ZXIqDMVJzqWIyKigqSijyMT0bUYidjUILlJQgir7v7bXJh9tn33Mu5L+EHa+abPXPPOnvvs/d31tprrXNNT
AZkQAZkQAbEQEIIcQT+DlwEfgRqDYgKYAQ33gxOpwxwfQXP6QU8ZcbNUqNnCgQBh4BSoNrAaxKj77P86qvrHwO1DObo2
V8A15+
+eAIUAAnA62rGzGD0H6rbtLCOjg66aUaR1tZWxfbt273YMffv37+C12tsbDxpZHLaNDc3/8SOeevWrRoRPRfge2JEycr
KuqQnmSa5Jhe9QEu6IU+88hStzi+5bVjsOrY/Q8I15VoTJSo/pmNUegUz/06xTZsBcrYTI8u2bdu82XF37ty5So3qCmM
R9MWLFwf5wYqLi+t5y9nS0pJv7PU4ceJEgR7kHCRPyMsTI4J8y/dHdSbonJg4YxGUwUJ2TIe/fVvZM/eEPIXKpB4/fpz
LL97hw4dJVFQUiYiIIMuWLdMbixcvJoGBgZPYcXft2rVSbONevnzZgsbbCNbzz2LjlZSU1LF67e3tvrzOjRs3yOrVq7v
Ww1BrEhoamq7rs7imlCzWYKkUurp6nqCw0MR65hJiNT2UWP3mQ+lQ6r/2/gpYxX8L55dU0IB2GEPQJxoJWltb28JuxqZ
Nmwh+PgxEARHAMgNgMWAthaBUmpqaqBu2NiA5J8N6Nkgh6O3btzPZ6w8ePCByufwOLq1Wroeh1sRTR+v5Bjb5GbvpTqu
OCq3o5vzHaG31JujWq0TmMnabDs/crZ9i5R32kn+JHD5N/a1kgtbX13eyGzJ37tzUVxGUaSIoFRAqzUDkNGtoaPhB3Tg
8QfPz80s5V9xIj0r9JZiVb74scO1On/2DDB4mv+cce5K3VBmGIKjd/E1e+szXfOyUL1y3FQrmhrPufMkEraurU7Absnv
37kV9QdDOzk4x/oTqOw5c9la+U4VCoZag58+fL2d1L1y48GN/ISc2cYnAUiZdIbLhE8roJct3ZlVRl9xDru0/UFfvry9
BbUKi/PSZs83sSC/ezb/2x88WaePiFZzFWNsXBM3IyFDAvQqI1NbW9hLNaD2s50wEgALmp6amkufPn6sl6MmTJ+9xUX5
VPyGnKwgpcO02s5a24dJEpcqf7BYkdHJRPXX1Zn1K0JDlXpi3QmeCFhYWCiJ4RLD1aJYCE4CRgJuWoPfYa0vQgwcP3vb
393/IW1KcR4vRWOhATlscE/7H9nXs2DEyffr04yCtWoKuX7/+EnsPdOkL/A3goeN6jALkgKU+Gw2XfVFwjos8QEwGDV7
P6uC8eMJl/VkuaCr5uk8JGhjxLl4UoQX9YJV0giI6LRfzrSBKG9AENGsJek8NDX4BGnAslELQs2fPFuJn740bNyr4ueC
l2awlOWmq6DTbR3l5OXFzc/sO+dggTS5+woQJEVVVVUTNmuiyHhQNwH/pY9I4FBiupfVcwG6wy4YLxGzEG8W4NIhTHYk
Iuk4kuveRRNAP18ZzGQFE4tH+
+hAUL1Io7Udg+UOi/iKZoA4ODpF79uwxetoPsNJEULjWG/T3YcOGbTlz5gzhrBg1q5LfZOiv4AoFJCQk5AkuOaFAMEcT
QSF2wcHBdQisjLYYOBfTytpsieR0w9myhd1gu/C4F9YBS2jVZxLgDozs1jc1s/ir3UdxxCnmOHFac6yrddmQUwKdXr2a
TfDyL1y+PEOcvzz9C9b+ix4j3mPmIgPeVo6rCROByfTFQl72oYD0CJgsPYNnSyYohLrPPTQ3l52dTZ4+NU5BCRWcRCkE
hVjCil2qqanhq0yPpFge6LiDAG3svXDbHbgUQK8nJyeH90JQKjO9vLya0tPTyd27d2lu1hjrQc20Yy/kNJVvyc9WyXUm
F7UjCKLo6EJKSRV+d+r29ECayWDZfRwBymg7yNr+kvk4D3lva2dqbulnOsSqAu1PXRhi9dDUwnpsD4FnLbVwiT9/BmMp
esYWRzt0OsXytLZzv6R7MVwbgnYLzVtlOzo6Vk+ZMoX4+vrqhKCgIBITE0PKysr4gIeedUdJIGiXqwoLC2sUyY/mUPet
gZz22Pi7XBROhg4dGt+tk5KS8pEEglKZBqSbmZmVjR8/vtXHx0en9fDz8yMLFy4kR44cIezZlwqMwYZeEvLzpVZokH7a
z91upiQrbWli3FyCwR6szFcPZcAeI2Qy59En8NLoVEWy/
+RrAsKncZUkyQTtuQeYAvjqiCAgBm7yEU+wgoKCRRIJ2hWVHjhwQMXyYJOXq5s43PI+VhcpNOLp6XmV3RwtCMpu9HjAR
8f1oEcTeg4/grKq4HyNAPWaBus5ynVr4XMu4Omq7rgmF6si5Rq1WO9yfVCXbA4MAayVMNVksWnUz0Amoj8CyfcWafX3E
uKy8SJxWnmEWPstIrDmObjfSl+CGkRgAechiiZcimezFgQ1MTc3/7a0tFSsFOouYj3/oJJEDQ19zqRhdCWowQQ51lp2f
jTnqiEhn8VutuPyNCJz/XWnzGVMO6L1DhW4vt4xxP13gYI+EnLd4W4fAOVABUDTThvVWuzkYh/o3APKlO1NRPKjVM8Cp
hFmIyYSMzd3DXiTyOTjOk2tbKtxx01grdKim/QLgiYkJHjBJQsIs3fv3q3aEJQ+0NSpU8tR7eLPb/fRmDPkHIPfBCklB
EO0ZPsB32FfEhRVqifsHM+dO/cfNZbsE+GZs5huON3kycoXbpII3gKc2X4G2Ti4281PeMafX9HOEBvXbt6Gz1XOjKGfi
2UATJWl2mkaQK35m4C9Ul/cXfchQachIS5wafv27UvSkqBUJkdGRjaLRMKHuhUwjuDTuDt37hBLS8tvxDrrS4Lm5eX1S
tBfXPvVRpYkQ30WdCoJqK3IEOik8WVQVHYeUfetmgddE6+SBw3+1N+Ya9JnBIU79wGJeAuqC0GpLKVJdhF5H1jD1fCJt
7d3ubqgoC8JWlRU9DM715ycHBUXjwDklMC1Rx8icKkr9RjWwmKy78/UCnNWOfFVJOr7JUFpOqiysjKTZ9MaiI4EpQn00
/fv3+czA83t3FsQGxtLy38e6vrpC4LSKhIQ8uzZs1Z2rsePHy/jrOfHPEHMR79dqslFSpRgu/D4Ts7Vt6F9q98TFOv0H
t0n+u2uAVAEXEekXc+T8/Lly8TJyclbV4LS6DEgIOCRppwktbLKw7iJrgTFTzLgqAHXpFhZReKPKCQ8PPyfDDldeNduE
7isHZfeMQQRBjuOzHRed5r/4ukBWst+TVBsaryxy0g0yEEN/JoyZdMl+GpK8EX9qVOnbkp4nhlIuot+/V9RUUHGjRt3q
rcOUOoMZ+
+7fv16PXfdsrq6utnYa7Jjxw56rvRWvhRmIEuO8JvJg/Rl22BALsiRHqpRyZ8mXenJEduGro3j00T6ljp7E8flqZXM2V
ghZlGS8EUTMRaQ+yMeHh6Nygi0R/AXkBWsXmZm5jUpD0ST7rTixd4LQpF58+bR/xb1+n+cxMTEMFql6r43NzdX8J+kuL
g4K1jVVmOtB/7BQKKjoyn5vmLytyEgSrt8Uy6hoB98oPJz0wh86CqDdo/ThaQrzSBH18fT+MpoHXvNJf4crHjE741JUP
sluyq6x3OO/a5T9HwC1BoRxWrc1AxOT+oHITT4yebupbk2qd+O0nNXDXNvlkhi/qoR1+MxEM2NSfOXDZyOp5E4kSaydt
1jBXDXKoExRj6iZzDjPTQZkAEZkAEZED3l/yw2+Xsa+AiKAAAAAElFTkSuQmCC"></img>
</par>
</body>
</smil>
Poniższa tabela przedstawia parametry niezbędne do wysłania wiadomości MMS.
Parametr | Opis |
---|---|
access_token | token przypisany do konta w serwisie SMSAPI |
to | Numer odbiorcy wiadomości w formacie 48xxxxxxxxx lub xxxxxxxxx. |
group | Nazwa grupy kontaktów z książki telefonicznej, do których ma zostać wysłana wiadomość |
subject | Temat wiadomości MMS. Temat może zawierać maksymalnie 30 znaków, w przypadku przekroczenia limitu wiadomość jest odrzucana i zwracany jest błąd 26. |
date | Data w formacie unixtime (&date=1287734110) lub ISO 8601 (&date=2012-05-10T08:40:27+00:00) kiedy wiadomość ma być wysłana |
date_validate | Ustawienie „1” sprawdza poprawność formatu podanej daty. W przypadku wystąpienia błędnej daty zwrócony zostanie błąd ERROR:54 |
smil | Wiadomość MMS w formacie SMIL 1.0 |
idx | Opcjonalny parametr użytkownika wysyłany z wiadomością a następnie zwracany przy wywołaniu zwrotnym CALLBACK. Parametr idx może mieć maksymalnie 255 znaków dopuszczalne są cyfry 0 - 9 oraz litery a – z (wielkość liter nie jest rozróżniana). (&idx=123) |
check_idx | Pozwala zabezpieczyć przed wysłanie dwóch wiadomości z identyczną wartością parametru idx. W przypadku ustawienia parametru (&check_idx=1) system sprawdza czy wiadomość z takim idx już została przyjęta, jeśli tak zwracany jest błąd 53. |
notify_url | Parametr do podawania URL do skryptu callback do odbierania raportów doręczeń. Jeżeli na koncie nie ma ustawionego stałego adresu callback dlr lub jeżeli dla tej wiadomości adres ten ma być inny niż stały można go podać w parametrze ¬ify_url. |
test | Wiadomość nie jest wysyłana, wyświetlana jest jedynie odpowiedź (w celach testowych). (&test=1) |
format | Dla &format=json powoduje, że zwrotka z API wysyłana jest w formacie JSON |
W razie problemów podczas odwoływania się do podstawowego adresu URL można wykorzystać adres URL backup https://api2.smsapi.pl/
8. Wiadomości VMS
https://api.smsapi.pl/vms.do
- dla połączeń szyfrowanych SSL
curl -H "Authorization Bearer access_token" \
"https://api.smsapi.pl/vms.do?\
to=48500000000&\
tts=treść_Wiadomości"
<?php
$params = array(
'acces_token' => 'smsapi_token', //token SMSAPI
'to' => '48500000000', //numer odbiorcy
'tts' => 'Treść_Wiadomości', //pole nadawcy
);
?>
Lub :
curl -H "Authorization Bearer access_token" \
"https://api.smsapi.pl/vms.do?\
to=48500000000&\
file=http://hiper.lacze.do/pliku.wav"
<?php
$params = array(
'acces_token' => 'smsapi_token', //token SMSAPI
'to' => '48500000000', //numer odbiorcy
'file' => 'http://hiper.lacze.do/pliku.wav', //pole nadawcy
);
?>
Poniższa tabela przedstawia parametry niezbędne do wysłania wiadomości VMS:
Parametr | Opis |
---|---|
access_token | token przypisany do konta w serwisie SMSAPI |
to | Numer odbiorcy wiadomości w formacie 48xxxxxxxxx lub xxxxxxxxx. |
group | Nazwa grupy kontaktów z książki telefonicznej, do których ma zostać wysłana wiadomość |
tts | Treść wiadomości głosowej w postaci tekstu. Tekst powinien być podawany w kodowaniu UTF-8, w przeciwny razie zostanie zwrócony błąd Error:11 . |
file | Treść wiadomości w postaci pliku wave, akceptowalny link do pliku umieszczonego w sieci lub plik wysłany postem metodą multipart form-data |
date | Data w formacie unixtime (&date=1287734110) lub ISO 8601 (&date=2012-05-10T08:40:27+00:00) kiedy wiadomość ma być wysłana |
date_validate | Ustawienie „1” sprawdza poprawność formatu podanej daty. W przypadku wystąpienia błędnej daty zwrócony zostanie błąd ERROR:54 |
try | Ilość prób połączenia (dopuszczalne wartości od 1 do 6) |
interval | Czas w sekundach po jakim powtórzone ma być połączenie w przypadku jego nieodebrania lub odrzucenia (dopuszczalne wartości od 300 do 7200s) |
skip_gsm | Ustawienie tego parametru (&skip_gsm=1) spowoduje pominięcie telefonów komórkowych podczas wysyłki i wysłanie wiadomości tylko do numerów stacjonarnych |
check_idx | Pozwala zabezpieczyć przed wysłanie dwóch wiadomości z identyczną wartością parametru idx. W przypadku ustawienia parametru (&check_idx=1) system sprawdza czy wiadomość z takim idx już została przyjęta, jeśli tak zwracany jest błąd 53. |
notify_url | Parametr do podawania URL do skryptu callback do odbierania raportów doręczeń. Jeżeli na koncie nie ma ustawionego stałego adresu callback dlr lub jeżeli dla tej wiadomości adres ten ma być inny niż stały można go podać w parametrze ¬ify_url. |
test | Wiadomość nie jest wysyłana, wyświetlana jest jedynie odpowiedź (w celach testowych). (&test=1) |
format | Dla &format=json powoduje, że zwrotka z API wysyłana jest w formacie JSON |
W razie problemów podczas odwoływania się do podstawowego adresu URL można wykorzystać adres URL backup https://api2.smsapi.pl/
9. Raporty doręczenia
9.1 Raporty SMS
<?php
if($_GET['MsgId'] && $_GET['status'] ) {
mysqli_select_db('database_name',mysqli_connect('localhost','login','password'));
$arIds = explode(',',$_GET['MsgId']);
$arStatus = explode(',',$_GET['status']);
$arIdx = explode(',',$_GET['idx']);
if($arIds){
foreach($arIds as $k => $v){
mysqli_query("UPDATE sms SET sms_status = '".mysqli_real_escape_string($arStatus[$k])."',
sms_index = '".mysqli_real_escape_string($arIdx[$k])."' WHERE sms_id ='".mysqli_real_escape_string($v)."' LIMIT 1");
}
mysqli_close();
echo"OK";
}
?>
W celu sprawdzenia statusu wiadomości należy w panelu klienta Adresy Callback ustawić adres do skryptu do którego przekazywany będzie raport doręczenia wiadomości. Aby móc wprowadzić adres callback, skrypt musi być umieszczony w podanej lokalizacji.
Przykład: http://www.moja_strona.pl/status_update.php
Ważne, aby podany adres był poprawny, tzn. aby wskazany skrypt istniał na serwerze. W momencie dodawania adresu do skryptu callback w panelu SMSAPI, weryfikowany jest on poprzez odwołanie się do niego z pustą tablicą GET. Do skryptu wysyłane będą status wiadomości (od 1 do 5 w zależności od tego dla ilu wiadomości zmienił się status). Parametry będą podane metodą GET i będą oddzielone przecinkami.
Parametr | Opis |
---|---|
MsgId | ID wysłanej wiadomości.Parametr MsgId jest parametrem o zmiennej długości, ale nie większej niż 32 znaki. |
status | Kod statusu doręczenia. |
status_name | Nazwa statusu doręczenia. |
idx | Opcjonalny parametr użytkownika wysłany z SMS'em |
donedate | Czas dostarczenia wiadomości w formacie unixtime |
username | Nazwa użytkownika wysyłającego wiadomość |
points | Ilość punktów pobranych za wysyłkę wiadomości |
from | Pole nadawcy z którym została wysłana wiadomość |
to | Numer na jaki wysyłana była wiadomość |
mcc | Kod Mobile Country Code identyfikujący jednoznacznie kraj przynależności numeru |
mnc | Kod Mobile Network Code identyfikujący jednoznacznie sieć w ramach kraju (MCC) do której numer należy. |
Skrypt powinien zwracać OK, w innym przypadku nastąpią ponowne odwołania.
9.2. Raporty MMS
W celu sprawdzenia statusu wiadomości należy w panelu klienta Adresy Callback ustawić adres do skryptu do którego przekazywany będzie raport doręczenia wiadomości.
Przykład: http://www.moja_strona.pl/status_update.php
Ważne, aby podany adres był poprawny, tzn. aby wskazany skrypt istniał na serwerze. W momencie dodawania adresu do skryptu callback w panelu SMSAPI, weryfikowany jest on poprzez odwołanie się do niego z pustą tablicą GET.
Poniższa tabela przedstawia wysyłane parametry:
Parametr | Opis |
---|---|
MsgId | ID wysłanej wiadomości. Parametr MsgId jest parametrem o zmiennej długości, ale nie większej niż 32 znaki. |
status | Kod doręczenia wiadomości |
to | Numer na jaki wysyłana była wiadomość |
idx | Opcjonalny parametr użytkownika wysłany z MMS'em |
donedate | Czas dostarczenia wiadomości w formacie unixtime |
username | Nazwa użytkownika z którego została wysłana wiadomość |
Skrypt powinien zwracać OK, w innym przypadku nastąpią ponowne odwołania.
9.3 Raport VMS
W celu sprawdzenia statusu wiadomości należy w panelu klienta Adresy Callback ustawić adres do skryptu do którego przekazywany będzie raport doręczenia wiadomości.
Przykład: http://www.moja_strona.pl/status_update.php
Ważne, aby podany adres był poprawny, tzn. aby wskazany skrypt istniał na serwerze. W momencie dodawania adresu do skryptu callback w panelu SMSAPI, weryfikowany jest on poprzez odwołanie się do niego z pustą tablicą GET.
Poniższa tabela przedstawia wysyłane parametry:
Parametr | Opis |
---|---|
MsgId | ID wysłanej wiadomości. Parametr MsgId jest parametrem o zmiennej długości, ale nie większej niż 32 znaki. |
status | Kod doręczenia wiadomości |
to | Numer na jaki wysyłana była wiadomość |
idx | Opcjonalny parametr użytkownika wysłany z MMS'em |
donedate | Czas dostarczenia wiadomości w formacie unixtime |
username | Nazwa użytkownika z którego została wysłana wiadomość |
pressed | Klawisz wybrany przez odbiorcę wiadomości podczas jej odsłuchiwania |
hangup_time | Czas trwania połączenia |
Skrypt powinien zwracać OK, w innym przypadku nastąpią ponowne odwołania.
10. CALLBACK
10.1 Wysyłki masowe
Do skryptu CALLBACK dla wysyłek masowych wysyłane jest odwołanie w momencie rozpoczęcia wysyłania danej wysyłki. Odwołanie zawiera parametry przedstawione w tabeli poniżej. W celu włączenia CALLBACK'a dla wysyłek masowych należy w panelu klienta Adresy Callback ustawić adres do skryptu do którego przekazywane będą statusy wysyłek masowych
Przykład: http://www.moja_strona.pl/bulk_callback.php
Ważne, aby podany adres był poprawny, tzn. aby wskazany skrypt istniał na serwerze. W momencie dodawania adresu do skryptu callback w panelu SMSAPI, weryfikowany jest on poprzez odwołanie się do niego z pustą tablicą GET.
Poniższa tabela przedstawia wysyłane parametry:
Parametr | Opis |
---|---|
type | Typ wiadomości SMS/MMS/VMS |
all | Liczba wiadomości (numerów) w wysyłce. |
points | Liczba pobranych punktów za wysyłkę. |
to | Określa gdzie (za pomocą której zakładki bramki SMS) została wysłana wysyłka csv, csv_and_text lub phonebook. |
info | W przypadku wysyłki to numerów z Bazy lista grup do których zostały wysłane wiadomości. |
text | Tekst wysłanej wiadomości. |
Skrypt powinien zwracać OK, w innym przypadku nastąpią ponowne odwołania.
10.2 Kliknięcia idz.do
W celu sprawdzenia kliknięć w link idz.do należy w panelu klienta Adresy Callback ustawić adres do skryptu do którego przekazywany będzie raport kliknięć idz.do.
Przykład: http://www.moja_strona.pl/idzdo_callback.php
Ważne, aby podany adres był poprawny, tzn. aby wskazany skrypt istniał na serwerze. W momencie dodawania adresu do skryptu callback w panelu SMSAPI, weryfikowany jest on poprzez odwołanie się do niego z pustą tablicą GET.
Poniższa tabela przedstawia wysyłane parametry:
Parametr | Opis |
---|---|
MsgId | ID wysłanej wiadomości. Parametr MsgId jest parametrem o zmiennej długości, ale nie większej niż 32 znaki. |
to | Numer na jaki wysyłana była wiadomość |
click_date | Czas pierwszego otwarcia odnośnika w formacie unixtime |
device | Typ urządzenia |
operating_system | System operacyjny |
browser | Rodzaj przeglądarki |
username | Nazwa użytkownika z którego została wysłana wiadomość |
ip | Adres IP z którego nastąpiło kliknięcie w skrócony link |
sufix | Sufiks skróconego adresu, np. Hq9Y(dla http://idz.do/Hq9Y) |
Skrypt powinien zwracać OK, w innym przypadku nastąpią ponowne odwołania.
11. Odbiory Wiadomości
Serwis SMSAPI oferuje również odbiór wiadomości SMS oraz MMS. Odbierać można wiadomości SMS i/lub MMS wysłane na wykupiony numer dedykowany lub odpowiedzi na wysłane wiadomości 2way.
Czas oczekiwania na wiadomość zwrotną od adresata w systemie 2Way wynosi 24h. Po tym czasie wiadomość nie zostanie przypisana do konta klienta
11.1 Odbiór SMS
<?php
function messageReceive()
{
$received = $_POST;
$content = print_r($received, true);
$sms_from = $received['sms_from'];
$sms_to = $received['sms_to'];
$sms_date = $received['sms_date'];
$sms_text = $received['sms_text'];
$username = $received['username'];
$filename = "sms.log";
file_put_contents($filename, $content);
if (is_file($filename)) {
return true;
} else {
return false;
}
}
if ($_POST) {
if (messageReceive() === true) {
echo "OK";
}
}
?>
Odbiór wiadomości odbywać się będzie za pomocą skryptu, do którego adres należy ustawić w Adresy Callback.
Działanie skryptu opisane jest poniżej:
Po odebraniu wiadomości odwoływać będziemy się do skryptu stworzonego przez Państwa, który powinien obsługiwać następujące parametry z tablicy POST:
Parametr | Opis |
---|---|
sms_to | numer telefonu odbiorcy |
sms_from | numer telefonu nadawcy |
sms_text | treść wiadomości |
sms_date | czas w postaci unixtime pobrany z SMS'a |
username | nazwa użytkownika (login) do którego wiadomość została przydzielona |
MsgId | id wiadomości 2way na którą jest to odpowiedź, dla odpowiedzi na numer dedykowany pole to będzie puste. Parametr MsgId jest parametrem o zmiennej długości, ale nie większej niż 32 znaki. |
Dane wysyłane są w kodowaniu UTF8.
Skrypt powinien zwracać OK, w innym przypadku nastąpią ponowne odwołania.
W momencie dodawania adresu do skryptu callback w panelu SMSAPI, weryfikowany jest on poprzez odwołanie się do niego z pustą tablicą GET.
11.2 Odbiór MMS
<?php
function receiveMms()
{
$received = false;
foreach ($_FILES as $plik)
{
if (is_uploaded_file($plik['tmp_name']))
{
if (move_uploaded_file($plik['tmp_name'],'mms/'.$plik['name'])) {
$received = true;
}
}
}
return $received;
}
if ($_FILES) {
if (receiveMms() === true) {
echo "OK";
}
}
?>
Odbiór wiadomości odbywać się będzie za pomocą skryptu, do którego adres należy ustawić w Adresy Callback. Działanie skryptu opisane jest poniżej:Po odebraniu wiadomości odwoływać będziemy się do skryptu stworzonego przez Państwa, który powinien obsługiwać parametry z tablicy POST oraz FILES podane poniżej:
Tablica POST:
Parametr | Opis |
---|---|
mms_to | numer telefonu odbiorcy |
mms_from | numer telefonu nadawcy |
mms_subject | temat wiadomości |
mms_date | czas w postaci unixtime pobrany z MMS'a |
Tablica FILES:
Parametr | Opis |
---|---|
name | oryginalna nazwa wysyłanego pliku |
type | typ MIME wysyłanego pliku (JPEG, GIF, ...) |
tmp_name | tymczasowa nazwa pliku, który został wysłany na serwer |
error | numer błędu (0 oznacza prawidłowe wysłanie) |
size | rozmiar wysyłanego pliku (w bajtach) |
Dane wysyłane są w kodowaniu UTF8.
Skrypt powinien zwracać OK (np. echo 'OK';), w innym przypadku nastąpią ponowne odwołania.
12. HLR
curl -H "Authorization Bearer access_token" \
"https://api.smsapi.pl/hlr.do?\
number=48500000000&\
format=json"
<?php
$params = array(
'acces_token' => 'smsapi_token', //token SMSAPI
'numer' => '48500000000', //numer do sprawdzenia
'format' => 'Treść_Wiadomości',
);
if ($params['access_token']&&$params['number']&&$params['format']) {
$date = '?'.http_build_query($params);
$file = fopen('https://api.smsapi.pl/hlr.do'.$date,'r');
$result = fread($file,1024);
fclose($file);
echo $result;
}
?>
HLR (ang. Home Location Register) – Rejestr Abonentów Macierzystych – element infrastruktury telekomunikacyjnej zawierający informacje o każdym aktywnym numerze GSM. W celu skorzystania z tej opcji należy wysłać żądanie pod adres: https://api.smsapi.pl/hlr.do z parametrami opisanymi w tabeli poniżej. Informacje o numerach będą wysłane do skryptu do którego adres należy podać w panelu klienta na stronie https://api.smsapi.pl w menu Adresy Callback w polu „Adres callback - odwołania HLR”.
Ważne aby wprowadzony adres URL prowadził do istniejącego, działającego skryptu. Po sprawdzeniu numeru w systemie HLR informacja o nim zostanie przesłana do podanego adresu URL w postaci tablicy POST. W jednym odwołaniu może znajdować się do 20 numerów.
Poniższa tabela przedstawia parametry odwołania HLR:
Parametr | Opis |
---|---|
access_token | token przypisany do konta w serwisie SMSAPI |
number | Numer/y, które mają być sprawdzone w HLR. |
idx | Opcjonalny parametr użytkownika wysyłany z odwołaniem, a następnie zwracany przy wywołaniu zwrotnym CALLBACK. Parametr idx może mieć maksymalnie 255 znaków dopuszczalne są cyfry 0- 9 oraz litery a – z (wielkość liter nie jest rozróżniana). (&idx=123) |
format | Dla &format=json powoduje, że zwrotka z API wysyłana jest w formacie JSON. |
Poniższa tabela przedstawia parametry wysyłane do skryptu:
Parametr | Opis |
---|---|
id | id zwrócony podczas sprawdzania numeru |
number | sprawdzany numer |
mcc | numer identyfikujący kraj (ang. Mobile Country Code) |
mnc | numer sieci w danym kraju (ang. Mobile Network Code) |
info | nazwa sieci, do której należy numer, lub opis błędu |
status | OK kiedy numer jest poprawny, FAIL kiedy numer jest błędny (np. wyłączony, nieaktywny itp.) |
date | Data w formacie UNIX timestamp, kiedy numer był sprawdzany |
ported | 0 jeżeli numer jest nieprzeniesiony, 1 jeżeli numer jest przeniesiony |
ported_from | null kiedy numer jest nieprzeniesiony lub nazwa sieci z której numer został przeniesiony |
idx | Opcjonalny parametr użytkownika wysłany z zapytaniem HLR |
13. Konto użytkownika
13.1 Dodawanie użytkownika
Przykład:
curl -H "Authorization: Bearer access_token" \
"https://api.smsapi.pl/user.do?\
password=&\
add_user=subuser&\
pass=subuser_md5_password\
format=json"
Przykład odpowiedzi:
OK:<SUB_NAME>
ERROR:<ERR>
Przykład odpowiedzi gdy &format = :
{
"username":"subuser",
"limit":0,
"month_limit":0, // miesięczny limit odnawialny
"senders":0, // dostęp do pól nadawcy konta głównego
"phonebook":0, // dostęp do bazy kontaktów konta głównego
"active":false,
"info":"unknown"
}
Gdy wystąpi błąd:
{
"error": 123,
"message": "error message"
}
W celu dodania nowego konta użytkownika należy w odwołaniu umieścić parametr &add_user=poduzytkownik oraz parametry określające właściwości dodawanego konta.
Zarządzanie kontem odbywa się przez wysłanie metodą GET lub POST danych do adresu połączenia odpowiednich parametrów:
Parametr | Opis |
---|---|
access_token | Token przypisany do konta w serwisie SMSAPI |
add_user | Nazwa dodawanego użytkownika |
pass | Hasło do panelu klienta SMSAPI dodawanego |
pass_api | Hasło do interfejsu API dla użytkownika brak tego parametru spowoduje ustawienie jako hasła do API kopii hasła do panelu klient |
limit | Limit punktów przydzielony użytkownikowi |
month_limit | Ilość punktów która będzie przypisana do konta użytkownika każdego pierwszego dnia |
senders | Udostępnienie pól nadawców konta głównego (dostępne wartości: 1 – udostępniaj, 0 – nie udostępniaj, domyślnie wartość równa 0) |
phonebook | Udostępnienie grup książki telefonicznej konta głównego (dostępne wartości: 1 – udostępniaj, 0 – nie udostępniaj, domyślnie wartość równa 0). Po udostępnieniu książki użytkownik będzie mógł wysyłać do grup wiadomości nie będzie jednak widział poszczególnych kontaktów w książce telefonicznej. |
active | Aktywowanie konta użytkownika (dostępne wartości: 1 – aktywne, 0 – nieaktywne, domyślnie wartość równa 0) |
info | Dodatkowy opis użytkownika |
format | Dla &format=json powoduje, że zwrotka z API wysyłana jest w formacie JSON, w zwrotce oprócz potwierdzenia , zawierająca następujące parametry: limit, limit_month, senders, phonebook, active, info. |
without_prefix | Ustawienie tego parametru pozwala na dodanie użytkownika bez prefixu użytkownika głównego (poduzytkownik zamiast uzytkownik_poduzutkownik) |
13.2 Edycja użytkownika
curl -H "Authorization: Bearer access_token" \
"https://api.smsapi.pl/user.do?\
set_user=subuser&\
pass=new_subuser_password_in_md5&\
active=1&\
format=json"
Przykład odpowiedzi:
OK:<SUB_NAME>
ERROR:<ERR>
Przykład odpowiedzi kiedy &format = json :
{
"username":"subuser",
"limit":0,
"month_limit":0,
"senders":0,
"phonebook":0,
"active":false,
"info":"unknown"
}
W przypadku wystąpienia błędu:
{
"error": 123,
"message": "error message"
}
W celu edycji parametrów istniejącego konta użytkownika należy w odwołaniu umieścić parametr &set_user=uzytkownik
oraz parametr odpowiadający właściwości, która ma zostać zmieniona.
Zarządzanie kontem odbywa się przez wysłanie metodą GET lub POST danych do adresu połączenia:
Parametr | Opis |
---|---|
access_token | Token przypisany do konta w serwisie SMSAPI |
set_user | Nazwa edytowanego użytkownika bez prefiksu użytkownika głównego |
pass | Hasło do panelu klienta SMSAPI dodawanego użytkownika |
pass_api | Hasło do interfejsu API dla użytkownika, brak tego parametru spowoduje ustawienie jako hasła do API kopii hasła do panelu klient |
limit | Limit punktów przydzielony użytkownikowi |
month_limit | Ilość punktów która będzie przypisana do konta użytkownika każdego pierwszego dnia |
senders | Udostępnienie pól nadawców konta głównego (dostępne wartości: 1 – udostępniaj, 0 – nie udostępniaj, domyślnie wartość równa 0) |
phonebook | Udostępnienie grup książki telefonicznej konta głównego (dostępne wartości: 1 – udostępniaj, 0 – nie udostępniaj, domyślnie wartość równa 0). Po udostępnieniu książki użytkownik będzie mógł wysyłać do grup wiadomości nie będzie jednak widział poszczególnych kontaktów w książce telefonicznej. |
active | Aktywowanie konta użytkownika (dostępne wartości: 1 – aktywne, 0 – nieaktywne, domyślnie wartość równa 0) |
info | Dodatkowy opis użytkownika |
format | Dla &format=json powoduje, że zwrotka z API wysyłana jest w formacie JSON, w zwrotce oprócz potwierdzenia , zawierająca następujące parametry: limit, limit_month, senders, phonebook, active, info. |
without_prefix | Ustawienie tego parametru pozwala na dodanie użytkownika bez prefixu użytkownika głównego (poduzytkownik zamiast uzytkownik_poduzutkownik) |
13.3 Dane użytkownika
curl -H "Authorization: Bearer access_token" \
"https://api.smsapi.pl/user.do?\
get_user=sub_user\
format=json"
Przykład odpowiedzi:
OK:<LIMIT>:<MONTH_LIMIT>:<SENDERS>:<PHONEBOOK>:<ACTIVE>:<INFO>
ERROR:<ERR>
Przykład odpowiedzi kiedy &format = json:
{
"username":"user_subuser",
"limit":"10.000",
"month_limit":"0.000",
"senders":0,
"phonebook":0,
"active":"1",
"info":"unknown"
}
W przypadku wystąpienia błędu:
{
"error": 123,
"message": "error message"
}
W celu pobrania informacji dotyczących istniejącego konta użytkownika należy w odwołaniu umieścić parametr &get_user=1.
Zarządzanie kontem odbywa się przez wysłanie metodą GET lub POST danych do adresu połączenia:
Parametr | Opis |
---|---|
access_token | Token przypisany do konta w serwisie SMSAPI |
get_user | Nazwa użytkownika bez prefiksu użytkownika głównego |
format | Dla &format=json powoduje, że zwrotka z API wysyłana jest w formacie JSON, w zwrotce oprócz potwierdzenia , zawierająca następujące parametry: limit, limit_month, senders, phonebook, active, info. |
without_prefix | Ustawienie tego parametru pozwala na dodanie użytkownika bez prefixu użytkownika głównego (poduzytkownik zamiast uzytkownik_poduzutkownik) |
13.4 Liczba punktów
curl -H "Authorization: Bearer access_token" \
"https://api.smsapi.pl/user.do?\
credits=1\
format=json"
Przykład odpowiedzi:
Points: <POINTS>
ERROR:<ERR>
Przykład odpowiedzi kiedy &format = json:
{
"points":6225.4875,
"proCount":"41503",
"
}
W przypadku wystąpienia błędu:
{
"error": 123,
"message": "error message"
}
W celu sprawdzenia ilości środków pozostałych na koncie dla istniejącego użytkownika należy w odwołaniu umieścić parametr &credits=1. Dodatkowo umieszczenie w odwołaniu parametru &details=1 powoduje oprócz ilości środków na koncie również zwrócenie ilości wiadomości dostępnych do wysłania.
Zarządzanie kontem odbywa się przez wysłanie metodą GET lub POST danych do adresu połączenia:
Parametr | Opis |
---|---|
access_token | Token przypisany do konta w serwisie SMSAPI |
credits | &credits=1 |
details | &details=1 powoduje dodatkowo zwrócenie ilości SMS, MMS, VMS (PRO, ECO, MMS, VMS_gsm, VMS_land) |
format | Dla &format=json powoduje, że zwrotka z API wysyłana jest w formacie JSON, w zwrotce oprócz potwierdzenia , zawierająca następujące parametry: limit, limit_month, senders, phonebook, active, info. |
without_prefix | Ustawienie tego parametru pozwala na dodanie użytkownika bez prefixu użytkownika głównego (poduzytkownik zamiast uzytkownik_poduzutkownik) |
13.5 Lista użytkowników
curl -H "Authorization: Bearer access_token" \
"https://api.smsapi.pl/user.do?\
list=1\
format=json"
Przykład odpowiedzi:
OK: subuser1:subuser2
ERROR:<ERR>
Przykład odpowiedzi kiedy &format = json:
[{
"username":"subuser1",
"limit":"10.0000",
"month_limit":"0.0000", /
"senders":"0",
"phonebook":"0",
"active":"1",
"info":"unknown"
},
"username":"subuser2",
"limit":"0.0000",
"month_limit":"0.0000", /
"senders":"0",
"phonebook":"0",
"active":"0",
"info":"unknown"
}]
W przypadku wystąpienia błedu:
{
"error": 123,
"message": "error message"
}
W celu pobrania listy użytkowników należy w odwołaniu umieścić parametr &list=1. Dodatkowo po dodaniu parametru &format=json w odpowiedzi zwracana jest tablica obiektów w formacie JSON zawierająca dane o kontach użytkowników jak dla parametru &get_user=1.
Zarządzanie kontem odbywa się przez wysłanie metodą GET lub POST danych do adresu połączenia:
Parametr | Opis |
---|---|
access_token | Token przypisany do konta w serwisie SMSAPI |
list | &list=1 zwraca listę użytkowników dla danego konta głównego |
format | Dla &format=json powoduje, że zwrotka z API wysyłana jest w formacie JSON, w zwrotce oprócz potwierdzenia , zawierająca następujące parametry: limit, limit_month, senders, phonebook, active, info. |
14. Pola nadawcy
14.1 Dodawanie pola nadawcy
Funkcja dodawania pól nadawcy wymaga dodatkowej aktywacji. Aby aktywować funkcję prosimy o kontakt z Biurem Obsługi Klienta.
14.2 Status pola nadawcy
curl -H "Authorization: Bearer access_token" \
"https://api.smsapi.pl/sender.do?\
status=sender\
format=json"
Przykład odpowiedzi:
OK:<STATUS>
ERROR:<ERR>
Przykład odpowiedzi kiedy &format = json :
{
"name":"SMSAPI",
"status":"ACTIVE"
"default":true
}
W przypadku wystąpienia błedu:
{
"error": 123,
"message": "error message"
}
Zarządzanie polami nadawcy odbywa się przez wysłanie metodą GET lub POST danych do adresu połączenia:
Parametr | Opis |
---|---|
access_token | Token przypisany do konta w serwisie SMSAPI |
status | Nazwa pola nadawcy, którego status ma być sprawdzony |
format | &format=json powoduje zwrócenie wyniku obiektu w formacie JSON zawierającego następujące parametry: nazwa_nadawcy, status oraz informację czy nazwa jest nazwą domyślną. |
14.3 Listy pól nadawcy
curl -H "Authorization: Bearer access_token" \
"https://api.smsapi.pl/sender.do?\
list=1\
format=json"
Przykład odpowiedzi:
OK:<SENDER_1>,<STATUS_1>:<SENDER_2>:<STATUS_2>...,...:...,...:...,...
ERROR:<ERR>
Przykład odpowiedzi kiedy &format = json:
[{
"sender":"SMSAPI",
"status":"ACTIVE",
"default":true
},
{
"sender":"SMSAPI.pl", /
"status":"INACTIVE",
"default":false
},
{
"sender":"SMS",
"status":"ACTIVE",
"default":false
}]
W przypadku wystąpienia błedu:
{
"error": 123,
"message": "error message"
}
W celu sprawdzenia listy dostępnych pól nadawcy, wraz z ich statusami, należy w odwołaniu umieścić parametr &list=1
Zarządzanie polami nadawcy odbywa się przez wysłanie metodą GET lub POST danych do adresu połączenia:
Parametr | Opis |
---|---|
access_token | Token przypisany do konta w serwisie SMSAPI |
format | &format=json powoduje zwrócenie w wyniku tablicy obiektów w formacie JSON zawierającego następujące parametry: nazwa_nadawcy, status oraz informację czy dana nazwa jest nazwą domyślną |
with_nat_names | Ustawienie tego parametru (&with_nat_names=1) powoduje wyświetlenie na liście również nazw udostępnionych przez użytkownika głównego (dla użytkowników) |
14.4 Domyślne pole nadawcy
curl -H "Authorization: Bearer access_token" \
"https://api.smsapi.pl/sender.do?\
default=default_name\
format=json"
Przykład odpowiedzi:
OK
ERROR:<ERR>
Przykład odpowiedzi kiedy &format = json:
{
"count": 1
}
W przypadku wystąpienia błędu:
{
"error": 123,
"message": "error message"
}
Domyślne pole nadawcy jest to nazwa, z która zostanie wysłana wiadomość w przypadku przesłania parametru &from lub gdy parametr ten jest pusty. Pole nadawcy ustawiane jako domyślne musi być aktywne. W przypadku braku domyślnego pola nadawcy wiadomości takie wysyłane są z nazwą SMSAPI.
W celu ustawienia nazwy jako domyślne pole nadawcy należy umieścić parametr &default=nazwa, gdzie nazwa jest nazwą pola nadawcy, które ma być domyślnym.
Zarządzanie polami nadawcy odbywa się przez wysłanie metodą GET lub POST danych do adresu połączenia:
Parametr | Opis |
---|---|
access_token | Token przypisany do konta w serwisie SMSAPI |
default | Nazwa, która ma być ustawiona jako domyślna |
format | Dla &format=json powoduje, że zwrotka z API wysyłana jest w formacie JSON |
Multi-factor authentication
Usługa Multi-factor authentication (MFA) może pomóc podnieść poziom bezpieczeństwa użytkownika na witrynach, na których podaje on swoje dane. Pozwoli ona w zautomatyzowany sposób sprawdzić poprawność numeru telefonu i potwierdzić, że numer należy faktycznie do niego przez wysłanie wiadomości SMS z kodem weryfikacyjnym oraz potwierdzenie poprawności kodu. Wysyłka SMS oraz sprawdzanie poprawności kodu jest wykonywana przez SMSAPI.
Wysyłka kodu
curl -H "Authorization Bearer access_token"\
"Content-Type: application/json" -X POST -d\
'{"phone_number":"48500500500"}'\
https://api.smsapi.pl/mfa/codes
Przykład odpowiedzi :
{"id":"5AA7A7BA3738303CBB1EA1D6","code":"861214","phone_number":"48500500500"}
Po podaniu przez Klienta numeru telefonu należy umieścić go w zapytaniu do API. Na ten numer zostanie wysłany SMS z losowym kodem, wygenerowanym automatycznie przez usługę. Kolejnym krokiem będzie przepisanie przez Klienta kodu z wiadomości do odpowiedniego miejsca w serwisie. Kolejnym krokiem będzie sprawdzenie, czy kod wprowadzony przez użytkownika jest zgodny z tym wysłanym SMSem.
Sprawdzenie poprawności kodu
curl -H "Authorization Bearer access_token"\
"Content-Type: application/json" -X POST -i -d\
'{"phone_number":"48500500500","code":"861214"}'\
https://api.smsapi.pl/mfa/codes/verifications
Przykład odpowiedzi :
HTTP/1.1 204
Sprawdzenie poprawności kodu wpisanego przez użytkownika odbywa się przez zapytanie do API. W treści zapytania jest wpisany numer telefonu, dla którego przeprowadzana jest weryfikacja oraz kodu, wprowadzonego przez użytkownika. W odpowiedzi zostanie zwrócony jeden z poniższych statusów:
Status | Opis |
---|---|
204 | Kod poprawny |
404 | Błędny kod |
408 | Kod przedawniony |
Interfejs SMPP
Protokół SMPP
SMPP (Short Message Peer-to-Peer) jest otwartym, ustandaryzowanym protokołem zaprojektowanym do bezpośredniej komunikacji pomiędzy systemami teleinformatycznymi, takimi jak operatorskie Centrum SMS (SMSC) oraz Systemy przesyłania wiadomości SMS (SME/ESME) w celu przesyłu krótkich wiadomości tekstowych SMS. Protokół SMPP wykorzystywany jest w SMSAPI głównie do komunikacji z polskimi sieciami komórkowymi oraz agregatorami SMS dla wysyłek zagranicznych (połączenia ESME <-> SMSC). Dla serwisów posiadających własny rozbudowany system obsługi klientów szukających dostawcy usługi wysyłki wiadomości SMS platforma SMSAPI w razie potrzeby może udostępnić połączenie do własnego SMSC za pomocą interfejsu SMPP.
Protokół SMPP oparty jest na binarnie zakodowanych parach pakietów zapytań/odpowiedzi (request/response PDUs) przesyłanych za pomocą warstwy transportowej modelu OSI. Dane pomiędzy peer'ami wymieniane mogą być synchronicznie, gdzie po każdym wysłanym pakiecie oczekiwana jest odpowiedź przed wysłaniem kolejnego, oraz asynchroniczne gdzie dozwolone jest wysyłanie większej liczby pakietów bez odpowiedzi potwierdzającej ich odebranie. Dozwolona liczba zapytań bez odpowiedzi, nazywana oknem, powinna być identyczna dla obu stron komunikacji dla zapewnienia najwyższej jakości usługi.
Sposób komunikacji wykorzystywany w protokole SMPP sprawia, że dla poprawnego wysłania wiadomości SMS nie jest konieczne wykorzystywanie telefonów komórkowych, modemów GSM czy kart SIM. Dodatkowo udostępnia on wiele funkcjonalności niedostępnych przy użyciu standardowych urządzeń komunikacji GSM jak np. przesyłanie wiadomości z alfanumerycznym polem nadawcy zamiast standardowego numeru telefonu.
Szczegółowe informacje oraz dostęp do połączenia SMPP można uzyskać w Biurze Obsługi Klienta - kontakt
Lista statusów doręczenia
Kod | Status ANG | Status | Opis |
---|---|---|---|
401 | NOT_FOUND | Nieznaleziona | Błędny numer ID lub raport wygasł |
402 | EXPIRED | Przedawniona | Wiadomość niedostarczona z powodu zbyt długiego czasu niedostępność numeru |
403 | SENT | Wysłana | Wiadomość została wysłana ale operator nie zwrócił jeszcze raportu doręczenia |
404 | DELIVERED | Dostarczona | Wiadomość dotarła do odbiorcy |
405 | UNDELIVERED | Niedostarczona | Wiadomość niedostarczona (np.: błędny numer, numer niedostępny) |
406 | FAILED | Nieudana | Błąd podczas wysyłki wiadomości - prosimy zgłosić |
407 | REJECTED | Odrzucona | Wiadomość niedostarczona (np.: błędny numer, numer niedostępny) |
408 | UNKNOWN | Nieznany | Brak raportu doręczenia dla wiadomości (wiadomość doręczona lub brak możliwości doręczenia) |
409 | QUEUE | Kolejka | Wiadomość czeka w kolejce na wysyłkę |
410 | ACCEPTED | Zaakceptowana | Wiadomość przyjęta przez operatora |
411 | RENEWAL | Ponawianie | Wykonana była próba połączenia która nie została odebrana, połączenie zostanie ponowione. |
412 | STOP | Zatrzymanie | Zatrzymanie |
Kody błędów
ERROR | Opis |
---|---|
8 | Błąd w odwołaniu (Prosimy zgłosić) |
11 | Zbyt długa lub brak wiadomości lub ustawiono parametr nounicode i pojawiły się znaki specjalne w wiadomości. Dla wysyłki VMS błąd oznacz brak pliku WAV lub błąd tekstu TTS (brak tekstu lub inne niż UTF-8 kodowanie). |
12 | Wiadomość składa się z większej ilości części niż określono w parametrze &max_parts |
13 | Brak prawidłowych numerów telefonów (numer błędny, stacjonarny (w przypadku wysyłki SMS) lub znajdujący się na czarnej liście) |
14 | Nieprawidłowe pole nadawcy |
17 | Nie można wysłać FLASH ze znakami specjalnymi |
18 | Nieprawidłowa liczba parametrów |
19 | Za dużo wiadomości w jednym odwołaniu |
20 | Nieprawidłowa liczba parametrów IDX |
21 | Wiadomość MMS ma za duży rozmiar (maksymalnie 300kB) |
22 | Błędny format SMIL |
23 | Błąd pobierania pliku dla wiadomości MMS lub VMS |
24 | Błędny format pobieranego pliku |
25 | Parametry &normalize oraz &datacoding nie mogą być używane jednocześnie. |
26 | Za długi temat wiadomości. Temat może zawierać maksymalnie 30 znaków. |
27 | Parametr IDX za długi. Maksymalnie 255 znaków |
28 | Błędna wartość parametru time_restriction. Dostępne wartości to FOLLOW, IGNORE lub NEAREST_AVAILABLE. |
30 | Brak parametru UDH jak podany jest datacoding=bin |
31 | Błąd konwersji TTS |
32 | Nie można wysyłać wiadomości Eco, MMS i VMS na zagraniczne numery lub wysyłka na zagranicę wyłączona na koncie. |
33 | Brak poprawnych numerów |
35 | Błędna wartość parametru tts_lector. Dostępne wartości: agnieszka, ewa, jacek, jan, maja |
36 | Nie można wysyłać wiadomości binarnych z ustawioną stopką. |
40 | Brak grupy o podanej nazwie |
41 | Wybrana grupa jest pusta (brak kontaktów w grupie) |
50 | Nie można zaplanować wysyłki na więcej niż 3 miesiące w przyszłość |
51 | Ustawiono błędną godzinę wysyłki, wiadomość VMS mogą być wysyłane tylko pomiędzy godzinami 8 a 22 lub ustawiono kombinację parametrów try i interval powodującą możliwość próby połączenia po godzinie 22. |
52 | Za dużo prób wysyłki wiadomości do jednego numeru (maksymalnie 10 prób w przeciągu 60sek do jednego numeru) |
53 | Nieunikalny parametr idx. Wiadomość o podanym idx została wysłana w ostatnich czterech dniach lub jest zaplanowana do wysyłki w przyszłości przy wykorzystaniu parametru &check_idx=1. |
54 | Błędny format daty. Ustawiono sprawdzanie poprawności daty &date_validate=1 |
55 | Brak numerów stacjonarnych w wysyłce i ustawiony parametr skip_gsm |
56 | Różnica pomiędzy datą wysyłki, a datą wygaśnięcia nie może być mniejsza niż 15 minut i większa niż 72 godzin |
57 | Numer znajduje się na czarnej liście dla danego użytkownika. |
60 | Grupa kodów o podanej nazwie nie istnieje. |
61 | Data ważności grupy kodów minęła. |
62 | Brak wolnych kodów w podanej grupie (wszystkie kody zostały już wykorzystane). |
65 | Brak wystarczającej liczby kodów rabatowych dla wysyłki. Liczba niewykorzystanych kodów w grupie musi być co najmniej równa liczbie numerów w wysyłce. |
66 | W treści wiadomości brak jest znacznika [%kod%] dla wysyłki z parametrem &discount_group (znacznik taki jest wymagany). |
70 | Błędny adres CALLBACK w parametrze notify_url. |
74 | Data wysyłki nie spełnia ograniczeń czasowych ustawionych na koncie |
101 | Niepoprawne lub brak danych autoryzacji |
102 | Nieprawidłowy login lub hasło |
103 | Brak punków dla tego użytkownika |
104 | Brak szablonu |
105 | Błędny adres IP (włączony filtr IP dla interfejsu API) |
110 | Usługa (SMS, MMS, VMS lub HLR) nie jest dostępna na danym koncie. |
200 | Nieudana próba wysłania wiadomości, prosimy ponowić odwołanie |
201 | Wewnętrzny błąd systemu (prosimy zgłosić) |
202 | Zbyt duża ilość jednoczesnych odwołań do serwisu, wiadomość nie została wysłana (prosimy odwołać się ponownie) |
203 | Zbyt wiele odwołań do serwisu. Spróbuj ponownie później. |
300 | Nieprawidłowa wartość pola points (przy użyciu pola points jest wymagana wartość 1) |
301 | Wiadomość o podanym ID nie istnieje lub jest zaplanowana do wysłania w przeciągu najbliższych 60 sekund (nie można usunąć takiej wiadomości). |
400 | Nieprawidłowy ID statusu wiadomości. |
999 | Wewnętrzny błąd systemu (prosimy zgłosić) |
1000 | Akcja dostępna tylko dla użytkownika głównego |
1001 | Nieprawidłowa akcja (oczekiwane jedna z add_user, set_user, get_user, credits) |
1010 | Błąd dodawania użytkownika |
1020 | Błąd edycji konta użytkownika |
1021 | Brak danych do edycji, przynajmniej jeden parametr musi być edytowany |
1030 | Błąd pobierania danych użytkownika |
1032 | Nie istnieje użytkownik o podanej nazwie dla danego użytkownika głównego |
1100 | Błąd danych użytkownika |
1110 | Błędna nazwa tworzonego użytkownika |
1111 | Nie podano nazwy tworzonego konta użytkownika |
1112 | Nazwa konta użytkownika za krótka (minimum 3 znaki) |
1113 | Nazwa konta użytkownika za długa, łączna długość nazwy użytkownika wraz z prefiksem użytkownika głównego może mieć maksymalnie 32 znaki |
1114 | W nazwie użytkownika pojawiły się nidozwolone znaki, dozwolone są litery [A – Z], cyfry [0 – 9] oraz znaki @, -, _ i |
1115 | Istnieje już użytkownik o podanej nazwie |
1120 | Błąd hasła dla tworzonego konta użytkownika |
1121 | Hasło dla tworzonego konta użytkownika za krótkie |
1122 | Hasło dla tworzonego konta użytkownika za długie |
1123 | Hasło powinno być zakodowane w MD5 |
1130 | Błąd limitu punktów przydzielanego użytkownikowi |
1131 | Parametr limit powinno zawierać wartość numeryczną |
1140 | Błąd limitu miesięcznego punktów przydzielanego użytkownikowi |
1141 | Parametr month_limit powinno zawierać wartość numeryczną |
1150 | Błędna wartość parametru senders, dopuszczalne wartości dla tego parametru to 0 lub 1 |
1160 | Błędna wartość parametru phonebook, dopuszczalne wartości dla tego parametru to 0 lub 1 |
1170 | Błędna wartość parametru active, dopuszczalne wartości dla tego parametru to 0 lub 1 |
1180 | Błąd parametru info |
1183 | Zawartość parametru info jest za długa |
1190 | Błąd hasła do interfejsu API dla konta użytkownika |
1192 | Błędna długość hasła do interfejsu API dla konta użytkownika (hasło zakodowane w md5 powinno mieć 32 znaki) |
1193 | Hasło do interfejsu powinno zostać podane w formie zakodowanej w md5 |
2001 | Nieprawidłowa akcja (oczekiwane jedna z add, status, delete, list) |
2010 | Błąd dodawania pola nadawcy |
2030 | Błąd sprawdzania statusu pola nadawcy |
2031 | Nie istnieje pole nadawcy o podanej nazwie |
2060 | Błąd dodawania domyślnego pola nadawcy |
2061 | Pole nadawcy musi być aktywne, żeby ustawić je jako domyślne |
2062 | Pole nadawcy już jest ustawione jako domyślne |
2100 | Błąd przesyłanych danych |
2110 | Błąd nazwy pola nadawcy |
2111 | Brak nazwy dodawanego pola nadawcy (parametr &add jest pusty) |
2112 | Niepoprawna nazwa pola nadawcy (np. numer telefonu, zawierająca polskie i/lub specjalne znaki lub za długie), pole nadawcy może mieć maksymalnie 11 znaków, dopuszczalne znaki: a-z A-Z 0-9 - . [spacja] |
2115 | Pole o podanej nazwie już istnieje |
Tabela błędów systemu HLR:
Błąd | Opis |
---|---|
UNKNOWN_SUBSCRIBER | Błędny, nieaktywny numer. Błąd mający charakter stały. |
ABSENT_SUBSCRIBER | Numer wyłączony lub poza zasięgiem przez dłuższy czas. Numer uznany jest jako nieaktywny (podobnie jak w przypadku UNKNOWN) jednak ma charakter tymczasowy, jeżeli numer pojawi się w zasięgu stanie się na nowo aktywny. |
TELESERVICE_NOT_PROVISIONED | Numer ma zablokowaną opcję odbierania wiadomości SMS. Błąd ma charakter stały. |
SYSTEM_FAILURE | Błąd systemu sieci macierzystej podczas sprawdzania numeru, ma charakter tymczasowy. |
HLR_LOCAL_CANCEL / HLR_ABORT | Błąd sytemu HLR dla danego numeru, ma charakter tymczasowy. |
CALL_BARRED | Zablokowane połączenia przychodzące dla danego numeru. Błąd ma charakter stały |
Alfabet 7bit GSM
Tutaj przedstawiony jest podstawowy alfabet '7bit' zgodny ze specyfikacją GSM 03.38.
Wszystkie znaki poza tym spisem, są uznawane za znaki specjalne oraz skracają wiadomość ze 160 znaków na 70. Użycie znaków z tej listy nie skróci wiadomości.
Zauważ, że znaki ^ { } [ ] \ ~ | [enter] € są liczone podwójnie, kiedy wysyłana jest wiadomość bez znaków specjalnych z powodu wymagań specyfikacji GSM.
Znak | Nazwa Znaku | HEX | DEC |
---|---|---|---|
@ | COMMERCIAL AT | 0x00 | 0 |
£ | POUND SIGN | 0x01 | 1 |
$ | DOLLAR SIGN | 0x02 | 2 |
¥ | YEN SIGN | 0x03 | 3 |
è | LATIN SMALL LETTER E WITH GRAVE | 0x04 | 4 |
é | LATIN SMALL LETTER E WITH ACUTE | 0x05 | 5 |
ù | LATIN SMALL LETTER U WITH GRAVE | 0x06 | 6 |
ì | LATIN SMALL LETTER I WITH GRAVE | 0x07 | 7 |
ò | LATIN SMALL LETTER O WITH GRAVE | 0x08 | 8 |
Ç | LATIN CAPITAL LETTER C WITH CEDILLA | 0x09 | 9 |
LINE FEED | 0x0A | 10 | |
Ø | LATIN CAPITAL LETTER O WITH STROKE | 0x0B | 11 |
ø | LATIN SMALL LETTER O WITH STROKE | 0x0C | 12 |
CARRIAGE RETURN | 0x0D | 13 | |
Å | LATIN CAPITAL LETTER A WITH RING ABOVE | 0x0E | 14 |
å | LATIN SMALL LETTER A WITH RING ABOVE | 0x0F | 15 |
Δ | GREEK CAPITAL LETTER DELTA | 0x10 | 16 |
_ | LOW LINE | 0x11 | 17 |
Φ | GREEK CAPITAL LETTER PHI | 0x12 | 18 |
Γ | GREEK CAPITAL LETTER GAMMA | 0x13 | 19 |
Λ | GREEK CAPITAL LETTER LAMBDA | 0x14 | 20 |
Ω | GREEK CAPITAL LETTER OMEGA | 0x15 | 21 |
Π | GREEK CAPITAL LETTER PI | 0x16 | 22 |
Ψ | GREEK CAPITAL LETTER PSI | 0x17 | 23 |
Σ | GREEK CAPITAL LETTER SIGMA | 0x18 | 24 |
Θ | GREEK CAPITAL LETTER THETA | 0x19 | 25 |
Ξ | GREEK CAPITAL LETTER XI | 0x1A | 26 |
ESCAPE TO EXTENSION TABLE | 0x1B | 27 | |
FORM FEED | 0x1B0A | 27 10 | |
^ | CIRCUMFLEX ACCENT | 0x1B14 | 27 20 |
{ | LEFT CURLY BRACKET | 0x1B28 | 27 40 |
} | RIGHT CURLY BRACKET | 0x1B29 | 27 41 |
'\' | REVERSE SOLIDUS (BACKSLASH) | 0x1B2F | 27 47 |
[ | LEFT SQUARE BRACKET | 0x1B3C | 27 60 |
~ | TILDE | 0x1B3D | 27 61 |
] | RIGHT SQUARE BRACKET | 0x1B3E | 27 62 |
VERTICAL BAR | 0x1B40 | 27 64 | |
€ | EURO SIGN | 0x1B65 | 27 101 |
Æ | LATIN CAPITAL LETTER AE | 0x1C | 28 |
æ | LATIN SMALL LETTER AE | 0x1D | 29 |
ß | LATIN SMALL LETTER SHARP S (German) | 0x1E | 30 |
É | LATIN CAPITAL LETTER E WITH ACUTE | 0x1F | 31 |
SPACE | 0x20 | 32 | |
! | EXCLAMATION MARK | 0x21 | 33 |
\" | QUOTATION MARK | 0x22 | 34 |
# | NUMBER SIGN | 0x23 | 35 |
¤ | CURRENCY SIGN | 0x24 | 36 |
% | PERCENT SIGN | 0x25 | 37 |
& | AMPERSAND | 0x26 | 38 |
' | APOSTROPHE | 0x27 | 39 |
( | LEFT PARENTHESIS | 0x28 | 40 |
) | RIGHT PARENTHESIS | 0x29 | 41 |
* | ASTERISK | 0x2A | 42 |
+ | PLUS SIGN | 0x2B | 43 |
, | COMMA | 0x2C | 44 |
- | HYPHEN-MINUS | 0x2D | 45 |
. | FULL STOP | 0x2E | 46 |
/ | SOLIDUS (SLASH) | 0x2F | 47 |
0 | DIGIT ZERO | 0x30 | 48 |
1 | DIGIT ONE | 0x31 | 49 |
2 | DIGIT TWO | 0x32 | 50 |
3 | DIGIT THREE | 0x33 | 51 |
4 | DIGIT FOUR | 0x34 | 52 |
5 | DIGIT FIVE | 0x35 | 53 |
6 | DIGIT SIX | 0x36 | 54 |
7 | DIGIT SEVEN | 0x37 | 55 |
8 | DIGIT EIGHT | 0x38 | 56 |
9 | DIGIT NINE | 0x39 | 57 |
: | COLON | 0x3A | 58 |
; | SEMICOLON | 0x3B | 59 |
< | LESS-THAN SIGN | 0x3C | 60 |
= | EQUALS SIGN | 0x3D | 61 |
> | GREATER-THAN SIGN | 0x3E | 62 |
? | QUESTION MARK | 0x3F | 63 |
¡ | INVERTED EXCLAMATION MARK | 0x40 | 64 |
A | LATIN CAPITAL LETTER A | 0x41 | 65 |
B | LATIN CAPITAL LETTER B | 0x42 | 66 |
C | LATIN CAPITAL LETTER C | 0x43 | 67 |
D | LATIN CAPITAL LETTER D | 0x44 | 68 |
E | LATIN CAPITAL LETTER E | 0x45 | 69 |
F | LATIN CAPITAL LETTER F | 0x46 | 70 |
G | LATIN CAPITAL LETTER G | 0x47 | 71 |
H | LATIN CAPITAL LETTER H | 0x48 | 72 |
I | LATIN CAPITAL LETTER I | 0x49 | 73 |
J | LATIN CAPITAL LETTER J | 0x4A | 74 |
K | LATIN CAPITAL LETTER K | 0x4B | 75 |
L | LATIN CAPITAL LETTER L | 0x4C | 76 |
M | LATIN CAPITAL LETTER M | 0x4D | 77 |
N | LATIN CAPITAL LETTER N | 0x4E | 78 |
O | LATIN CAPITAL LETTER O | 0x4F | 79 |
P | LATIN CAPITAL LETTER P | 0x50 | 80 |
Q | LATIN CAPITAL LETTER Q | 0x51 | 81 |
R | LATIN CAPITAL LETTER R | 0x52 | 82 |
S | LATIN CAPITAL LETTER S | 0x53 | 83 |
T | LATIN CAPITAL LETTER T | 0x54 | 84 |
U | LATIN CAPITAL LETTER U | 0x55 | 85 |
V | LATIN CAPITAL LETTER V | 0x56 | 86 |
W | LATIN CAPITAL LETTER W | 0x57 | 87 |
X | LATIN CAPITAL LETTER X | 0x58 | 88 |
Y | LATIN CAPITAL LETTER Y | 0x59 | 89 |
Z | LATIN CAPITAL LETTER Z | 0x5A | 90 |
Ä | LATIN CAPITAL LETTER A WITH DIAERESIS | 0x5B | 91 |
Ö | LATIN CAPITAL LETTER O WITH DIAERESIS | 0x5C | 92 |
Ñ | LATIN CAPITAL LETTER N WITH TILDE | 0x5D | 93 |
Ü | LATIN CAPITAL LETTER U WITH DIAERESIS | 0x5E | 94 |
§ | SECTION SIGN | 0x5F | 95 |
¿ | INVERTED QUESTION MARK | 0x60 | 96 |
a | LATIN SMALL LETTER A | 0x61 | 97 |
b | LATIN SMALL LETTER B | 0x62 | 98 |
c | LATIN SMALL LETTER C | 0x63 | 99 |
d | LATIN SMALL LETTER D | 0x64 | 100 |
e | LATIN SMALL LETTER E | 0x65 | 101 |
f | LATIN SMALL LETTER F | 0x66 | 102 |
g | LATIN SMALL LETTER G | 0x67 | 103 |
h | LATIN SMALL LETTER H | 0x68 | 104 |
i | LATIN SMALL LETTER I | 0x69 | 105 |
j | LATIN SMALL LETTER J | 0x6A | 106 |
k | LATIN SMALL LETTER K | 0x6B | 107 |
l | LATIN SMALL LETTER L | 0x6C | 108 |
m | LATIN SMALL LETTER M | 0x6D | 109 |
n | LATIN SMALL LETTER N | 0x6E | 110 |
o | LATIN SMALL LETTER O | 0x6F | 111 |
p | LATIN SMALL LETTER P | 0x70 | 112 |
q | LATIN SMALL LETTER Q | 0x71 | 113 |
r | LATIN SMALL LETTER R | 0x72 | 114 |
s | LATIN SMALL LETTER S | 0x73 | 115 |
t | LATIN SMALL LETTER T | 0x74 | 116 |
u | LATIN SMALL LETTER U | 0x75 | 117 |
v | LATIN SMALL LETTER V | 0x76 | 118 |
w | LATIN SMALL LETTER W | 0x77 | 119 |
x | LATIN SMALL LETTER X | 0x78 | 120 |
y | LATIN SMALL LETTER Y | 0x79 | 121 |
z | LATIN SMALL LETTER Z | 0x7A | 122 |
ä | LATIN SMALL LETTER A WITH DIAERESIS | 0x7B | 123 |
ö | LATIN SMALL LETTER O WITH DIAERESIS | 0x7C | 124 |
ñ | LATIN SMALL LETTER N WITH TILDE | 0x7D | 125 |
ü | LATIN SMALL LETTER U WITH DIAERESIS | 0x7E | 126 |
à | LATIN SMALL LETTER A WITH GRAVE | 0x7F | 127 |
Kodowanie
Domyślnie kodowanie znaków ustawione jest na windows-1250. Jednak do wysyłania wiadomości można użyć jednego z poniżej przedstawionych rodzajów kodowania. W tym celu wykorzystać należy parametr &encoding.
- iso-8859-1
- iso-8859-2
- iso-8859-3
- iso-8859-4
- iso-8859-5
- iso-8859-7
- windows-1250
- windows-1251
- utf-8
Integracje
Branża e-commerce coraz częściej i chętniej korzysta z potencjału mobilnej komunikacji, tym bardziej, że przekłada się ona zarówno na wprowadzenie oszczędności, jak i wsparcie sprzedaży.
Z SMSAPI zintegrowanych jest już kilkadziesiąt platform tworzących oprogramowania e-sklepów, CRM oraz wielu innych. Ich pełną listę znajdziesz tutaj.
Gmail
Skrypt monitoruje wiadomości na podstawie etykiet. Aby ustawić automatyczne przypisywanie etykiety od zdefiniowanego odbiorcy, należy zalogować się na pocztę Gmail, następnie kliknąć w ikonę koła zębatego znajdującą się w prawym górnym rogu strony i przejść do ustawień
W ustawieniach należy przejść do zakładki „Filtry”, a następnie wybrać opcję „utwórz nowy filtr”
W następnym kroku należy określić parametry, dla których danej wiadomości zostanie przypisana odpowiednia etykieta. W tym przypadku powiadomienia będą wysyłane na odebrane wiadomości z adresu bok@smsapi.pl Oznacza to, że wszystkie wiadomości od zdefiniowanego odbiorcy będą automatycznie zapisywane z wybraną etykietą.
Aby przejść dalej, należy kliknąć w link „Utwórz filtr na podstawie tych kryteriów wyszukiwania”
Należy zaznaczyć opcję „zastosuj etykietę”, a następnie stworzyć nową, lub wybrać wcześniej utworzoną
Aby dokonać konfiguracji usługi SMSAPI w Google Mail należy upewnić się czy jesteśmy zalogowani na odpowiednim koncie w usłudze Google a następnie przejść pod adres https://script.google.com
W nowo otwartym oknie usuwamy przykład rozpoczętego skryptu oraz wklejamy skrypt dostępny pod adresem http://www.smsapi.pl/integracje/poczta-google
W celu ustawienia częstotliwości wykonywania skryptu należy wybrać (wyzwalacze bieżącego projektu) a następnie dodać nowy wyzwalacz i wybrać częstotliwość wyzwalania
Do poprawnego uruchomienia skryptu wymagane jest nadanie mu uprawnień. Skrypt pobiera informacje o adresach e-mail nadawców wiadomości oraz ich tematach dla zdefiniowanej w ustawieniach poczty Gmail etykiety. Następnie wykonywane są odpowiednio przygotowane odwołania do naszego API które skutkują wysłaniem powiadomienia SMS
Google Calendar
function SmsApiCalendar()
{
/* Configuration */
var SMSAPI_TOKEN = 'token';
var SMSAPI_RECEIVER = '48XXXXXXXXX'; // Numer odbiorcy
var SMSAPI_SENDERNAME = 'Info'; // Pole nadawcy
var SMSAPI_URL = 'https://api.smsapi.pl/sms.do?';
var HOURS = 0;
var MINUTES = 30;
var MESSAGE = 'GOOGLE Calendar: Coming events: :TITLE that begin :TIME';
/****************/
SMSAPI_URL += 'access_token='+SMSAPI_TOKEN;
SMSAPI_URL += '&from='+SMSAPI_SENDERNAME;
SMSAPI_URL += '&to='+encodeURIComponent(SMSAPI_RECEIVER);
var period = (HOURS * 3600000) + (MINUTES * 60000);
var now = new Date();
var periodFromNow = new Date(now.getTime() + period);
var calendar = CalendarApp.getDefaultCalendar();
var events = calendar.getEvents(now, periodFromNow);
for (var i in events) {
var event = events[i];
var has_smsapi_status = false;
var tag_keys = event.getAllTagKeys();
for (var k = 0; k < tag_keys.length; ++k) {
if (tag_keys[k] === 'smsapi_status') {
has_smsapi_status = true;
break;
}
}
if (has_smsapi_status) {
if (event.getTag('smsapi_status') === 'ok') {
continue;
}
}
var idx = event.getId();
var message = MESSAGE.replace(':TITLE', event.getTitle()).replace(':TIME', event.getStartTime());
var url = SMSAPI_URL+"&encoding=utf8&message="+encodeURIComponent(message)+"&check_idx=1&idx="+encodeURIComponent(idx);
UrlFetchApp.fetch(url);
event.setTag('smsapi_status', 'ok');
}
}
* 'SMSAPI_TOKEN', Token smsAPI
* 'SMSAPI_RECIVER', Numer odbiorczy
* 'SMSAPI_SENDERNAME', Pole nadawcy
* 'HOURS', Ustawienie ile godzin przed wydarzeniem ma zostać wysłana wiadomość
* 'MINUTES', Ustawienie ile minut przed wydarzeniem ma zostać wysłana wiadomość
* 'MESSAGE', Treść wiadomości SMS, ':TITLE' tytuł wydarzenia ':TIME' czas wydarzenia.
Integracja pozwala na konfigurację automatycznych powiadomień SMS o nadchodzących wydarzeniach w Kalendarzu Google. W celu rozpoczęcia współpracy należy utworzyć konto w serwisie SMSAPI. Utworzone konto jest gotowe do użytku, jednak zalecamy ustawienie własnego pola nadawcy. Jako domyślne ustawione jest pole nadawcy „Info”. Dodanie pola nadawcy jest usługą całkowicie darmową.
Aby dokonać konfiguracji usługi SMSAPI w Kalendarzu Google należy upewnić się czy jesteśmy zalogowani na odpowiednim koncie w usłudze Google. Następnie przejść na stronę Google Script
Zmień nazwę z 'Code.gs' na 'SmsApiCalendar.gs'.
W nowo otwartym oknie usuwamy przykład rozpoczętego skryptu oraz wklejamy skrypt dostępny po prawej ->
Aby ustawić częstotliwość wykonywania skryptu należy wybrać „Current project's triggers” , następnie „No triggers set up. Click here to add one now” oraz zmienić ustawienia na „Minutes timer” i „Every minute”.
Do poprawnego uruchomienia skryptu wymagane jest nadanie mu uprawnień. Skrypt pobiera informacje o datach oraz nazwach wydarzeń w Kalendarzu Google. Następnie wykonywane są odpowiednio przygotowane odwołania do naszego API które skutkują wysłaniem powiadomienia SMS.
Opencart
Aby dokonać konfiguracji usługi SMSAPI w Opencart w pierwszej kolejności należy pobrać pliki modułu pod adresem SMSAPI-Opencart oraz skopiować je do katalogu, w którym zainstalowany jest Opencart. Po udanym skopiowaniu plików na serwer w panelu administratora Opencart w zakładce Moduły pojawi się możliwość instalacji modułu SMSAPI – Powiadomienia SMS
Po wprowadzenia danych autoryzacyjnych, loginu w SMSAPI i hasła do API zakodowanego w MD5 oraz zatwierdzeniu operacji uzyskujemy dostęp do konfiguracji modułu.
W zakładce „Ustawienia” można wybrać aktywne na koncie w SMSAPI pole nadawcy dla powiadomień SMS, sprecyzować dodatkowe parametry dla wysyłki powiadomień SMS, ustawić możliwość odbierania powiadomień SMS o zarejestrowaniu nowego zamówienia w sklepie, ustawić oraz spersonalizować powiadomienia SMS dla konkretnych statusów zamówień.
W zakładce Wyślij SMS można skorzystać z „Szybkiej bramki” aby wysłać dowolne powiadomienie SMS do odbiorcy zapisanego w bazie sklepu Opencart lub wprowadzonego ręcznie. W zakładce Historia dostępna jest historia wysłanych powiadomień SMS o zmianie statusów zamówień. W zakładce Stan konta dostępna jest informacja o aktualnym stanie konta w SMSAPI.
Moduł SMSAPI wyposażony jest również w tłumaczenie dla polskiej wersji językowej. Przyjęte zostało założenie że polska wersja językowa Opencart zostanie umieszczona w katalogu admin/language/polish .
Shoper
W zakładce „Aplikacje” odnajdujemy „SMSAPI – powiadomienia SMS” oraz wybieramy „Zainstaluj”. Kolejny etap to akceptacja regulaminu sklepu Shoper oraz wybranie akcji „Instaluj”. Po udanej instalacji konfiguracja modułu SMSAPI dostępna jest w zakładce Konfiguracja – Moje aplikacje – SMSAPI
Podajemy login w SMSAPI („Login”), hasło do API w MD5 („Hasło API”) oraz zatwierdzamy wybierając „Zapisz”. Hasło można wygenerować w panelu klienta pod linkiem SMSAPI
„Pokaż hasło do API w MD5”.
Na liście „Pole nadawcy” można dokonać wyboru pola nadawcy wiadomości SMS spośród dostępnych oraz aktywnych w serwisie SMSAPI. Pole nadawcy „ECO”odpowiada usłudze Eco. Pozostałe pola nadawcy dotyczą usługi Pro. W zakładce „Szablony” można dokonać personalizacji wiadomości dla wybranych statusów zamówień w sklepie Shoper. Aby wiadomość SMS została wysłana dla wybranego statusu zamówienia w polu „Wyślij” należy wybrać „Tak” a następnie „Zapisz”. Lista dostępnych zmiennych które można wykorzystać w treści wiadomości SMS dostępna jest na końcu strony konfiguracyjnej modułu.
IAI Shop
Integracja SMSAPI z IAI-SHOP pozwala na wysyłkę powiadomień SMS podczas zmiany statusu zamówienia w sklepie IAI-SHOP oraz powiadomienie właściciela sklepu o nowym zamówieniu. W ramach jednego użytkownika IAI-SHOP można skonfigurować usługę powiadomień SMS dla kilku sklepów.
Konfiguracja integracji dostępna jest pod adresem iaishop.smsapi.pl Aby uruchomić usługę należy wypełnić formularz pod adresem iaishop.smsapi.pl Rejestracja
Podajemy nazwę użytkownika w SMSAPI („SMSAPI UŻYTKOWNIK”), hasło do API („SMSAPI hasło do API w MD5”).Hasło można wygenerować w panelu klienta pod linkiem SMSAPI
Podajemy nazwę sklepu IAI-SHOP („IAI-SHOP nazwa sklepu”), nazwę użytkownika IAI-Shop („IAI-SHOP użytkownik”) oraz hasło użytkownika IAI-Shop („IAI-SHOP hasło”).
Wprowadzone ustawienia należy potwierdzić naciskając „Utwórz konto”.
Pod adresem iaishop.smsapi.pl Logowanie dostępne jest logowanie do nowo utworzonej integracji z IAI-SHOP
W integracji dostępne są 3 zakładki :
„Zarządzaj sklepem”, pozwala na konfigurację treści wysyłanym wiadomości SMS podczas zmiany statusu w sklepie IAI-SHOP oraz konfigurację powiadomień o nowym zamówieniu dla właściciela sklepu.
„Ustawienia SMSAPI”, pozwala na zmianę konta w SMSAPI z którym powiązana jest integracja.
„Stan konta”, pozwala na sprawdzenie ilości dostępnych punktów na platformie SMSAPI.
Szczegółowa konfiguracja integracji IAI-SHOP
W zakładce „Zarządzaj sklepem” można wybrać sklep IAI-SHOP dla którego chcemy przeprowadzić konfigurację.
Na liście „Nadawca wiadomości” można dokonać wyboru pola nadawcy wiadomości SMS spośród dostępnych oraz aktywnych w serwisie SMSAPI. Pole nadawcy „ECO” odpowiada usłudze Eco. Pozostałe pola nadawcy dotyczą usługi Pro
Opcja „Zastąp znaki specjalne” pozwala na automatyczną zmianę wszystkich znaków specjalnych ( w tym polskich diakrytycznych) w treści wysyłanych powiadomień SMS na odpowiedniki np. ą na a.
Opcja „Wyślij fast” pozwala na nadanie wysyłanym wiadomością najwyższego priorytetu zgodnie z wykorzystywanym kanałem PRO/ECO. Opcja wiąże się z podwyższonymi opłatami – 1,5x stawki standardowej wiadomości danego typu.
Opcja „Numer właściciela sklepu” pozwala na konfigurację numeru/ów na które zostaną wysłane powiadomienia SMS o nowym zamówieniu
Opcja przedstawiona poniżej pozwala na aktywacje wysyłki oraz konfigurację treści powiadomienia SMS o nowym zamówieniu.
Opcja przedstawiona poniżej pozwala na aktywacje wysyłki oraz konfigurację treści powiadomień SMS o zmianie statusu zamówienia w sklepie IAI-SHOP.
Tabela dostępnych parametrów w treści powiadomień SMS dla integracji z IAI-SHOP:
Parametr | Opis |
---|---|
{customer} | Imię i nazwisko klienta |
{number} | Numer zamówienia |
{phone} | Numer telefonu klienta |
{status} | Status zamówienia klienta |
{total_price} | Całkowita wartość zamówienia |
QNAP
Aby skonfigurować serwer QNAP do wysyłania powiadomień, należy przejść do zakładki Ustawienia systemowe → Powiadomienia →Serwer SMSC.
W polu Usługodawca SMS należy wybrać opcję Dodaj usługodawcę SMS.
Do pola poniżej należy wpisać swoją nazwę – np. SMSAPI.pl
Do pola Szablon tekstowy URL należy wkleić poniższe wyrażenie:
https://api.smsapi.pl/sms.do?username=@@UserName@@&password=@@Password@@&to=@@PhoneNumber@@&from=SMSAPI&message=@@Text@@
Następnie należy wybrać przycisk Zapisz
W kolejnym kroku należy wybrać z listy wyboru przed chwilą utworzoną konfigurację - SMSAPI.pl
W polu Nazwa użytkownika serwera SMS powinien się znaleźć Państwa login z serwisu SMSAPI
Do pola Hasło użytkownika serwera SMS należy wpisać zakodowane hasło w md5.
W zakładce Ustawienia systemowe → Powiadomienia → Powiadomienia o alertach należy zaznaczyć opcję SMS
W kolejnym kroku należy wybrać kraj oraz numery telefonów (maksymalnie dwa) na jakie mają być wysyłane powiadomienia o błędach.
Pozostałe Integracje
Pozostałe serwisy i usługi, które można zintegrować z SMSAPI znajdziesz tutaj: Integracje.