Wie man SMPP-Zustellungsberichte über die SMPP-API empfängt

Das Short Message Peer-to-Peer (SMPP)-Protokoll ist ein Grundpfeiler der modernen SMS-Kommunikation, der es External Short Message Entities (ESMEs) ermöglicht, Nachrichten und Zustellungsberichte mit Short Message Service Centers (SMSCs) auszutauschen. Für Entwickler, die die SMPP-API mit Ozeki SMS Gateway verwenden, ist es entscheidend zu verstehen, wie Zustellungsberichte empfangen werden, um den Status gesendeter SMS-Nachrichten zu verfolgen. Dieser Artikel bietet eine umfassende Anleitung zum Empfang von SMPP-Zustellungsberichten auf Protokollebene, wobei der Schwerpunkt auf den erforderlichen SMPP Protocol Data Units (PDUs) für die Verbindungseinrichtung, -wartung und den Empfang von Zustellungsberichten liegt, wobei Ozeki SMS Gateway als primäre SMPP-API-Serverplattform verwendet wird.

Einführung in SMPP-Zustellungsberichte und Ozeki SMS Gateway

SMPP-Zustellungsberichte sind Benachrichtigungen, die vom SMSC an die ESME gesendet werden, um über den Status einer zuvor gesendeten SMS zu informieren, z.B. ob sie zugestellt wurde, fehlgeschlagen ist oder abgelehnt wurde. Diese Berichte sind essenziell für Anwendungen, die eine Bestätigung der Nachrichtenzustellung erfordern, wie z.B. transaktionale Benachrichtigungen oder Marketingkampagnen. Ozeki SMS Gateway, eine robuste SMPP-Software, die die Versionen 3.3, 3.4 und 5.0 unterstützt, vereinfacht den Umgang mit SMPP-Zustellungsberichten durch seine intuitive Oberfläche und leistungsstarke Konfigurationsoptionen. Dieser Artikel beschreibt die SMPP-PDUs, die für die Einrichtung einer SMPP-API-Clientverbindung, deren Wartung und den Empfang von Zustellungsberichten erforderlich sind, mit praktischen Anleitungen für Benutzer von Ozeki SMS Gateway.

Verständnis der SMPP-PDUs für Zustellungsberichte

Das SMPP-Protokoll verwendet Protocol Data Units (PDUs), um die Kommunikation zwischen dem SMPP-Client (z.B. Ozeki SMS Gateway) und dem SMSC zu verwalten. Um Zustellungsberichte zu empfangen, muss der Client eine Verbindung herstellen, diese aufrechterhalten und eingehende Zustellungsberichte verarbeiten. Die wichtigsten beteiligten PDUs sind:

• bind_transceiver: Stellt eine Verbindung für das Senden und Empfangen von SMS und Zustellungsberichten her.
• enquire_link: Hält die Verbindung aufrecht, um den kontinuierlichen Empfang von Zustellungsberichten zu gewährleisten.
• deliver_sm: Liefert eingehende Zustellungsberichte (und SMS-Nachrichten) vom SMSC an den Client.
• unbind: Beendet die SMPP-Sitzung.

Im Folgenden untersuchen wir jede PDU, ihre Struktur und ihre Rolle beim Empfang von SMPP-Zustellungsberichten mit der SMPP-API und Ozeki SMS Gateway.

Einrichten einer SMPP-API-Client-Verbindung

Das Empfangen von SMPP-Zustellberichten erfordert eine stabile SMPP-API-Client-Verbindung zum SMSC. Ozeki SMS Gateway vereinfacht diesen Prozess, aber das Verständnis der Protokollebene ist für fortgeschrittene Benutzer und die Fehlerbehebung unerlässlich.

1. Konfiguration des SMPP-Clients in Ozeki SMS Gateway

Um eine SMPP-API-Client-Verbindung in Ozeki SMS Gateway für den Empfang von Zustellberichten einzurichten, folgen Sie diesen Schritten:

