Biblioteka C# SMS API poradnik dewelopera

Table of Contents

Od podstaw: jak wysłać SMS z C#? Poznaj naszą bibliotekę SMS API. W artykule znajdziesz przykłady kodu, praktyczne rady, rozwiązania najczęstszych problemów i więcej.

Czas na wprowadzenie do kolejnej biblioteki do masowej wysyłki SMS! Poza poprzednio omawianymi językami webowymi (PHP i JavaScript), SMSAPI oferuje Ci też implementację w języku C#. Jeśli to trafia w Twój programistyczny gust – czytaj dalej!

Biblioteki SMS API

Cały kod źródłowy jest upubliczniony na GitHubie SMSAPI. Znajdziesz w nim dwa katalogi:

  • smsapi – zawiera kod produkcyjny, z którego możesz korzystać w swojej aplikacji. Z jego wybranymi metodami zapoznasz się poniżej.
  • smsapiTests – zawiera testy jednostkowe, korzystające z frameworka MSTest. Możesz w nim znaleźć przykłady zastosowań poszczególnych metod. 

Cała omawiana biblioteka jest implementacją API, które opisuje Dokumentacja SMSAPI. Jeśli do niej zajrzysz, zapewne znajdziesz sporo analogii do obiektów i metod w C#. Możesz, oczywiście, napisać Twoją aplikację od zera w dowolnym języku, odwołując się bezpośrednio do API. Liczne tego przykłady ilustrują samą Dokumentację. Prościej jednak jest skorzystać z już gotowego rozwiązania. Zaczynamy!

Na początek – konto w serwisie SMSAPI

Identycznie jak w każdym przypadku korzystania z usług API do obsługi SMS-ów, najpierw zarejestruj się do Panelu Klienta i skonfiguruj konto. Potrzebne będą następujące informacje:

  • Twój e-mail, hasło, numer telefonu, imię i nazwisko;
  • dane Twojej firmy – do faktury;
  • pole nadawcy SMS – nieobowiązkowe, acz przydatne;
  • dodatkowo: adres mailowy do wysyłania faktur i numer kontaktowy do Twojej księgowości.

Po zweryfikowaniu konto zostanie aktywowane. Dzięki Panelowi Klienta możesz je doładowywać i zacząć korzystać z wysyłki SMS! Po więcej szczegółów sięgnij do serii SMSAPI Zrób to sam. Tutaj skupimy się na programowym podejściu.

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

Początek obsługi kampanii SMS: konfiguracja 

Za kulisami omawianej Biblioteki działa działa biblioteka RestSharp, czyli klient obsługujący obsługę odwołań HTTP. Używa ona metod HTTP (GET, POST, PUT, DELETE) do całej komunikacji z serwerem i obsługi kampanii SMS. Na szczęście nie musisz wgłębiać się w szczegóły, lecz tylko skorzystać z gotowego rozwiązania. Jak rozpocząć?

Podobnie, jak w większości projektów: od inicjalizacji. Połączenie powinno zostać autoryzowane za pomocą tokena API. Jest to 40-znakowy ciąg, który możesz wygenerować w zakładce Tokeny API (OAuth), a potem wykorzystać w Visual Studio:

SMSApi.Api.IClient client = new SMSApi.Api.ClientOAuth("token");

Obiekty client przechowują dane wykorzystywane później w autoryzacji.

Wysyłka SMS dzięki metodom C#

Po utworzeniu klienta dalsze działanie biblioteki opiera się na fabrykach i akcjach, co przedstawia poniższy przykład. Następuje tu wysłanie testowej wiadomości do jednego odbiorcy:

var smsFactory = new SMSApi.Api.SMSFactory(client);
SMSFactory.ActionSend("48111222333", "Hello world!").Execute();

Tak więc w trzech linijkach da się zamknąć trzy podstawowe etapy prostej obsługi SMS-ów: utworzenie klienta, utworzenie fabryki i zastosowanie odpowiedniej akcji. Połączenie z serwerem jest obsługiwane wewnątrz obiektu klasy Factory, która jest bazą dla licznych fabryk – w tym SMSFactory. Odpowiadają one za poszczególne funkcje biblioteki.

Zaś metody z klas typu Action pozwalają ustawiać poszczególne parametry wykonywanych akcji. Wywołania metod można łączyć łańcuchowo, rozpoczynając od fabryki, a kończąc na wykonaniu (metoda Execute() z bazowej klasy wszystkich akcji). Dla przykładu poniższy kod działa identycznie do poprzedniego: 

var smsFactory = new SMSApi.Api.SMSFactory(client);
var response = SMSFactory.ActionSend()
	.SetTo("48111222333")
	.SetText("Hello world!")
	.Execute();

Odpowiedzi na różne zapytania do API obsługują klasy z przestrzeni nazw Response. W przypadku zlecania wysyłki SMS używany jest Response.Status (typ obiektu response z przykładu powyżej). Ma on kilka przydatnych właściwości. Count to liczba wysłanych wiadomości. List to lista z odpowiadającymi im zmiennymi, m.in.: 

  • ID – unikalny identyfikator w systemie SMSAPI.
  • Points – koszt wyrażony w liczbie punktów, pobranych z Twojego konta.
  • Number – numer odbiorcy.
  • Status – stan doręczenia (patrz lista statusów w Dokumentacji).

