Zagadnienia: API, Biblioteka, IT

Biblioteka PHP: SMS API

12 lipca, 2021
Przeczytasz w 8 min. 19 sek.
Biblioteka PHP SMS API

W poniższym artykule przybliżam, jak za pomocą funkcjonalności, zaimplementowanych w języku PHP, obsługiwać masową wysyłkę SMS w PHP. 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 funkcjonalności, które szczegółowo opisuje Dokumentacja.

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ą.

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 funkcjonalności, 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:

  1. Załóż konto SMSAPI.
  2. Wprowadź swoje dane. W Panelu Klienta w zakładce Płatności uzupełnij dane firmy, na którą wystawimy fakturę.
  3. 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.
  4. 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.

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

Do dzieła: wysyłka PHP SMS

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

Bramka SMS PHP

Wysyłanie SMS to najważniejsza, podstawowa funkcjonalność 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 = '0000000000000000000000000000000000000000';
$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:

  1. Utworzenie klienta HTTP;
  2. Połączenie z usługą SMSAPI;
  3. Ustalenie treści SMS i odbiorcy;
  4. 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.

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 funkcjonalność przyda się przy ustalaniu harmonogramu komunikacji. Podstawowym sposobem zwrócenia uwagi jest po prostu odnalezienie najlepszego momentu na dostarczenie wiadomości.

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 funkcjonalności, 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!

Photo by Craig Stevenson on Unsplash