1. Zugriff auf die Management-Konsole: Melden Sie sich mit dem Administrator-Konto (Standard-Benutzername: "admin") an der Ozeki SMS Gateway-Weboberfläche an.
2. Neue Verbindung erstellen: Klicken Sie im Bereich "Verbindungen" auf "Neue Verbindung hinzufügen" und wählen Sie "SMPP-Client" aus dem Abschnitt "IP-SMS-Verbindungen".
3. SMPP-Einstellungen eingeben: Geben Sie die folgenden Details an, die normalerweise von Ihrem SMS-Dienstanbieter bereitgestellt werden:
   • Hostname: Die IP-Adresse oder der Hostname des SMSC (z.B. "192.168.1.1").
   • Portnummer: Der TCP/IP-Port für die SMPP-Kommunikation (Standard ist 9500, bestätigen Sie dies mit Ihrem Anbieter).
   • Benutzername (System-ID): Ihr SMSC-Konto-Identifikator (z.B. "smppuser").
   • Passwort: Das Passwort für die System-ID (z.B. "password123").
   • SMPP-Version: Wählen Sie v3.4 für Transceiver-Unterstützung, was optimal für das Senden und Empfangen ist.
   • Systemtyp: Optional, oft "SMPP", wie vom Anbieter angegeben.
   • Absenderadresse: Die standardmäßige Telefonnummer für ausgehende SMS (z.B., "+1234567890").
   • Adressbereich: Optional, wird für den Empfang von Nachrichten oder Berichten für bestimmte Nummern verwendet.
4. Bind-Modus: Wählen Sie "Transceiver", um sowohl das Senden von SMS als auch den Empfang von Zustellberichten über eine einzige Verbindung zu ermöglichen.
5. Zustellberichte aktivieren: Aktivieren Sie im Tab "Erweitert" die Option "Zustellbericht anfordern", um sicherzustellen, dass der SMSC Zustellberichte für gesendete Nachrichten sendet.
6. Keepalive-Einstellungen: Aktivieren Sie "Keepalive-Pakete senden", um die Verbindung für den kontinuierlichen Empfang von Berichten aufrechtzuerhalten.
7. Protokollierung aktivieren: Aktivieren Sie im Tab "Erweitert" die Option "Kommunikationsereignisse protokollieren", um SMPP-PDUs für die Fehlersuche zu erfassen.
8. Speichern und verbinden: Klicken Sie auf "OK", um zu speichern, dann auf "Verbinden", um die SMPP-API-Verbindung zu starten.

Diese Einstellungen bereiten Ozeki SMS Gateway darauf vor, eine SMPP-API-Verbindung mit dem bind_transceiver-PDU herzustellen, wodurch der Empfang von Zustellberichten ermöglicht wird.

2. Das bind_transceiver-PDU

Das bind_transceiver-PDU authentifiziert den SMPP-Client beim SMSC und stellt eine Verbindung sowohl für das Senden von SMS als auch für den Empfang von Zustellberichten her. Es ist der erste Schritt zur Aktivierung der SMPP-API-Funktionalität.

Struktur des bind_transceiver-PDU

Befehlslaenge: 4 Bytes (Gesamtlaenge des PDU)
Befehls-ID: 0x00000009 (bind_transceiver)
Befehlsstatus: 0x00000000 (für Anfragen auf 0 gesetzt)
Sequenznummer: Eindeutige Kennung für das PDU
System-ID: Benutzername fuer Authentifizierung (z.B. "smppuser")
Passwort: Passwort fuer Authentifizierung (z.B. "password123")
Systemtyp: Optional, oft "SMPP"
Schnittstellenversion: SMPP-Version (z.B. 0x34 fuer v3.4)
Adressbereich: Optional, fuer den Empfang von Nachrichten oder Berichten

Beispiel bind_transceiver-PDU (hexadezimal):

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

Erklaerung:

• Befehlslaenge (0000002F): Gesamtlaenge des PDU (47 Bytes).
• Befehls-ID (00000009): Identifiziert das PDU als bind_transceiver.
• Befehlsstatus (00000000): Fuer die Anfrage auf 0 gesetzt.
• Sequenznummer (00000001): Eine eindeutige ID zur Verfolgung des PDU.
• System-ID (736D70707573657200): ASCII für "smppuser" mit Null-Terminator.
• Passwort (70617373776F726431323300): ASCII für "password123" mit Null-Terminator.
• Systemtyp (534D505000): ASCII für "SMPP" mit Null-Terminator.
• Schnittstellenversion (34): Gibt SMPP v3.4 an.
• Adressbereich (00): Null, da optional.

Der SMSC antwortet mit einem bind_transceiver_resp-PDU. Ein Befehlsstatus von 0x00000000 zeigt eine erfolgreiche Verbindung an. Ozeki SMS Gateway protokolliert diese Interaktion im "Kommunikationsereignisse"-Log, was für die Überprüfung der Verbindung nützlich ist.

Aufrechterhaltung der SMPP-API-Verbindung

Eine stabile Verbindung ist entscheidend für den Empfang von SMPP-Zustellberichten, da Unterbrechungen zu verpassten Statusupdates führen können. Das enquire_link-PDU wird verwendet, um die Verbindung aufrechtzuerhalten.

Das enquire_link-PDU

Das enquire_link-PDU wird periodisch vom SMPP-Client gesendet, um den Verbindungsstatus zu bestätigen und eine Trennung aufgrund von Inaktivität zu verhindern.

Struktur des enquire_link-PDU

Befehlslaenge: 0x00000010 (16 Bytes)
Befehls-ID: 0x00000015 (enquire_link)
Befehlsstatus: 0x00000000 (für Anfragen auf 0 gesetzt)
Sequenznummer: Eindeutige Kennung für das PDU

Beispiel enquire_link-PDU (hexadezimal):

00000010 00000015 00000000 00000002

Erklaerung:

• Befehlslaenge (00000010): Gesamtlaenge (16 Bytes).
• Befehls-ID (00000015): Identifiziert das PDU als enquire_link.
• Befehlsstatus (00000000): Fuer die Anfrage auf 0 gesetzt.
• Sequenznummer (00000002): Eine eindeutige ID zur Verfolgung des PDU.

Der SMSC antwortet mit einem enquire_link_resp-PDU, um den Verbindungsstatus zu bestätigen. In Ozeki SMS Gateway stellt die Aktivierung von "Keepalive-Pakete senden" im Tab "Kommunikation" sicher, dass enquire_link-PDUs automatisch gesendet werden (z.B. alle 30 Sekunden). Dies ist entscheidend für die Aufrechterhaltung einer zuverlässigen SMPP-API-Verbindung für den Empfang von Zustellberichten.

Empfangen von SMPP-Zustellberichten

SMPP-Zustellberichte werden über die deliver_sm-PDU empfangen, die der SMSC an den Client sendet, um den Status einer zuvor gesendeten SMS zu melden. Die PDU enthält Details wie die Nachrichten-ID, den Zustellstatus und den Zeitstempel.

Die deliver_sm-PDU für Zustellberichte

Die deliver_sm-PDU wird sowohl für eingehende SMS-Nachrichten als auch für Zustellberichte verwendet. Für Zustellberichte ist das Feld ESM Class der PDU so gesetzt, dass es einen Zustellungsbeleg anzeigt (typischerweise 0x04), und der Nachrichteninhalt enthält einen strukturierten Bericht mit Statusinformationen.