Inne właściwości: Message, Length oraz Parts dotyczą treści, długości i liczby części wysyłanego tekstu.

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

Masowa wysyłka SMS w kodzie C#

Przy prowadzeniu kampanii SMS najbardziej podstawowa funkcja to wysyłka wiadomości do wielu odbiorców naraz. Pisanie osobnej wiadomości do każdego z Twoich klientów byłoby po prostu zbyt żmudne. Dzięki przeładowaniu metod ActionSend() i SetTo() odpowiada za to tylko drobna zmiana kodu.

Tak wyglądają wysyłki identycznych wiadomości do trzech odbiorców na dwa sposoby: za pomocą metody z fabryki SMSFactory oraz za pomocą łańcuchowego połączenia metod z akcji SMSSend:

SMSFactory.ActionSend(
	new[]{"48111222333", "48444555666", "48777888999"},
	"Hello receivers!")
	.Execute();
SMSFactory.ActionSend()
	.SetTo(new[]{"48111222333", "48444555666", "48777888999"})
	.SetText("Hello again receivers!")
	.Execute();

W Panelu klienta zauważysz możliwość tworzenia grup odbiorców. Biblioteka C# pozwala skorzystać z tychże, aby uprościć zarządzanie masową wysyłką. Przedstawia to kolejny fragment:

SMSFactory.ActionSend()
	.SetGroup("Group_name")
	.SetText("Hello group!")
	.Execute();

Automatyczne SMS w C# – dodatkowe opcje

Klasa Action.SMSSend posiada jeszcze kilka metod, które odpowiadają paru przydatnym funkcją omawianej biblioteki. Przyjrzyjmy się trzem z nich. 

Pole nadawcy SMS

SetSender("sender_name") ustawia pole nadawcy SMS, czyli tekst wyświetlany na telefonie odbiorcy SMS zamiast numeru nadawcy. Może to być nazwa marki lub produktu, coś charakterystycznie kojarzącego się z Twoją firmą. Prezentuje się to lepiej, niż obcy numer telefonu. Pomaga też zwrócić uwagę osoby, która codziennie dostaje na telefon co najmniej kilka powiadomień.

Pola nadawcy SMS możesz tworzyć w Panelu klienta SMSAPI. Od strony programowej do zarządzania nimi służy fabryka SenderFactory oraz akcje z katalogu Api/Action/Sender. 

Zarządzanie nazwami nadawcy SMS w bibliotece C# SMS API

Nazwy nadawcy SMS można tworzyć w Panelu Klienta oraz zarządzać nimi programowo. Służy do tego fabryka SenderFactory i cztery akcje: List, Add, SetDefault, Delete. Najprościej korzystać z nich za pomocą metod z tejże fabryki. Poniższy przykład obrazuje wylistowanie wszystkich utworzonych pól nadawcy, dodanie nowego i ustawienie go jako domyślny oraz jego usunięcie.

var senderFactory = new SenderFactory(client);
var senderNamesResp =	senderFactory.ActionList().Execute();
foreach (var sender in senderNamesResp.List){
	System.Console.WriteLine(
		"Name: "
		+sender.Name
		+", status: "
		+sender.Status
		+", dafault: "
		+sender.Default);
}

senderFactory.ActionAdd("NewSenderName").Execute();
senderFactory.ActionSetDefault("NewSenderName").Execute();
senderFactory.ActionDelete("NewSenderName").Execute();

W poniższym artykule o brandingu SMS znajdziesz dalsze wskazówki i wymogi co do pól nadawcy SMS. Przypomnę tu tylko, że ze względów bezpieczeństwa każde z nich musi zostać zatwierdzone przez pracownika SMSAPI. 

Branding SMS – jak ustawić nazwę nadawcy w miejsce numeru telefonu?

Planowanie wysyłki SMS

Ważną kwestią przy planowaniu kampanii SMS jest ułożenie harmonogramu wysyłki. Moment dostarczenia powiadomienia do klienta ma ważne znaczenie dla skutecznego marketingu. SMS API umożliwia ustawienie daty i godziny wysyłki na przyszłość. Klasa Action.SMSSend robi to poprzez metodę SetDateSent(DateTime data). Argumentem jest standardowy obiekt System.DateTime. Poniższy kod wyśle SMS 30.09.2021, o 16:30:00.

DateTime sendDate = new DateTime(2021, 9, 30,
	16, 30, 0,
	DateTimeKind.Local);
var sendResult = SMSFactory.ActionSend()
	.SetTo("48111222333")
	.SetText("Hello in the future!")
	.SetDateSent(sendDate)
	.Execute();

W razie zmiany planów zaplanowaną wysyłkę można anulować za pomocą akcji SMSDelete. Potrzebny jest do tego unikalny identyfikator SMS-a z systemu, zawarty w odpowiedzi na jego wysłanie. Kontynuując poprzedni kod, może to wyglądać tak:

SMSFactory.ActionDelete(sendResult.List[0].ID);

Więcej na temat planowania wysyłek SMS

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

Personalizacja treści SMS

Aby zrobić na odbiorcy dobre wrażenie, warto potraktować go indywidualnie. W treści SMS może oznaczać to np. zwrot do kogoś po imieniu. Nie oznacza to, że potrzeba pisać ręcznie treść każdego powiadomienia do każdego odbiorcy z osobna.

Zamiast tego możesz spersonalizować treści wiadomości używając parametrów. API umożliwia skorzystanie maksymalnie z 4 parametrów, oznaczanych w treści za pomocą specjalnych ciągów znaków: [%1%], [%2%], [%3%] oraz [%4%]. W poszczególnych wiadomościach będą one zastępowane tekstami, podawanymi do metody SetParam(int i, string text). Przedstawia to przykład:

SMSFactory.ActionSend()
	.SetTo("48111222333", "48444555666")
	.SetText("Hello [%1%], your number is [%2%]!")
	.SetParam(0,["Adam", "Bert"])
	.SetParam(1,["11", "22"])
	.Execute();

Dwie wiadomości będą miały treści:

"Hello Adam, your number is 11!"
"Hello Bert, your number is 22!"

Za pomocą podobnie konstruowanych ciągów specjalnych możesz wykorzystać informacje z bazy kontaktów. Pozwala to personalizować wiadomości bez umieszczania wartości parametrów w kodzie. Na przykład:

SMSFactory.ActionSend()
	.SetTo("48111222333", "48444555666")
	.SetText("Hello [%imie%], your number is [%1%]!")
	.SetParam(0,["11", "22"])
	.Execute();

Pole [%imie%] zostanie zamienione na odpowiednią wartość, przypisaną do danego kontaktu. Lista standardowych pól znajduje się w dokumentacji masowego wysyłania SMS. 

Obsługa błędów wysyłki SMS – gdy nie wszystko idzie gładko

Jak łatwo zgadnąć, błędy w bibliotece C# są obsługiwane poprzez rzucanie wyjątkami. Biblioteka definiuje kilka typów wyjątków. Zawierają one wiadomość i kod błędu. Listę kodów z opisami znajdziesz w odpowiedniej sekcji Dokumentacji. W konsoli Visual Studio możesz możesz spodziewać się następujących wyjątków:

  • ActionException – różne błędy poszczególnych akcji. Na przykład kod 11 oznacza zbyt długą lub brak wiadomości; 13 to niepoprawny numer odbiorcy; 14 – błędne pole nadawcy; 26 – za długi temat wiadomości.
  • ClientExceptin – błędy klienta HTTP. Kody to m.in. 101 (błędny token), 103 (za mało punktów na koncie), 105 (błędny adres IP). 
  • HostException – błędy po stronie serwera. Przykładowe kody to 8 (błąd w odwołaniu) i 201 (wewnętrzny błąd systemu).
  • ProxyException – dotyczą nie SMSAPI, ale połączenia z serwerem, dlatego nie zawierają kodu. Ten wyjątek jest rzucany w reakcji na wyjątek Net.WebException. 
  • ArgumentException – tym razem to wyjątek z przestrzeni System języka C#. Jest rzucany, gdy próbujesz wysłać pustą wiadomość lub odbiorcą jest jednocześnie grupa i pojedynczy numer (parametry To oraz Group wykluczają się).

Inne możliwości biblioteki C# SMS API

Wraz z rozwojem biznesu najprawdopodobniej będziesz również poszerzać listę odbiorców Twoich powiadomień SMS i kampanii marketingowych.

Zrób to sam #07 – Budowanie własnej bazy odbiorców (poradnik wideo)

Możesz zarządzać nią ręcznie w panelu Klienta oraz programowo dzięki fabryce ContactsFactory. Udostępnia ona liczne akcje, które służą do listowania, tworzenia, edycji oraz usuwania zarówno kontaktów (oraz ich poszczególnych pól), jak i ich grup. Otwórz w Visual Studio katalogi Action/Contacts i smsapiTests/Contacts, aby szczegółowo się z nimi zapoznać.

Poza SMS-ami warto pamiętać jeszcze o multimedialnych MMS. Biblioteka wspiera ich wysyłanie dzięki fabryce MMSFactory. Sama wysyłka jest bardzo zbliżona do obsługi SMS-ów. Tak samo możesz ustawić odbiorcę/-ów i czas wysłania, odpowiedź też jest tego samego typu Response.Status. Zawartość to oczywiście nie jest zwykły tekst, ale treść w XML-owym formacie SMIL, którą musisz najpierw poprawnie sformatować.

Mam nadzieję, że teraz masz już pojęcie, jak za pomocą programów w C# możesz prowadzić kampanie SMS-owe. Jeśli masz wątpliwości co do sposobów użycia poszczególnych metod, najpierw prześledź przykłady ich wykorzystania w katalogu testów. Wyjaśnienia i fragmenty programów są też w szczegółowej dokumentacji API. Powodzenia!