Jak odbierać raporty dostarczenia wiadomości przez SMPP API

Protokół Short Message Peer-to-Peer (SMPP) jest kluczowym elementem współczesnej komunikacji SMS, umożliwiającymi Zewnętrznym Jednostkom Wiadomości Krótkich (ESME) wymianę wiadomości i raportów dostarczenia z Centrami Usług Wiadomości Krótkich (SMSC). Dla programistów korzystających z SMPP API wraz z Ozeki SMS Gateway, zrozumienie, jak odbierać raporty dostarczenia, jest kluczowe dla śledzenia statusu wysłanych wiadomości SMS. Ten artykuł dostarcza kompleksowego przewodnika na temat odbierania raportów dostarczenia SMPP na poziomie protokołu, skupiając się na niezbędnych Jednostkach Danych Protokołu (PDU) SMPP do nawiązania połączenia, jego utrzymania oraz odbioru raportów dostarczenia, wykorzystując Ozeki SMS Gateway jako główną platformę serwera SMPP API.

Wprowadzenie do raportów dostarczenia SMPP i Ozeki SMS Gateway

Raporty dostarczenia SMPP to powiadomienia wysyłane przez SMSC w celu poinformowania ESME o statusie wcześniej wysłanej wiadomości SMS, np. czy została dostarczona, nie powiodła się lub została odrzucona. Raporty te są niezbędne dla aplikacji wymagających potwierdzenia dostarczenia wiadomości, takich jak powiadomienia transakcyjne lub kampanie marketingowe. Ozeki SMS Gateway, solidne oprogramowanie SMPP obsługujące wersje 3.3, 3.4 i 5.0, upraszcza proces obsługi raportów dostarczenia SMPP dzięki intuicyjnemu interfejsowi i potężnym opcjom konfiguracyjnym. Ten artykuł szczegółowo opisuje PDU SMPP zaangażowane w konfigurację połączenia klienta SMPP API, jego utrzymanie oraz odbiór raportów dostarczenia, z praktycznymi wskazówkami dla użytkowników Ozeki SMS Gateway.

Zrozumienie PDU SMPP dla raportów dostarczenia

Protokół SMPP opiera się na Jednostkach Danych Protokołu (PDU) do zarządzania komunikacją między klientem SMPP (np. Ozeki SMS Gateway) a SMSC. Aby odbierać raporty dostarczenia, klient musi nawiązać połączenie, utrzymać je i przetwarzać przychodzące raporty dostarczenia. Kluczowe PDU zaangażowane w ten proces to:

• bind_transceiver: Nawiązuje połączenie do wysyłania i odbierania wiadomości SMS oraz raportów dostarczenia.
• enquire_link: Utrzymuje połączenie, aby zapewnić ciągły odbiór raportów dostarczenia.
• deliver_sm: Dostarcza przychodzące raporty dostarczenia (oraz wiadomości SMS) z SMSC do klienta.
• unbind: Kończy sesję SMPP.

Poniżej omawiamy każde PDU, ich strukturę oraz rolę w odbieraniu raportów dostarczenia SMPP przy użyciu SMPP API z Ozeki SMS Gateway.

Konfiguracja połączenia klienta SMPP API

Odbieranie raportów dostarczenia wiadomości SMS wymaga stabilnego połączenia klienta SMPP API z SMSC. Ozeki SMS Gateway upraszcza ten proces, ale zrozumienie operacji na poziomie protokołu jest niezbędne dla zaawansowanych użytkowników i rozwiązywania problemów.

1. Konfiguracja klienta SMPP w Ozeki SMS Gateway

Aby skonfigurować połączenie klienta SMPP API w Ozeki SMS Gateway w celu odbierania raportów dostarczenia, wykonaj następujące kroki:

1. Dostęp do konsoli zarządzania: Zaloguj się do interfejsu webowego Ozeki SMS Gateway przy użyciu konta administratora (domyślna nazwa użytkownika: "admin").
2. Utwórz nowe połączenie: W panelu "Połączenia" kliknij "Dodaj nowe połączenie" i wybierz "Klient SMPP" z sekcji "Połączenia SMS IP".
3. Wprowadź ustawienia SMPP: Podaj następujące dane, zazwyczaj dostarczane przez dostawcę usług SMS:
   • Nazwa hosta: Adres IP lub nazwa hosta SMSC (np. "192.168.1.1").
   • Numer portu: Port TCP/IP do komunikacji SMPP (domyślnie 9500, potwierdź u dostawcy).
   • Nazwa użytkownika (System ID): Identyfikator konta SMSC (np. "smppuser").
   • Hasło: Hasło dla System ID (np. "password123").
   • Wersja SMPP: Wybierz v3.4 dla obsługi transceivera, co jest optymalne dla wysyłania i odbierania.
   • Typ systemu: Opcjonalne, często "SMPP", zgodnie z określeniem dostawcy.
   • Adres nadawcy: Domyślny numer telefonu dla wychodzących SMS (np. "+1234567890").
   • Zakres adresów: Opcjonalne, używane do odbierania wiadomości lub raportów dla określonych numerów.