Aufbau der deliver_sm-PDU (Zustellbericht)

  
Command Length: Variable (abhängig von der Berichtslänge)  
Command ID: 0x00000005 (deliver_sm)  
Command Status: 0x00000000 (für Anfragen auf 0 gesetzt)  
Sequence Number: Eindeutige Kennung für die PDU  
Service Type: Optional, oft null  
Source Address TON: Type of Number für den Absender (SMSC oder Empfänger)  
Source Address NPI: Numbering Plan Indicator für den Absender  
Source Address: Telefonnummer des Absenders oder SMSC-Kennung  
Destination Address TON: Type of Number für den Empfänger (ESME)  
Destination Address NPI: Numbering Plan Indicator für den Empfänger  
Destination Address: Telefonnummer des Empfängers (z.B. virtuelle Nummer des ESME)  
ESM Class: 0x04 (zeigt Zustellungsbeleg an)  
Data Coding: Zeichenkodierung (z.B. 0x00 für GSM 7-bit)  
Short Message: Text des Zustellberichts (z.B. "id:12345 sub:001 dlvrd:001 submit date:2505270415 done date:2505270416 stat:DELIVRD err:000")  
Optional Parameters: TLV-Felder wie receipted_message_id und message_state  

Beispiel einer deliver_sm-PDU (hexadezimal):

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

Erklärung:

• Command Length (0000007A): Gesamtlänge (122 Bytes).
• Command ID (00000005): Identifiziert die PDU als deliver_sm.
• Command Status (00000000): Für die Anfrage auf 0 gesetzt.
• Sequence Number (00000003): Eindeutige ID zur Verfolgung der PDU.
• Service Type (00): Null, da optional.
• Source Address TON (01): Internationale Nummer.
• Source Address NPI (01): ISDN/Telefonnummernplan.
• Source Address (2B3938373635343332313000): ASCII für "+9876543210" (Nummer des Empfängers).
• Destination Address TON (01): Internationale Nummer.
• Destination Address NPI (01): ISDN/Telefonnummernplan.
• Destination Address (2B3132333435363738393000): ASCII für "+1234567890" (Nummer des ESME).
• ESM Class (04): Zeigt einen Zustellungsbeleg an.
• Data Coding (00): GSM 7-bit-Kodierung.
• Short Message: ASCII für "id:12345 sub:001 dlvrd:001 submit date:2505270415 done date:2505270416 stat:DELIVRD err:000".

Felder des Zustellberichts:

• id: Vom SMSC zugewiesene Nachrichten-ID (z.B. "12345").
• sub: Anzahl der Empfänger (z.B. "001").
• dlvrd: Anzahl der zugestellten Nachrichten (z.B. "001").
• submit date: Zeitstempel der Übermittlung (z.B. "2505270415" für 27. Mai 2025, 04:15).
• done date: Zeitstempel der Zustellung (z.B. "2505270416").
• stat: Zustellstatus (z.B. "DELIVRD" für zugestellt, "UNDELIV" für nicht zustellbar).
• err: Fehlercode (z.B. "000" für keinen Fehler).

Der Client muss mit einer deliver_sm_resp-PDU antworten, um den Empfang zu bestätigen. Ozeki SMS Gateway handelt dies automatisch ab und leitet den Zustellbericht an die konfigurierte Anwendung oder Datenbank weiter, wo er im "Messages"-Panel protokolliert wird.

Konfiguration von Ozeki SMS Gateway für den Empfang von Zustellberichten

Um sicherzustellen, dass Ozeki SMS Gateway SMPP-Zustellberichte korrekt verarbeitet:

1. Zustellberichte aktivieren: Aktivieren Sie in der SMPP-Client-Konfiguration unter dem Reiter "Erweitert" die Option "Zustellbericht anfordern", um den SMSC anzuweisen, Zustellberichte zu senden.
2. Einrichtung einer virtuellen Nummer: Stellen Sie sicher, dass der SMSC so konfiguriert ist, dass Zustellberichte an die virtuelle Nummer oder den Adressbereich gesendet werden, der in den SMPP-Client-Einstellungen angegeben ist.
3. Datenbankintegration: Konfigurieren Sie Ozeki so, dass Zustellberichte in einer Datenbank gespeichert werden, indem Sie die SQL-SELECT-Anweisung in der "Database user"-Konfiguration anpassen (z.B. "SELECT id, sender, receiver, msg, msgtype, status FROM ozekimessagein WHERE msgtype='DLR'").
4. Protokollierung: Aktivieren Sie die SMPP-PDU-Protokollierung, um eingehende deliver_sm-PDUs zur Fehlerbehebung zu überwachen.

