Biblioteka PHP: SMS API

Jak wysłać SMS z PHP? Poznaj nasze API SMS do wysyłki wiadomości.

W poniższym artykule przybliżam, jak za pomocą funkcji zaimplementowanych w języku PHP, obsługiwać masową wysyłkę SMS w PHP dla stron, aplikacji. Jeśli Twój system, jak wielka część internetu, polega na tym języku, zapraszam!

SMS API PHP Biblioteka

Naszą bibliotekę PHP rozwijamy od 2013. Dzięki połączeniu ze stabilnym i wydajnym API zapewnia ona szerokie możliwości bez konieczności pisania wszystkich szczegółów od zera. Pozwala w bezpieczny i efektywny sposób skorzystać z usług, udostępnionych przez platformę masowych wysyłek SMS. Sam interfejs programistyczny daje jeszcze więcej funkcji, które szczegółowo opisuje Dokumentacja.

API SMSAPI od podstaw – poradnik programisty #01

Pamiętaj, że zawsze możesz też skorzystać z naszego API. W Dokumentacji znajdziesz liczne przykłady wykorzystania poszczególnych możliwości bramki SMS. Przykłady (w Shellu, PHP oraz Pythonie) pokazują, jak praktycznie możesz je zaimplementować. Biblioteka PHP jest zresztą również taką implementacją.

Biblioteki SMS API

Jeżeli chcesz poznać działanie omawianej biblioteki od podszewki, od razu skieruję Cię do repozytorium PHP SMSAPI na GitHubie. Tam odnajdziesz najlepsze źródło informacji o działaniu wszystkich funkcji, czyli sam kod źródłowy. Jeśli zamiast tego wolisz bardziej pragmatyczne podejście lub nie masz czasu i ochoty na dokładne analizowanie poszczególnych plików, czytaj dalej!

Podstawa działania – konto SMSAPI

Przed pierwszą wysyłką SMS z komputera musisz wykonać kilka prostych czynności. Konfiguracja konta SMSAPI nie jest trudna, zamyka się w czterech prostych krokach.

Jak przygotować konto SMSAPI?

Załóż konto SMSAPI – testy są darmowe i zupełnie niezobowiązujące.
Uzupełnij dane firmy w Panelu Klienta – dzięki nim szybciej zweryfikujemy Twoje konto i uruchomimy wszystkie funkcje bramki SMS.
Dodaj pole nadawcy SMS. Będzie to reprezentowana przez Ciebie marka, znak rozpoznawczy dla Twoich odbiorców. Nazwa, która zastąpi numer telefonu może mieć maksymalnie 11 liter, poza tym w Panelu wyszczególnione są inne wymogi co do dozwolonych znaków.
Wygeneruj token OAuth 2. To unikalny, losowy ciąg 40 znaków, którego użyjesz w swoim kodzie. Klient HTTP wysyła go w nagłówku autoryzacyjnym w żądaniu dostępu do chronionego API.

Przetestuj SMSAPI

SMSAPI Zrób to sam – seria poradników wideo

Zrób to sam #01 – Jak utworzyć konto testowe? (poradnik wideo)

Do dzieła: wysyłka PHP SMS

Nie będę tu szczegółowo omawiać wszystkich klas i metod. Zajmę się tylko tymi najważniejszymi, tak aby przedstawić kilka podstawowych metod wysyłki powiadomień SMS. Do dzieła!

Bramka SMS PHP

Wysyłanie SMS to najważniejsza, podstawowa funkcja SMSAPI. Składanie treści wiadomości czy zarządzanie listą kontaktów możesz zaimplementować według własnego pomysłu, ale przy samym wysłaniu SMS API jest niezbędne. Zacznij więc od podstaw: jak to działa w kodzie?

Główna idea to wykorzystanie metod HTTP, które obsługuje klient. Kod PHP umożliwia Ci skorzystanie z gotowego adaptera popularnej biblioteki libcurl. Dzięki temu nie musisz dostarczać własnego klienta HTTP – taka możliwość jednak również istnieje. Prościej jest oczywiście użyć gotowego rozwiązania. Wtedy początek pracy wygląda po prostu tak:

<?php
//client.php
declare(strict_types=1);
use Smsapi\Client\Curl\SmsapiHttpClient;
require_once 'vendor/autoload.php';

$client = new SmsapiHttpClient();

Gdy masz już klienta, potrzebujesz połączenia z serwisem https://api.smsapi.pl. Przedstawia to listing drugiego pliku:

<?php
//service.php
declare(strict_types=1);
use Smsapi\Client\SmsapiClient;
require_once 'vendor/autoload.php';
require_once 'client.php';

$apiToken = '%SMSAPI_ACCESS_TOKEN%';
$service = $client->smsapiPlService($apiToken);