4. Tryb powiązania: Wybierz "Transceiver", aby umożliwić zarówno wysyłanie SMS, jak i odbieranie raportów dostarczenia przez jedno połączenie.
5. Włącz raporty dostarczenia: W zakładce "Zaawansowane" zaznacz "Żądaj raportu dostarczenia", aby zapewnić wysyłanie raportów dostarczenia przez SMSC dla wysłanych wiadomości.
6. Ustawienia keepalive: Włącz "Wysyłaj pakiety keepalive", aby utrzymać połączenie dla ciągłego odbierania raportów.
7. Włącz logowanie: W zakładce "Zaawansowane" włącz "Loguj zdarzenia komunikacyjne", aby rejestrować PDU SMPP do debugowania.
8. Zapisz i połącz: Kliknij "OK", aby zapisać, a następnie "Połącz", aby zainicjować połączenie SMPP API.

Te ustawienia przygotowują Ozeki SMS Gateway do nawiązania połączenia SMPP API przy użyciu PDU bind_transceiver, umożliwiając odbieranie raportów dostarczenia.

2. PDU bind_transceiver

PDU bind_transceiver uwierzytelnia klienta SMPP w SMSC i nawiązuje połączenie zarówno do wysyłania SMS, jak i odbierania raportów dostarczenia. Jest to pierwszy krok w umożliwieniu funkcjonalności SMPP API.

Struktura PDU bind_transceiver

Długość polecenia: 4 bajty (całkowita długość PDU)
ID polecenia: 0x00000009 (bind_transceiver)
Status polecenia: 0x00000000 (ustawione na 0 dla żądań)
Numer sekwencji: Unikalny identyfikator PDU
System ID: Nazwa użytkownika do uwierzytelnienia (np. "smppuser")
Hasło: Hasło do uwierzytelnienia (np. "password123")
Typ systemu: Opcjonalne, często "SMPP"
Wersja interfejsu: Wersja SMPP (np. 0x34 dla v3.4)
Zakres adresów: Opcjonalne, do odbierania wiadomości lub raportów

Przykładowe PDU bind_transceiver (szesnastkowo):

0000002F 00000009 00000000 00000001 736D70707573657200 70617373776F726431323300 534D505000 34 00

Wyjaśnienie:

• Długość polecenia (0000002F): Całkowita długość PDU (47 bajtów).
• ID polecenia (00000009): Identyfikuje PDU jako bind_transceiver.
• Status polecenia (00000000): Ustawione na 0 dla żądania.
• Numer sekwencji (00000001): Unikalny ID do śledzenia PDU.
• System ID (736D70707573657200): ASCII dla "smppuser" z terminatorem null.
• Hasło (70617373776F726431323300): ASCII dla "password123" z terminatorem null.
• Typ systemu (534D505000): ASCII dla "SMPP" z terminatorem null.
• Wersja interfejsu (34): Wskazuje SMPP v3.4.
• Zakres adresów (00): Null, ponieważ jest opcjonalne.

SMSC odpowiada PDU bind_transceiver_resp. Status polecenia 0x00000000 oznacza udane połączenie. Ozeki SMS Gateway rejestruje tę interakcję w dzienniku "Zdarzenia komunikacyjne", co jest przydatne do weryfikacji połączenia.

Utrzymanie połączenia SMPP API

Stabilne połączenie jest kluczowe dla odbierania raportów dostarczenia SMPP, ponieważ przerwy mogą skutkować pominiętymi aktualizacjami statusu. PDU enquire_link jest używane do utrzymania połączenia.

PDU enquire_link

PDU enquire_link jest okresowo wysyłane przez klienta SMPP w celu potwierdzenia statusu połączenia, zapobiegając rozłączeniu z powodu braku aktywności.

Struktura PDU enquire_link

Długość polecenia: 0x00000010 (16 bajtów)
ID polecenia: 0x00000015 (enquire_link)
Status polecenia: 0x00000000 (ustawione na 0 dla żądań)
Numer sekwencji: Unikalny identyfikator PDU

Przykładowe PDU enquire_link (szesnastkowo):

00000010 00000015 00000000 00000002

Wyjaśnienie:

• Długość polecenia (00000010): Całkowita długość (16 bajtów).
• ID polecenia (00000015): Identyfikuje PDU jako enquire_link.
• Status polecenia (00000000): Ustawione na 0 dla żądania.
• Numer sekwencji (00000002): Unikalny ID do śledzenia PDU.

