Table of Contents
Zaczynasz pracę z API SMSAPI? Przeczytaj pierwszą część poradnika programisty i przejdź przez pięć kroków do pierwszej wysyłki SMS po API.
Nazwa SMSAPI, ma już długą, ponad 13-letnią historię. Została zaproponowana przez założycieli firmy, którzy sami byli programistami i chcieli podkreślić, że platforma, którą budują, jest skierowana szczególnie dla programistów.
Teraz, obok niezwykle wydajnego, stabilnego i dającego duże możliwości API, nasza marka i charakterystyczny, niebieski kolor kojarzy się z Panelem Klienta, który codziennie jest aktywnie wykorzystywany przez osoby niezaznajomione z programowaniem. Wiele z nich zapewne nawet nie wie, czym jest drugi człon w nazwie SMSAPI – chcą po prostu wysłać masowe SMS!
A jednak nasze API jest cały czas utrzymywane, modyfikowane i rozszerzane. Stanowi fundament naszych wewnętrznych produktów, takich jak BaseBooster, aplikacja mobilna czy Newsletter SMS. Jest także aktywnie wykorzystywane przez naszych klientów, czego dowodzą wywiady z iQueue, Insly czy ProTrainUp. Chcemy ułatwiać kolejnym firmom, które potrzebują efektywnego, szybkiego i niezawodnego środka komunikacji rozpoczęcie pracy z API.
Zdaję sobie sprawę, że po decyzji „Wybieramy SMSAPI i skorzystamy z ich API do komunikacji SMS”, która potencjalnie została podjęta na innym szczeblu (jeśli firma ma rozbudowaną strukturę zarządzania), lub bardziej spontanicznie („oooo, to API wygląda dobrze i ma przyjemną dokumentację!”) w końcu to programista (a może nawet cały zespół?) będzie musiał usiąść do komputera, odpalić swoje IDE (albo Emacsa przez Sendmail), zrobić sobie kawę i rozgryzać wszystko od początku.
Dla takich właśnie osób rozpoczynamy cykl artykułów, które opiszą pierwsze kroki, które trzeba przejść, aby zacząć pracę z naszym API. Zacznę od opisania, jakie kroki musimy przejść i jakie decyzje podjąć, żeby wysłać pierwszego, testowego SMS-a przez API.
Krok 1: Załóż i zweryfikuj konto na platformie SMSAPI
To jest pierwszy i absolutnie najważniejszy krok do rozpoczęcia pracy – konto SMSAPI. Jak je założyć przedstawi Ci nasz screencast.
Rejestracja i weryfikacja konta SMSAPI
Oczywiście, jeśli ktoś już wcześniej założył i zweryfikował konto, na którym powinieneś pracować, wykorzystaj je albo rozważ stworzenie subkonta na potrzeby deweloperskie.
Świeże konto po rejestracji i weryfikacji powinno mieć kilka testowych punktów, które możesz wykorzystać, żeby wysłać kilka pierwszych wiadomości.
Krok 2: Dodaj pole nadawcy
Pole nadawcy to tekst, który będzie się wyświetlał jako nadawca na telefonie, który otrzyma SMS-a. Wygląda to tak, jak na przykładzie po prawej.
Pole nadawcy może mieć maksymalnie 11 znaków i warto, żeby odzwierciedlał markę, która w przyszłości będzie komunikować się z Twoim odbiorcą.
Domyślnym polem nadawcy dla nowego konta w SMSAPI jest „Test” i do testowania jest zupełnie wystarczające. Jeśli jednak zdecydujesz się pracować od razu mając docelową nazwę marki, musisz przejść procedurę rejestracji i aktywacji pola nadawcy, pokazaną w wideo ponizej, którą możesz wykonać w Panelu Klienta.
Jak dodać pole nadawcy SMS w Panelu Klienta SMSAPI?
Krok 3: Zdecyduj, czy będziesz korzystał z biblioteki czy API?
To pierwszy wybór, który musisz świadomie podjąć. Z jednej strony SMSAPI przygotowało dla Ciebie Biblioteki SMS API w kilku popularnych językach programistycznych, które można pobrać z GitHub.
Z drugiej strony jest API, które można wykorzystać bezpośrednio, bez użycia biblioteki. Zostało ono dokładnie opisane oraz okraszone przykładami w naszej Dokumentacji oraz w formie specyfikacji OpenAPI wykorzystując popularne narzędzie Swagger.
To, z którego narzędzia skorzystasz będzie zależało tylko od Twoich preferencji i od tego, co chcesz osiągnąć. Wszystkie biblioteki pozwolą Ci na wysyłkę wiadomości, niektóre na operacje na bazie kontaktów. Natomiast mogą one nie być pomocne podczas obsługi odbioru wiadomości SMS przy pomocy wirtualnego numeru odbiorczego, którym zajmiemy się w jednym z późniejszych artykułów.
Na potrzeby prostych integracji, opartych tylko o wysyłkę SMS-ów, rekomendujemy wykorzystanie jednej z naszych gotowych bibliotek, oczywiście pod warunkiem, że programujesz w języku, w którym ta biblioteka jest dostępna. Ułatwi i przyspieszy Ci to rozpoczęcie pracy.
Z drugiej strony, jeśli planujesz bardziej skomplikowane działania, których biblioteka w Twoim języku programowania nie wspiera, albo nie jesteś zwolennikiem Fluent API (na przykładzie biblioteki w JS) i wolałbyś mieć większą kontrolę nad dokładnym sposobem działania integracji, skorzystanie bezpośrednio z API jest równie dobrym wyborem.
Krok 4: Wygenerowanie klucza autoryzacyjnego
To jedna z czynności, które wymagają zalogowania do Panelu Klienta. Przejdź w miejsce, pokazane na obrazku poniżej.
Następnie kliknij przycisk „Generuj token”. Zostanie otwarte okienko, w którym będziesz mógł ustawić kilka opcji. Na testy (zgodnie z zasadą minimalizacji dostępu do danych) wystarczy nam sama możliwość wysyłki SMS przez API, dlatego odznaczymy resztę pól.
Po kliknięciu „Generuj token” pojawi się nowe okienko, w którym token zostanie wyświetlony.
Uwaga!
Krok 5: Testowe odwołanie do API
Pozostaje Ci teraz wysyłka Twojego pierwszego SMS-a przez API SMSAPI! W tym celu wykorzystaj poniższy kod, w którego zrozumieniu może pomóc Ci nasza Dokumentacja:
<?php
/** adres URL API SMSAPI, @see https://www.smsapi.pl/docs/#adresy-url */
$smsApiUrl = 'https://api.smsapi.pl';
/** token autoryzacyjny OAuth, @see https://ssl.smsapi.pl/react/oauth/manage */
$smsApiToken = 'token_oauth';
/** pole nadawcy, @see https://ssl.smsapi.pl/sms_settings/sendernames */
$from = 'test';
/** lista odbiorców, każdy kolejny oddzielony przecinkiem */
$to = 'XXXXXXXXX';
/** treść wiadomości */
$message = 'Hello world!';
/** format odpowiedzi */
$format = 'json';
$httpClient = curl_init();
curl_setopt($httpClient, CURLOPT_URL, $smsApiUrl . '/sms.do');
curl_setopt($httpClient, CURLOPT_POST, true);
curl_setopt($httpClient, CURLOPT_POSTFIELDS, [
'to' => $to,
'from' => $from,
'message' => $message,
'format' => $format,
]);
curl_setopt($httpClient, CURLOPT_RETURNTRANSFER, true);
curl_setopt($httpClient, CURLOPT_HTTPHEADER, [
'Authorization: Bearer ' . $smsApiToken
]);
$apiResponse = curl_exec($httpClient);
curl_close($httpClient);
echo $apiResponse . PHP_EOL;
?>To kod, który spowoduje wysłanie pierwszej wiadomości o zadanej treści pod określony numer. Oczywiście zachęcam do zamiany przykładowego numeru na swój w zmiennej $to, żeby być w stanie odebrać tę pierwszą wiadomość. 😉 Konieczne jest również wpisanie swojego tokena OAuth do zmiennej $smsApiToken .
Pozostaje nam uruchomienie tego kodu za pomocą interpretera PHP. Możemy to zrobić zapisując powyższy kod jako plik testowaWysylka.php i na systemie z zainstalowanym interpreterem PHP (wszystkie wersje >= 5.4 powinny sobie ze skryptem poradzić) uruchamiając go poleceniem
php testowaWysylka.phpJeśli wszystkie dotychczasowe kroki wykonaliśmy poprawnie, powinniśmy dostać komunikat sukcesu w formacie JSON, który będzie podobny do tego:
{"count":1,"list":[{"id":"566275XXXXX","points":0.14,"number":"48XXXXXXXXX","date_sent":1603356627,"submitted_number":"XXXXXXXXX","status":"QUEUE","error":null,"idx":null,"parts":1}]}A po chwili, na podany telefon powinna przyjść wiadomość SMS!
Najczęstsze błędy
Co, jeśli nasz test nie został zakończony sukcesem? Wtedy API poda nam numer błędu, który może naprowadzić nas na miejsce, w którym występuje problem. Błędy, na które możesz natrafić, są opisane w Dokumentacji. Najczęstszymi są:
- błąd 101, Invalid authorization info – podano nieprawidłowy token albo połączenie do nieprawidłowego serwisu np. do api.smsapi.com zamiast api.smsapi.pl,
- błąd 14, Wrong sender name – użycie złego pola nadawcy, niedodanego wcześniej w Panelu Klienta lub nieaktywnego/odrzuconego,
- bład 11, The message is too long or there is no message or parameter: nounicode is set and special characters (including Polish characters) are used – próba wysyłki zbyt długiej wiadomość w stosunku do konfiguracji i limitu na koncie – pamiętaj, że wysyłka wiadomości ze znakami spoza Unicode skraca liczbę znaków dostępnych w SMS-ie, a dokładny opis znajdziesz (jak zwykle) w Dokumentacji,
- błąd 13, Lack of valid phone numbers (invalid or blacklisted numbers) – wysyłka pod nieprawidłowe albo zablokowane numery telefonów. Należy sprawdzić, czy na pewno wpisywany numer jest prawidłowy i czy nie ma zbędnych lub dodatkowych znaków,
- błąd 103, Insufficient credits on your account – brak wystarczającej liczby punktów na koncie lub subkoncie.
Jest też kilka częstych błędów, na które nie naprowadzi nas komunikat błędu SMSAPI (ani nie odłożą się w logach), ponieważ wystąpiły przed poprawnym połączeniem się z API SMSAPI. Najczęściej to:
- połączenie do błędnego adresu – poprawne adresy API znajdziesz w Dokumentacji, ale prawdopodobnie chcesz użyć https://api.smsapi.pl/,
- połączenie z wykorzystaniem protokołu TLS w wersji niższej niż 1.2 – nie wspieramy już starych wersji protokołu TLS, który jest obecnie uważany za niedostatecznie zabezpieczający przed atakami, więc musisz sprawdzić wersję TLS, z której korzysta Twój system (środowisko) i prawdopodobnie zaktualizować całe swoje środowisko lub jego część,
- połączenie zablokowane przez firewall po stronie klienta – to znaczy, że na drodze z Twojej maszyny do API SMSAPI połączenie jest blokowane. Musisz sprawdzić Twój system, albo porozmawiać z administratorem sieci. Problem rzadko występuje na komputerach programistów (prawdopodobnie nie byłbyś w stanie przeczytać tego artykułu!), ale w sieciach wyizolowanych do użycia w serwerowni dbającej o bezpieczeństwo firmy, taki scenariusz jest możliwy. Być może będzie wtedy możliwość odblokowania ruchu pod adresy IP serwerów SMSAPI.
Co dalej? Nasze API SMSAPI ma dużo więcej możliwości. Pozwala zarządzać kontaktami, które można przechowywać na koncie SMSAPI, dodawać parametry do treści SMS-a czy modyfikować ustawienia swojego konta. Oprócz tego, mechanizm callbacków pozwoli Ci obsłużyć SMS-y, które ktoś wysłał pod numer odbiorczy, który przypiąłeś do swojego konta! Więcej o tym w kolejnych odcinkach cyklu!
Photo by Timothy Dykes on Unsplash