Podstawową konfigurację da się więc skrócić do zaledwie dwóch linijek (nie licząc odwołań do odpowiednich namespace’ów): utworzenie obiektów SmsapiHttpClient i smsapiPlService.

Wysyłanie SMS w PHP

Do nadania powiadomień SMS służy interfejs SmsFeature, zaś jego kluczowe metody to:

sendSms(SendSmsBag $sendSmsBag) – wysyłka wiadomość do pojedynczego adresata;
sendSmss(SendSmssBag $sendSmssBag) – wysyłka SMS do wielu odbiorców.

Obiekty typu „Bag” determinują składniki SMS. Ich właściwości to: odbiorca lub odbiorcy, treść i opcjonalne parametry. Praktyczne użycie wygląda następująco:

<?php
//sendSms.php
declare(strict_types=1);
use Smsapi\Client\Service\SmsapiComService;
use Smsapi\Client\Feature\Sms\Bag\SendSmsBag;
require_once 'service.php';

$smsBag = SendSmsBag::withMessage('48111222333', 'Hello world!');
$service->smsFeature()->sendSms($smsBag);

Statyczna metoda withMessage przyjmuje dwa argumenty stringowe: numer telefonu odbiorcy (wraz z kodem kraju) i treść SMS. Widzisz więc, że podstawowa wysyłka SMS za pomocą biblioteki PHP to tylko cztery elementy.

Wysyłka SMS z PHP:

utworzenie klienta HTTP;
połączenie z usługą SMSAPI;
ustalenie treści SMS i odbiorcy;
wysyłka SMS.

Powiadomienia SMS w PHP – dodatkowe opcje

Metoda sendSms zwraca obiekt Sms, który zawiera kilka przydatnych informacji, między innymi:

$id – identyfikator w systemie SMSAPI;
$points – koszt wysyłki, wyrażony w punktach pobranych z konta SMSAPI;
$dateSent – uniksowy czas wysłania;
$status – status doręczenia, jeden z listy w dokumentacji API.

Komunikacja z Twoimi odbiorcami najprawdopodobniej będzie uwzględniać dostarczanie wielu SMS o podobnej treści. Wysłanie identycznej wiadomości do wielu odbiorców odbywa się za pomocą funkcji sendSmss oraz klasy SendSmssBag.

System SMS dla firm i urzędów: powiadomienia i marketing

Alternatywnie, w zakładce Kontakty możesz utworzyć grupy, aby móc wysyłać masowe kampanie SMS. Przedstawia to poniższy fragment:

$receivers = ['48111222333','48444555666'];
$smssBag = SendSmssBag::withMessage($receivers, 'Hello receivers!');
$service->smsFeature()->sendSmss($smssBag);

$smsToGroupBag = SendSmsToGroupBag::withMessage('group_name', 'Hello group!');
$service->smsFeature()->sendSmsToGroup($smsToGroupBag);

Czas się liczy – planowanie SMS

Kolejna funkcja przyda się przy ustalaniu harmonogramu komunikacji. Podstawowym sposobem zwrócenia uwagi jest po prostu odnalezienie najlepszego momentu na dostarczenie wiadomości.

Czas się liczy! Jak wybrać odpowiedni moment na wysyłkę SMS?

Biblioteka PHP SMS API do wysyłania powiadomień SMS dostarcza kilka funkcji schedule. Dzięki nim nie musisz samodzielnie implementować programu, który o konkretnym czasie zleci nadanie wiadomości przez API – możesz to zaplanować właśnie dzięki API.

Poniższy kod przedstawia tę ideę na trzy już omówione sposoby: pojedyncza wiadomość, wiele SMS naraz oraz wysyłka do grupy:

$sendingDate = new DateTime('2021-06-30');
$scheduleSmsBag = ScheduleSmsBag::withMessage(
	$sendingDate, 
	'48111222333', 
	'Hello scheduled receiver!');
$smsFeature->scheduleSms($scheduleSmsBag);

$scheduleSmssBag = ScheduleSmssBag::withMessage(
	$sendingDate, 
	['48111222333', '48444555666'], 
	'Hello scheduled receivers!');
$smsFeature->scheduleSmss($scheduleSmssBag);

$scheduleSmsToGroupBag = ScheduleSmsToGroupBag::withMessage(
	$sendingDate, 
	'group_name', 
	'Hello scheduled group!');
$smsFeature->scheduleSmsToGroup($scheduleSmsToGroupBag);

Personalizacja SMS w bibliotece PHP – parametry i szablony

Przy masowej wysyłce SMS PHP przydatna będzie personalizacja treści, tak aby każda wiadomość była skierowana do konkretnego odbiorcy. Umożliwiają to dwie statyczne metody, które posiada każdy obiekt typu Bag.

