Table of Contents
Poznaj bibliotekę Javascript. Wysyłanie SMS z JS jest prostsze niż Ci się wydaje. W tym poradniku programisty znajdziesz zarówno gotowe fragmenty kodu wraz z omówieniem, jak i wyjaśnienie błędów, na które możesz natrafić.
Poprzednio zająłem się biblioteką SMS API napisaną w języku PHP. Czas na kontynuację! Poznaj implementację w kolejnym języku. Tym razem biorę na warsztat Bibliotekę JavaScript. Do dzieła! Na początku – sprostowanie. W styczniu 2021 wypuściliśmy wersję 2.0.0 Biblioteki Javascript.
Co się zmieniło? Całkiem sporo, ponieważ wprowadza wsparcie dla języka TypeScript. Jest to stworzona przez Microsoft mniej znana „nadbudówka” dla JavaScriptu (fachowo: jest jego nadzbiorem). Oznacza to, że każdy kod JavaScript jest poprawny również w TypeScripcie. Podstawowa różnica polega na dodaniu statycznego typowania do całkowicie dynamicznego JS. Poza tym TypeScript jako pierwszy zaczął wspierać bardzo ważny mechanizm async/await. Ale po kolei.
Zanim zaczniesz pisać program do wysyłki SMS…
Potrzebujesz kilku kroków przygotowań. Chodzi o założenie i skonfigurowanie konta w naszym serwisie. Da Ci to dostęp do Panelu, w którym możesz zarządzać:
- masową wysyłką SMS;
- danymi do faktury;
- płatnościami za kampanie SMS;
- nazwami nadawcy wiadomości (branding SMS);
- listą kontaktów;
- grupami odbiorców;
- tokenami OAuth 2 dla połączenia z API.
Sam panel, jak widać, daje spore możliwości. Proces stworzenia nowego konta był już opisany w artykule o bibliotece SMS API w PHP. Inne teksty i poradniki wideo na naszym blogu pokazują poszczególne funkcje panelu – zajrzyj do zakładki SMSAPI od podstaw. Skupmy się teraz na bardziej programistycznym podejściu.
Cały kod naszej biblioteki jest podzielony na moduły, które odpowiadają za poszczególne funkcje. Całość znajdziesz na GitHub SMSAPI. Analiza poszczególnych plików to oczywiście najpewniejszy sposób na nauczenie się jej obsługi. Jednak jeśli wolisz szybciej i nieco przyjemniej zapoznać się z jej wykorzystaniem w praktyce – zapraszam do lektury!
Wysyłka wiadomości przez SMS API JavaScript
Podwaliną automatycznej obsługi SMS są metody HTTP. Trzon aplikacji do komunikacji z SMS API stanowi klient HTTP, który formułuje te zapytania do serwera. Przykładem takiego rozwiązania jest popularny Axios, napisany w JavaScripcie. Właśnie z niego korzysta nasza Biblioteka. Dzięki temu nie musisz dostarczać własnego klienta.
Przygotowanie do pracy z SMS API
Na początku pracy z kodem będziesz musiał dokonać inicjalizacji funkcji biblioteki. Nic prostszego!. Jedynym potrzebnym tu parametrem jest token autoryzacyjny, wygenerowany w panelu Klienta.
Kod inicjalizacji może zaś wyglądać na przykład tak:
import {SMSAPI} from 'smsapi';
const apiToken = '%SMSAPI_ACCESS_TOKEN%';
const smsapi = new SMSAPI(apiToken);I to wszystko! Za konfigurację klienta całkowicie odpowiada Axios.
Javascript: wysyłanie SMS pojedynczego
A jak najprościej wysłać wiadomość? Za pomocą modułu o dość oczywistej nazwie sms. Może to wyglądać tak:
import {SMSAPI, MessageResponse} from 'smsapi'; // MessageResponse nie jest wykorzystany
const smsapi = new SMSAPI('[token]');
const receiver = '+48111222333';
const message = 'Hello world!';
smsapi.sms.sendSms(receiver, message);Metoda sendSms jest asynchroniczna, zatem zwraca znany z JavaScriptu obiekt Promise. Opakowuje on z kolei obiekt MessageResponse. Trzeba poczekać na odpowiedź, żeby jakoś skorzystać ze zwróconych danych. Z pomocą przychodzi tu więc mechanizm async/await. Poniższa funkcja po zakończonym wysyłaniu wyświetli komunikat ze statusem:
async function SendAndDisplayStatus(receiver, message) {
const response = await smsapi.sms.sendSms(receiver, message);
const response: MessageResponse = await smsapi.sms.sendSms(receiver, message); // Albo tak jeśli wykorzystujemy MessageResponse
alert(response.list[0].status);
}Poszczególne elementy zwracanego obiektu response są analogiczne do odpowiedzi w formacie JSON, którą opisuje Dokumentacja API. Możliwe jest wysyłanie SMS do wielu odbiorców naraz, stąd element o nazwie list. Jego pola to m.in.:
status– jeden ze statusów doręczenia wiadomości;id– unikalny identyfikator w systemie SMSAPI;points– koszt wysyłki, czyli liczba punktów pobranych z konta SMSAPI;number– numer odbiorcy;dateSent– data wysyłki.
Widzisz więc, że minimalna obsługa SMS w JavaScript dzięki bibliotece SMS API zajmuje zaledwie dwie linijki kodu: utworzenie głównego obiektu SMSAPI i zlecenie wysyłki klientowi HTTP:
const smsapi = new SMSAPI('%SMSAPI_ACCESS_TOKEN%');
smsapi.sms.sendSms('+48111222333', 'Hello world!');Wysyłka do wielu odbiorców – metody JavaScript
Przejdźmy dalej. Skoro planujesz programowo zautomatyzować wysyłanie SMS do klientów firmy, to pewnie potrzebujesz nieco więcej możliwości. Dostarczanie identycznych wiadomości do wielu odbiorców jednocześnie? Nic prostszego! Wystarczy tylko, że do tej samej funkcji zamiast numeru odbiorcy podasz ich listę.
async function SendMultipleAndDisplayStatuses(receivers, message) {
const response = await smsapi.sms.sendSms(receivers, message);
for (const respList of response.list) {
alert(respList.status);
}
}
SendMultipleAndDisplayStatuses(
['+48111222333', '+48444555666'],
'Hello receivers!'
);W Panelu Klienta łatwo zauważysz możliwość łączenia odbiorców w grupy. Nasza biblioteka w JavaScripcie umożliwia skorzystanie z nich. Gdy cała grupa ma dostać tę samą wiadomość, wystarczy użyć:
async function SendToGroupAndDisplayStatuses(group, message) {
const response = await smsapi.sms.sendSmsToGroup(group, message);
for (const respList of response.list) {
alert(respList.status);
}
}
SendToGroupAndDisplayStatuses('group_name', 'Hello group!');Jeśli argument group będzie listą, wszystko również wykona się poprawnie. Program po prostu spróbuje wysłać SMS do wszystkich odbiorców z kilku grup.
Dodatkowe opcje SMS-ów: personalizacja i planowanie
Przekaz jest lepiej odbierany, jeśli człowiek czuje się potraktowany indywidualnie. Tak drobna rzecz, jak zwrot po imieniu może być pierwszym krokiem w udanym marketingu SMS.
Personalizacja poszczególnych wiadomości oznacza nadanie poszczególnym wiadomościom bardziej osobistego charakteru. Nie musisz przy tym ręcznie pisać każdego tekstu z osobna. W odpowiedniej sekcji Twojego panelu klienta SMS API możesz tworzyć szablony wiadomości. Na przykład taki:
PackageSentTemplate: „Cześć [%imie%], Twoje zamówienie zostało wysłane!” Element [%imie%] zostanie zamieniony na odpowiednią treść, jeśli masz utworzoną bazę odbiorców. W ten prosty sposób adresat automatycznie dostanie wiadomość skierowaną bezpośrednio do niego. Dostępnych rodzajów pól jest naturalnie więcej – opisaliśmy je w Dokumentacji. W kodzie można skorzystać z szablonu na przykład tak:
async function NotifyPackageSent(receiver) {
const details = {
template: 'PackageSentTemplate'
};
await smsapi.sms.sendSms(receiver, "", details);
}Jak widzisz, pominąłem treść wiadomości, ponieważ jest zawarta w szablonie. Zmienna details jest typu SmsDetails. Zawiera ona szereg dodatkowych danych, które mogą być dołączone do wysyłanych wiadomości. Na przykład: kodowanie znaków, data wysłania, maksymalna liczba części wiadomości, użyty szablon i własne parametry. Dokładniejsze opisy znajdziesz w Dokumentacji, w rozdziale o pojedynczej wysyłce.
Przejdźmy dalej. Pole date z obiektu SmsDetails pozwala zaplanować wysyłkę na przyszłość. Jest to standardowy, JavaScriptowy obiekt typu Date, więc można wykorzystać go na przykład tak:
async function ScheduleSms(receiver, message, futureDate) {
const details = {
date: futureDate
};
await smsapi.sms.sendSms(receiver, message, details);
}Ta niepozorna funkcja pozwoli Ci planować kampanie SMS! Na wszelki wypadek w module sms znajdziesz funkcję, za pomocą której możesz anulować zaplanowane wysłanie SMS-a. Oto jej sygnatura:
async removeScheduledSms(smsId: string | string[]):
Promise<ScheduledSmsResponse>Przyjmowany parametr to unikalny identyfikator wiadomości, który poznajesz w momencie wysyłki. Zwracają go metody sendSms i sendSmsToGroup – patrz wyżej.
Pole nadawcy SMS
Jest to krótki tekst wyświetlany zamiast numeru telefonu nadawcy. Dzięki niemu odbiorca może natychmiast skojarzyć, kto do niego pisze. Może to być na przykład nazwa Twojej marki. W marketingu SMS to pierwsza okazja, żeby zrobić na kliencie dobre wrażenie.
Ze względów bezpieczeństwa, pracownik SMSAPI ręcznie zatwierdza każdą nową nazwę nadawcy w godzinach pracy naszego biura. Możesz ustawiać je w Panelu Klienta, a spośród nich wybrać jedną domyślną.
Od strony kodu obsługuje je moduł sendernames. Zawiera on kilka przydatnych metod do znajdowania, tworzenia i usuwania pól nadawcy. Poniższa funkcja dla przykładu pokazuje, jak możesz jawnie upewnić się, że SMS zostanie wysłany z domyślnym polem nadawcy.
async function sendSmsWithDefaultSenderName(receiver, message) {
const senderNamesList = await smsapi.sendernames.get();
for (let elem of senderNamesList.collection) {
if (elem.isDefault) {
await smsapi.sms.sendSms(receiver, message, {from: elem.sender});
break;
}
}
}Błędy wysłania SMS
Aby zabezpieczyć Twój program przed nieprzyjemnymi niespodziankami, powinieneś zawrzeć w nim obsługę błędów. Wspomniany wyżej Axios (klient HTTP) w razie niepowodzenia wysłania wiadomości zwróci kod i wiadomość błędu. Kod biblioteki SMS API w takiej sytuacji rzuci wyjątkiem z obiektem błędu typu MessageError, który zawiera te dwie wartości.
Szczegółowe opisy kodów błędów znajdziesz w Dokumentacji. Oto niektóre, najczęściej spotykane:
- 11 – zbyt długa wiadomość lub pojawiły się znaki specjalne przy jednoczesnym użyciu parametru nounicode;
- 12 – przekroczony limit części wiadomości;
- 13 – brak poprawnych numerów odbiorców;
- 14 – niepoprawne pole nadawcy;
- 26 – za długi temat wiadomości;
- 101 – złe dane autoryzacji (błędny token);
- 103 – brakuje punktów na koncie, aby wysłać wiadomość.
Inne moduły SMS API dla JavaScriptu
Jak już na początku wspomniałem, kod biblioteki podzielony jest na moduły. Powyżej zapoznaliśmy się z sms i sendernames – najważniejszymi do wysyłki SMS. Niektóre z pozostałych modułów to:
- templates – służy do obsługi szablonów wiadomości.
- contacts – do tworzenia i edytowania kontaktów. Zawiera pomniejsze moduły do zarządzania grupami kontaktów oraz własnymi, polami poszczególnych kontaktów.
- mms – przy jego pomocy wyślesz MMS w formacie SMIL.
- profile – pozwala sprawdzić dane Twojego konta w SMSAPI, takie jak liczba dostępnych punktów, dane użytkownika, typ płatności.
Brak w tym artykule miejsca, żeby się rozwlekać nad wszystkimi aspektami biblioteki Javascript do wysyłki SMS. Na koniec odsyłam Cię, więc do repozytorium na GitHubie, a konkretniej: plików testów jednostkowych. Znajdziesz je w poszczególnych podfolderach, zawsze pod nazwą index.spec.ts. Testy są jednocześnie przykładami zastosowania poszczególnych metod – to najprostszy sposób na naukę. Powodzenia!