Mit diesen Einstellungen verarbeitet und speichert Ozeki SMS Gateway Zustellberichte, sodass sie für Anwendungen oder weitere Analysen verfügbar sind.

Beenden der SMPP-API-Verbindung

Wenn die SMPP-API-Sitzung nicht mehr benötigt wird, sendet der Client eine unbind-PDU, um die Verbindung ordnungsgemäß zu beenden.

Die unbind-PDU

Die unbind-PDU signalisiert dem SMSC, die SMPP-Sitzung zu schließen.

Aufbau der unbind-PDU

  
Command Length: 0x00000010 (16 Bytes)  
Command ID: 0x00000006 (unbind)  
Command Status: 0x00000000 (für Anfragen auf 0 gesetzt)  
Sequence Number: Eindeutige Kennung für die PDU  

Beispiel einer unbind-PDU (hexadezimal):

  
00000010 00000006 00000000 00000004  

Erklärung:

• Command Length (00000010): Gesamtlänge (16 Bytes).
• Command ID (00000006): Identifiziert die PDU als unbind.
• Command Status (00000000): Für die Anfrage auf 0 gesetzt.
• Sequence Number (00000004): Eindeutige ID zur Verfolgung der PDU.

Der SMSC antwortet mit einer unbind_resp-PDU, die die Sitzungsbeendigung bestätigt. In Ozeki SMS Gateway kann dies durch Klicken auf "Trennen" im "Connections"-Panel initiiert werden.

Um Ihre SMPP API-Implementierung für den Empfang von Zustellberichten mit Ozeki SMS Gateway zu optimieren:

• Zustellberichte anfordern: Aktivieren Sie immer die Option "Zustellbericht anfordern" beim Versand von SMS, um sicherzustellen, dass die SMSC Berichte generiert.
• Protokolle überwachen: Verwenden Sie SMPP PDU-Protokolle, um Probleme mit deliver_sm PDUs, insbesondere bei Zustellberichten, zu beheben.
• Transceiver-Modus verwenden: Bevorzugen Sie den Transceiver-Modus für Effizienz, da er sowohl das Senden von SMS als auch den Empfang von Zustellberichten unterstützt.
• Sichere Verbindungen: Verwenden Sie SMPPS (SMPP über SSL/TLS), falls von Ihrem Anbieter unterstützt, um eine sichere Übertragung von Zustellberichten zu gewährleisten.
• Zustellberichte analysieren: Konfigurieren Sie Anwendungen so, dass sie das Short Message-Feld der deliver_sm PDU analysieren, um Statusinformationen (z.B. "DELIVRD" oder "UNDELIV") für umsetzbare Erkenntnisse zu extrahieren.

Fazit

Der Empfang von SMPP-Zustellberichten über die SMPP API mit Ozeki SMS Gateway umfasst das Herstellen einer Verbindung mit der bind_transceiver PDU, deren Aufrechterhaltung mit enquire_link PDUs und die Verarbeitung von Zustellberichten über die deliver_sm PDU. Durch die korrekte Konfiguration von Ozeki SMS Gateway und das Verständnis des zugrunde liegenden SMPP-Protokolls können Entwickler zuverlässige Systeme zum Verfolgen des SMS-Zustellstatus aufbauen. Die Robustheit der SMPP API und die flexible Konfiguration von Ozeki machen sie zu einer hervorragenden Wahl für die Verwaltung von Zustellberichten in SMS-Anwendungen mit hohem Volumen. Weitere Details finden Sie in der Ozeki SMS Gateway-Dokumentation oder wenden Sie sich an Ihren SMS-Dienstanbieter für spezifische Konfigurationsanforderungen.