Zagadnienia: 2WAY, API, IT

API SMSAPI od podstaw – odbieranie SMS online #02

30 czerwca, 2021
Przeczytasz w 7 min. 36 sek.
SMS API poradnik programisty podstawy odbiór SMS online

W poprzednim artykule z serii „API SMSAPI od podstaw” opisałem metodę, jaką można wykorzystać, aby wysłać SMS online przez Panel Klienta SMSAPI. W tym artykule chciałbym poruszyć temat odwrotny: jak za pomocą systemu informatycznego odebrać SMS wysłany przez klienta?

To jest druga cześć poradnika programisty SMSAPI. Jeżeli szukasz bardziej podstawowej wiedzy zapraszam do lektury wprowadzenia w wykorzystanie API do wysyłki kampanii SMS.

Od firm coraz częściej oczekujemy interakcji, a nie jedynie informacji

Myślę, że w przypadku obsługi klienta taka potrzeba istniała zawsze, ale dopiero od niedawna popularne technologie zaczęły na nią odpowiadać. Narzędziem, które jako pierwsze kojarzy się z taką interakcją jest Facebook Messenger. WhatsApp dołączył do tego grona dając partnerom (i w konsekwencji firmom) dostęp do swojego biznesowego API, a wcześniej bądź później tym tropem poszły również inne komunikatory popularne (Viber czy Telegram) w różnych częściach świata.

Wykorzystując interfejs programistyczny jesteśmy w stanie prowadzić dialog z użytkownikiem. Pierwszym przykładem, których przychodzi mi na myśl jest komunikacja w Biurze Obsługi Klienta. Wyobraźmy sobie taką sytuację: konsument pisze z firmą przez WhatsApp. Po drugiej stronie, za kilkoma systemami pośredniczącymi, jakąś wtyczką i platformą customer service, za monitorem i klawiaturą odpowiada pracownik.

Piękne są tutaj dwie rzeczy: fakt, że klient używa apki, którą zna i ma zainstalowaną na swoim telefonie oraz ułatwienie pracy działu BOK – tutaj też osoba pisze wykorzystując swój dobrze znany interfejs. Prosty proces nie tylko usprawnia obsługę zapytań, a także zapewnia porządek w BOK.

Conversational Messaging definicja

Komunikacja konwersacyjna (Conversational Messaging) oznacza interakcję jeden na jeden pomiędzy klientem i biznesem za pomocą różnorodnych kanałów komunikacyjnych. Na zapytania może odpowiadać zarówno pracownik biura obsługi klienta, jak i bot czy zaplanowany skrypt.

Do brzegu, gdzie ten odbiór SMS?

SMSAPI zapewnia narzędzia, które pomogą Ci wykorzystać moc SMS-a do wdrożenia komunikacji dwustronnej. Krótko mówiąc, Ty będziesz mógł napisać o czymś klientowi, a klient będzie mógł odpowiedzieć.

Świetnym przykładem jest moduł Ankiety i głosowania, który wykorzystując dwukierunkową komunikację SMS pozwala na prowadzanie badań. Często możemy je spotkać w telewizji albo radio. Nasz rząd też doskonale zna zalety SMS-ów, wykorzystuje je między innymi do zapisów na szczepienia przeciw COVID.

W jednym z wcześniejszych artykułów opisywałem pomiar wskaźnika NPS. SMS jest doskonałym narzędziem do przeprowadzenia badania satysfakcji klientów. Cały czas jestem pod wielkim wrażeniem możliwości i prostoty tego rozwiązania (no i wyniku, ale nie wypada mi chyba cały czas o tym wspominać, więc tego nie zrobię…).

Odbiór SMS konfiguracja

W SMSAPI daje możliwość odbierania SMS. Dzieje się to za pomocą mechanizmu callback. Jako pierwszy krok, musisz zadbać o to, żeby wysłane SMS trafiały na numer skojarzony z Twoim kontem (albo współdzielony z innymi kontami za pomocą prefiksu).

Krok 1: Zarezerwuj numer odbiorczy SMS

Pierwszą rzeczą jest zarezerwowanie numeru odbiorczego SMS, którego zamierzasz używać. Dysponujesz pulą numerów długich (9 cyfr), krótkich (4 lub 5 cyfr) oraz przeznaczonymi na potrzeby kampanii zagranicznych.

Wybór zależy od konkretnego przypadku i jeśli decyzja nie jest jasna, zawsze możesz zadzwonić do naszego Biura Obsługi Klienta, które na pewno doradzi Ci najlepszą na świecie opcję.

SMS API zarezerwuj numer odbiorczy SMS

Na tej stronie możesz wybrać i skonfigurować parametry numeru do odbioru SMS-ów. Wszystkie wiadomości przesłane przez klientów będą dostępne w Panelu.

Krok 2: Aktywacja numeru odbiorczego SMS

Teraz możesz pójść po kawę, a nasze Biuro Obsługi Klienta aktywuje wybrany przez Ciebie numer odbiorczy SMS.

Ale miej pod ręką telefon, bo w zależności od historii i aktywności dotychczasowej współpracy, może się wydarzyć, że któraś z koleżanek z BOK-u poprosi telefonicznie bądź za pomocą poczty e-mail o dodatkowe informacje. Przedstaw zamiary i cele odbioru SMS-ów, dzięki temu będzie w stanie lepiej doradzić w różnych obszarach, chociażby proponując inny typ numeru bardziej adekwatny do Twojej kampanii SMS.

Sama aktywacja powinna nastąpić bardzo szybko. Możesz założyć, że w godzinach pracy (poniedziałek-piątek, 08-17), całą procedurę uda się załatwić w trzy kwadranse.