Pierwsza to setParams(array $params). Pozwala na użycie do czterech dowolnych parametrów. Są to dodatkowe właściwości klas typu Bag: $param1, $param2, $param3, $param4. Argument funkcji to tablica z kluczami '1′, '2′, '3′, '4′, której wartości będą zastępowały sekwencje [%1%], [%2%], [%3%], [%4%] z treści wiadomości. Przedstawia to poniższy kod:

$receivers = ['48111222333','48444555666'];
$params = [
	1 => ['Anna', 'Barbara'],
	2 => ['Annopol', 'Bibce'],
];
$smssBag = SendSmssBag::withMessage(
	$receivers, 
	'Hello [%1%] from [%2%]!'
);
$smssBag->setParams($params);
$service->smsFeature()->sendSmss($smssBag);

Druga ze wspomnianych metod to withTemplateName(string $receiver, string $template), dzięki niej możesz wykorzystać szablony stworzone w Panelu. W ten sposób możesz łatwo zmienić treść wiadomości, bez ingerencji w kod PHP. SMS szablon może wyglądać w ten sposób:

PackageSentTemplate: Cześć [%1%], Twoje zamówienie zostało wysłane!
PackageArrivesTodayTemplate: Cześć [%1%], Twoje zamówienie nadejdzie dzisiaj!

Wysłanie SMS wygląda wtedy następująco:

$params = [1 => 'Adam'];
$smsBag = SendSmsBag::withTemplateName(
	'48111222333', 
	'PackageSentTemplate'
);
$smsBag->setParams($params);
$service->smsFeature()->sendSms($smsBag);

$smsBag = SendSmsBag::withTemplateName(
	'48111222333', 
	'PackageArrivesTodayTemplate'
);
$smsBag->setParams($params);
$service->smsFeature()->sendSms($smsBag);

Dalsza personalizacja treści SMS dzięki bazie kontaktów

Biblioteka PHP pozwala zrobić praktyczny użytek z informacji zgromadzonych w bazie danych, aby lepiej trafiać w gusta klientów. Ponownie chodzi tu o wykorzystanie automatycznej personalizacji, tak aby nie musieć wprowadzać danych odbiorców do skryptów PHP. SMSAPI udostępnia funkcję służąca do przeszukiwania bazy. Na przykład, chcesz znaleźć adresata według adresu e-mail, aby wysłać mu przypomnienie o rezerwacji stolika w restauracji. W tym celu używasz szablonu:

TableReservationTemplate: Masz dziś na [%1%] rezerwację w Najlepszej Restauracji na nazwisko [%nazwisko%]. Zapraszamy!

Może to wyglądać w przybliżeniu tak:

use Smsapi\Client\Service\SmsapiComService;
use Smsapi\Client\Feature\Sms\Bag\SendSmsBag;
use Smsapi\Client\Feature\Contacts\Bag\FindContactsBag;
use Smsapi\Client\Feature\Contacts\ContactsFeature;
require_once 'service.php';

$receiverEmail = '1234@example.com';
$reservationTime = '19:00';

$contactFindBag = new FindContactsBag();
$contactFindBag->email = $receiverEmail;
$foundContacts =
	$service->contactsFeature()->findContacts($contactFindBag);

$smsBag = SendSmsBag::withTemplateName(
	$foundContacts[0]->phoneNumber,
	'TableReservationTemplate'
);
$smsBag->setParams([1=>$reservationTime]);
$service->smsFeature()->sendSms($smsBag);

Dzięki zadanemu e-mailowi łatwo możesz odnaleźć odpowiadający mu numer telefonu, a następnie sparametryzować treść wiadomości i wysłać ją. Pole [%nazwisko%] zostanie zamienione na wprowadzone uprzednio do Twojej bazy nazwisko odbiorcy. Po pełne informacje w temacie personalizacji SMS sięgnij do Dokumentacji.

No dobra, a co dalej?

Cały kod naszej biblioteki PHP jest na GitHubie. Jeżeli rozważasz wykorzystanie innych języków, to znajdziesz tam również źródła w Javie, C#, Pythonie, bashu i JavaScripcie.

Ten artykuł naturalnie nie opisuje wszystkich możliwości skryptów PHP, które korzystają z SMSAPI. Możesz łatwo odnaleźć je samodzielnie w kodzie – zajrzyj do katalogu Feature. Są tam funkcje pozwalające m.in. na:

wysyłkę MMS, aby komunikacja z Twoimi klientami była bardziej atrakcyjna;
uwierzytelnianie wieloskładniowe (MFA), aby zwiększyć bezpieczeństwo logowania;
zarządzanie bazą kontaktów – dodawanie, edycję i usuwanie odbiorców i ich grup;
skracanie linków za pomocą adresu idz.do;
sprawdzenie stanu konta, czyli pozostałych do wykorzystania punktów.

Jeśli potrzebujesz przykładów użycia poszczególnych interfejsów i metod, znajdziesz je w katalogu testów. Powodzenia!