SMSC odpowiada PDU enquire_link_resp, aby potwierdzić status połączenia. W Ozeki SMS Gateway włączenie opcji "Wysyłaj pakiety keepalive" w zakładce "Komunikacja" zapewnia automatyczne wysyłanie PDU enquire_link (np. co 30 sekund). Jest to kluczowe dla utrzymania niezawodnego połączenia SMPP API do odbierania raportów dostarczenia.

Odbieranie raportów dostarczenia SMPP

Raporty dostarczenia SMPP są odbierane za pomocą PDU deliver_sm, które SMSC wysyła do klienta, aby zgłosić status wcześniej wysłanej wiadomości SMS. PDU zawiera szczegóły, takie jak identyfikator wiadomości, status dostarczenia i znacznik czasu.

PDU deliver_sm dla raportów dostarczenia

PDU deliver_sm jest używane zarówno do przychodzących wiadomości SMS, jak i raportów dostarczenia. W przypadku raportów dostarczenia pole ESM Class PDU jest ustawione na wskazanie potwierdzenia dostarczenia (zwykle 0x04), a treść wiadomości zawiera strukturalny raport z informacjami o statusie.

Struktura PDU deliver_sm (raport dostarczenia)

Długość polecenia: Zmienna (zależy od długości raportu)
ID polecenia: 0x00000005 (deliver_sm)
Status polecenia: 0x00000000 (ustawione na 0 dla żądań)
Numer sekwencji: Unikalny identyfikator PDU
Typ usługi: Opcjonalny, często null
TON adresu źródłowego: Typ numeru nadawcy (SMSC lub odbiorca)
NPI adresu źródłowego: Wskaźnik planu numeracji nadawcy
Adres źródłowy: Numer telefonu nadawcy lub identyfikator SMSC
TON adresu docelowego: Typ numeru odbiorcy (ESME)
NPI adresu docelowego: Wskaźnik planu numeracji odbiorcy
Adres docelowy: Numer telefonu odbiorcy (np. wirtualny numer ESME)
ESM Class: 0x04 (wskazuje potwierdzenie dostarczenia)
Kodowanie danych: Kodowanie znaków (np. 0x00 dla GSM 7-bit)
Krótka wiadomość: Tekst raportu dostarczenia (np. "id:12345 sub:001 dlvrd:001 submit date:2505270415 done date:2505270416 stat:DELIVRD err:000")
Parametry opcjonalne: Pola TLV, takie jak receipted_message_id i message_state

Przykładowe PDU deliver_sm (szesnastkowo):

0000007A 00000005 00000000 00000003 00 01 01 2B3938373635343332313000 01 01 2B3132333435363738393000 04 00 00 00 00 69643A3132333435207375623A30303120646C7672643A303031207375626D697420646174653A3235303532373034313520646F6E6520646174653A3235303532373034313620737461743A44454C49565244206572723A303030

Wyjaśnienie:

• Długość polecenia (0000007A): Całkowita długość (122 bajty).
• ID polecenia (00000005): Identyfikuje PDU jako deliver_sm.
• Status polecenia (00000000): Ustawione na 0 dla żądania.
• Numer sekwencji (00000003): Unikalny identyfikator do śledzenia PDU.
• Typ usługi (00): Null, ponieważ jest opcjonalny.
• TON adresu źródłowego (01): Numer międzynarodowy.
• NPI adresu źródłowego (01): Plan numeracji ISDN/telefoniczny.
• Adres źródłowy (2B3938373635343332313000): ASCII dla "+9876543210" (numer odbiorcy).
• TON adresu docelowego (01): Numer międzynarodowy.
• NPI adresu docelowego (01): Plan numeracji ISDN/telefoniczny.
• Adres docelowy (2B3132333435363738393000): ASCII dla "+1234567890" (numer ESME).
• ESM Class (04): Wskazuje potwierdzenie dostarczenia.
• Kodowanie danych (00): Kodowanie GSM 7-bit.
• Krótka wiadomość: ASCII dla "id:12345 sub:001 dlvrd:001 submit date:2505270415 done date:2505270416 stat:DELIVRD err:000".

Pola raportu dostarczenia:

• id: Identyfikator wiadomości przypisany przez SMSC (np. "12345").
• sub: Liczba odbiorców (np. "001").
• dlvrd: Liczba dostarczonych wiadomości (np. "001").
• submit date: Znacznik czasu wysłania (np. "2505270415" dla 27 maja 2025, 04:15).
• done date: Znacznik czasu dostarczenia (np. "2505270416").
• stat: Status dostarczenia (np. "DELIVRD" dla dostarczonej, "UNDELIV" dla niedostarczonej).
• err: Kod błędu (np. "000" dla braku błędu).