Krok 3: Przygotowanie skryptu, który będzie obsługiwał odbiory SMS

W końcu trochę prawdziwego programowania! Ale też nie za dużo, akurat tyle, żeby zdążyć przed śniadaniem. Zacznij od przygotowania skryptu obsługującego informacje przekazywane SMSAPI po zarejestrowaniu odebranej wiadomości SMS.

Warunki, które musi spełnić skrypt do odbioru SMS:

  • być dostępny publicznie z internetu, a przynajmniej z adresu IP serwerów SMSAPI,
  • być w stanie obsłużyć pola z tablicy POST, wymienione w Dokumentacji, które będą informowały o szczegółowych danych SMS-a przychodzącego,
  • być zarejestrowany do obsługi callbacków przychodzących w Panelu Klienta, ale o tym więcej w następnym kroku.

Konfiguracja webservera i interpretera PHP jest poza zakresem tego artykułu. Ja w moim laboratorium wykorzystałem nginx w dosyć standardowej konfiguracji z PHP w wersji 7.3.

Odbiór SMS – przykładowy skrypt

<?php

$to = $_POST['sms_to'] ?? '';
$from = $_POST['sms_from'] ?? '';
$date = $_POST['sms_date'] ?? '';
$content = $_POST['sms_text'] ?? '';

$logTemplate = "to: %s\n"
    . "from: %s\n"
    . "date: %s\n"
    . "content: %s\n";

$log = sprintf($logTemplate, $to, $from, $date, $content);

$file = fopen('callback-sms.log', 'a+');
fwrite($file, $log);
fwrite($file, str_repeat('-', 32) . PHP_EOL);
fclose($file);

echo 'OK';

Celem tego skryptu jest zinterpretowanie danych, które zostaną wysłane za pomocą callbacka oraz zapisanie ich do pliku callback-sms.log.

W pierwszej części skryptu zadeklarowane są zmienne, które będą wyświetlane dalej. Są one od razu wypełnione stosownymi elementami tablicy POST, która zostanie skryptowi przekazana wraz z tablicą. Komplet zmiennych, które przekazujesz z każdym typem callbacków jest dostępny w Dokumentacji.

Uwaga na typy callback

Zwróć szczególną uwagę na subtelne różnice pomiędzy różnymi typami callbacków. W przypadku callbacka z odbiorem tablica będzie typu POST, ale w przypadku callbacka z raportem tablica będzie już typu GET.

Dalej definiujesz format, w którym będziesz logować informacje przesłane przez callback i przypisane do zmiennych. Następnie, w oparciu o ten format zmienna $log wypełniana jest danymi do wyświetlenia.

W kolejnym kroku zapisujesz dane do pliku callback-sms.log i wysyłasz jako odpowiedź string „OK”, którego SMSAPI oczekuje jako potwierdzenie. Koniecznie musi to być „OK” – odesłanie kodu http 200 nie wystarczy. Tyle kodzenia na dzisiaj!

Plik umieściłem na publicznie widocznym serwerze, pod adresem https://adres_serwera/smsapi/receive.php. Teraz pozostaje jedynie skonfigurować callback w serwisie SMSAPI. Do dzieła!

Krok 4: Konfiguracja callbacka

Po zalogowaniu do Panelu Klienta SMSAPI przejdź do widoku Adresy callback. W tym miejscu możesz skonfigurować wszystkie dostępne w SMSAPI callbacki (a jest ich sporo!), ale teraz interesuje Cię jedynie „Odbiór SMS”. Wybierz go z listy.

Dodaj adres callback w Panelu Klienta SMSAPI

Callback możesz skonfigurować tak, żeby zostawał uaktywniony tylko wtedy, kiedy otrzymasz SMS na konkretny numer odbiorczy. Wybierz, więc numer (na liście może być ich więcej – musisz wybrać dokładnie ten, który aktywowałeś w kroku 2), a następnie uzupełnij adres, pod którym widoczny jest skrypt z kroku 3. Kliknij dodaj, a na liście pojawia się świeżutko stworzona konfiguracja.

Lista aktywnych adresów callback w Panelu Klienta SMSAPI

Krok 5: Test!

Teraz możesz (a w zasadzie powinieneś) przetestować połączenie – sprawdź, czy callback zostaje dostarczony. W tym celu kliknij ikonkę „Play” w kolumnie Opcje po prawej stronie. W moim przypadku test wypadł pozytywnie, co zostało potwierdzone niebieskim dymkiem w prawej górnej części ekranu.

Jeśli jednak coś nie zadziała (SMSAPI pokaże Ci po chwili krótki raport ze źródłem problemu), musisz sprawdzić publiczną dostępność Twojego skryptu i adres URL.

Następnie sprawdź, czy konfiguracja, skrypt i numer funkcjonują prawidłowo. Najprościej zrobisz to wysyłając SMS z telefonu na numer aktywowany w kroku 2 i jednocześnie monitorując plik callback-sms.log.

Jeśli zostanie on utworzony, to oznacza, że pojawił się pierwszy SMS. Sukces! Wysłany z telefonu SMS został zarejestrowany przez SMSAPI, a informacja o nim została przesłana callbackiem do skryptu. Ten zarejestrował i zinterpretował informację zapisując ją do pliku.

No dobra, coś tam niby się pojawiło… Ale co dalej?

Podany przykład jest tylko zachętą do tego, żeby budować dalej. Odbieranie SMS przez system informatyczny daje wielorakie możliwości – od budowania procesów klasy Marketing Automation, po wspomniane na początku wykorzystanie wiadomości tekstowych jako kanału wsparcia w Biurze Obsługi Klienta… Sky is the limit.

Photo by Andrew Wulf on Unsplash