Klient musi odpowiedzieć PDU deliver_sm_resp, aby potwierdzić odbiór. Ozeki SMS Gateway obsługuje to automatycznie i kieruje raport dostarczenia do skonfigurowanej aplikacji lub bazy danych, rejestrując go w panelu "Wiadomości".

Konfiguracja Ozeki SMS Gateway do odbioru raportów dostarczenia

Aby zapewnić poprawne przetwarzanie raportów dostarczenia SMPP przez Ozeki SMS Gateway:

1. Włącz raporty dostarczenia: W konfiguracji klienta SMPP zaznacz "Żądaj raportu dostarczenia" w zakładce "Zaawansowane", aby poinstruować SMSC o wysyłaniu raportów dostarczenia.
2. Konfiguracja numeru wirtualnego: Upewnij się, że SMSC jest skonfigurowany do wysyłania raportów dostarczenia na wirtualny numer lub zakres adresów określony w ustawieniach klienta SMPP.
3. Integracja z bazą danych: Skonfiguruj Ozeki do przechowywania raportów dostarczenia w bazie danych, modyfikując instrukcję SQL SELECT w konfiguracji "Użytkownik bazy danych" (np. "SELECT id, sender, receiver, msg, msgtype, status FROM ozekimessagein WHERE msgtype='DLR'").
4. Logowanie: Włącz logowanie PDU SMPP, aby monitorować przychodzące PDU deliver_sm w celu debugowania.

Dzięki tym ustawieniom Ozeki SMS Gateway będzie przetwarzał i przechowywał raporty dostarczenia, udostępniając je dla aplikacji lub dalszej analizy.

Zakończenie połączenia SMPP API

Gdy sesja SMPP API nie jest już potrzebna, klient wysyła PDU unbind, aby elegancko zakończyć połączenie.

PDU unbind

PDU unbind sygnalizuje SMSC zamknięcie sesji SMPP.

Struktura PDU unbind

Długość polecenia: 0x00000010 (16 bajtów)
ID polecenia: 0x00000006 (unbind)
Status polecenia: 0x00000000 (ustawione na 0 dla żądań)
Numer sekwencji: Unikalny identyfikator PDU

Przykładowe PDU unbind (szesnastkowo):

00000010 00000006 00000000 00000004

Wyjaśnienie:

• Długość polecenia (00000010): Całkowita długość (16 bajtów).
• ID polecenia (00000006): Identyfikuje PDU jako unbind.
• Status polecenia (00000000): Ustawione na 0 dla żądania.
• Numer sekwencji (00000004): Unikalny identyfikator do śledzenia PDU.

SMSC odpowiada PDU unbind_resp, potwierdzając zakończenie sesji. W Ozeki SMS Gateway można to zainicjować, klikając "Rozłącz" w panelu "Połączenia".

Aby zoptymalizować implementację SMPP API do odbierania raportów dostarczenia za pomocą Ozeki SMS Gateway:

• Żądaj raportów dostarczenia: Zawsze włącz opcję "Żądaj raportu dostarczenia" podczas wysyłania SMS-ów, aby zapewnić generowanie raportów przez SMSC.
• Monitoruj logi: Używaj logów PDU SMPP do rozwiązywania problemów z PDU deliver_sm, szczególnie w przypadku raportów dostarczenia.
• Używaj trybu transceiver: Preferuj tryb transceiver dla efektywności, ponieważ obsługuje zarówno wysyłanie SMS-ów, jak i odbieranie raportów dostarczenia.
• Bezpieczne połączenia: Używaj SMPPS (SMPP przez SSL/TLS), jeśli jest obsługiwane przez dostawcę, aby zapewnić bezpieczną transmisję raportów dostarczenia.
• Analizuj raporty dostarczenia: Skonfiguruj aplikacje do analizowania pola Short Message w PDU deliver_sm, aby wyodrębnić informacje o statusie (np. "DELIVRD" lub "UNDELIV") w celu uzyskania przydatnych informacji.

Podsumowanie

Odbieranie raportów dostarczenia SMPP za pomocą SMPP API z Ozeki SMS Gateway polega na nawiązaniu połączenia z PDU bind_transceiver, utrzymaniu go za pomocą PDU enquire_link oraz przetwarzaniu raportów dostarczenia przez PDU deliver_sm. Poprzez prawidłową konfigurację Ozeki SMS Gateway i zrozumienie podstawowego protokołu SMPP, programiści mogą budować niezawodne systemy do śledzenia statusu dostarczenia SMS-ów. Solidność SMPP API i elastyczna konfiguracja Ozeki sprawiają, że jest to doskonały wybór do zarządzania raportami dostarczenia w aplikacjach SMS o dużej skali. Więcej szczegółów można znaleźć w dokumentacji Ozeki SMS Gateway lub skontaktować się z dostawcą usług SMS w celu uzyskania konkretnych wymagań konfiguracyjnych.