SMPP-API

API-Informationen

Dieses Protokoll definiert das SMPP-Kommunikationsprotokoll für den EngageLab-OTP-Dienst und wurde entwickelt, um eine effiziente und zuverlässige Nachrichtenübermittlung sowie Statusberichte über TCP-Verbindungen zu ermöglichen. Die API-Informationen umfassen die für die Verbindung erforderliche IP-Adresse, Portnummer und Authentifizierungsdetails. Bitte stellen Sie sicher, dass das über autorisierte Kanäle bereitgestellte Konto und Passwort korrekt konfiguriert sind.

SMPP-Adresse

SMPP-Adresse: otpsmpp.api.engagelab.cc

Bitte beziehen Sie die folgenden Informationen über einen autorisierten Kanal, z. B. über den Business- oder technischen Support:

• Port: { port }
• Account: { system_id }
• Password: { password }

Verbindungsaufbau

Client-Paket

Nach dem Aufbau der TCP-Verbindung muss das erste Paket zur Authentifizierung den Befehl BindTransceiver (0x00000009) senden. Dieses Paket muss die folgenden Felder enthalten:

• system_id: Das dem Client zugewiesene Systemkonto, das zur Identifizierung des Clients verwendet wird.
• password: Das dem Systemkonto zugeordnete Zugriffspasswort, das zur Authentifizierung verwendet wird.

Serverantwort

Erfolgreiche Antwort

• Der Server gibt den Befehl BindTransceiverResp (0x80000009) zurück.
• Das Feld system_id wird mit demselben Wert gefüllt wie das empfangene Feld system_id.

Fehlgeschlagene Antwort

• Wenn die Authentifizierung fehlschlägt, trennt der Server die TCP-Verbindung und protokolliert den Grund für den Fehler.

Nachrichtenversand

Serverlogik

Für den Nachrichtenversand wird der Befehl SUBMIT_SM (0x00000004) verwendet, um eine Anfrage zur Nachrichtenzustellung zu übermitteln. Die Serverlogik ist wie folgt:

1. Der Server analysiert den Anfrageinhalt und verwendet für die Zustellung immer den SMS-Kanal.
2. Die Nachrichtenzustellung erfolgt synchron, und das Ergebnis wird über den Befehl SUBMIT_SM_RESP (0x80000004) zurückgegeben.
3. Der Zustellstatus wird über Zustellberichte gemeldet. Weitere Informationen finden Sie unter Zustellberichte.
4. Es wird empfohlen, die Codierung UCS2 zu verwenden, um Sonderzeichen und Internationalisierung zu unterstützen.

Client-Paket

Der Client sendet den Befehl SUBMIT_SM (0x00000004), um eine Nachricht zu übermitteln. Das Paket muss die folgenden Felder enthalten:

1. service_type

   • Wert: MSG / CODE / MRKT
   • Standardwert: MSG

2. source_addr

   • Kann leer gelassen werden und wird derzeit in OTP nicht verwendet.

3. destination_addr

   • Das Nachrichtenziel, das im internationalen Mobilfunknummernformat angegeben werden muss (zum Beispiel +6598765432).

4. short_message

   • Der Nachrichteninhalt verwendet das JSON-Format, wie unten gezeigt:
     { "id": "xxx", // Vorlagen-ID "language": "default", // Verwendete Sprache; Standard ist default "code": "xx", // Bestätigungscode; wird nur verwendet, wenn service_type CODE ist "params": { // Benutzerdefinierte Schlüssel-Wert-Paare "key1": "val1" // val muss im String-Format vorliegen } }

                   
                   {
       "id": "xxx",           // Vorlagen-ID
       "language": "default", // Verwendete Sprache; Standard ist default
       "code": "xx",          // Bestätigungscode; wird nur verwendet, wenn service_type CODE ist
       "params": {            // Benutzerdefinierte Schlüssel-Wert-Paare
         "key1": "val1"       // val muss im String-Format vorliegen
       }
     }
     
                 

     Diesen Codeblock im schwebenden Fenster anzeigen

5. data_coding

   • Es wird empfohlen, die Codierung UCS2 zu verwenden, um sicherzustellen, dass Sonderzeichen wie {} korrekt verarbeitet werden.
   • Wenn die direkte Übertragung von {} unterstützt wird, kann die Standardcodierung verwendet werden (0x00).

6. status im Header

   • Auf 0x00000000 setzen.

Serverantwort

Der Server sendet den Befehl SUBMIT_SM_RESP (0x80000004) als Antwort auf das Ergebnis der Nachrichtenzustellung.

Erfolgreiche Antwort

• Wert des status-Felds im Header: 0x00000000
• MESSAGE_ID-Feld: Die Antwort-Nachrichten-ID, die zur Zuordnung von Zustellberichten verwendet wird.

Fehlgeschlagene Antwort

• Der Server füllt das status-Feld im Header aus, um den Grund für den Fehler anzugeben:

Zustellberichte

Der Server meldet den Zustellstatus über den Befehl DELIVER_SM (0x00000005). Die relevanten Felder sind wie folgt:

1. service_type

   • Fester Wert: MSG

2. source_addr

   • Leer lassen.

3. destination_addr

   • Identisch mit destination_addr im Befehl SUBMIT_SM.

4. data_coding

   • Codierungsmethode: Standardwert 0x00.

5. esm_class

   • Auf 0x00 setzen.

6. short_message

   • Der Zustellbericht wird im Format delivery receipt verpackt.

7. ReceiptedMessageID in TLV

   • Nachrichten-ID, verwendet zur Zuordnung und Identifizierung.

8. MessageState in TLV

   • Nachrichtenstatus, Feldwert 0x0427.

Statusanalyse

Im Feld short_message sind die Bedeutungen der stat-Werte wie folgt:

Weitere Hinweise

Ungültige Befehle

Für ungültige, vom Client übermittelte Befehle gibt der Server den Befehl GENERIC_NACK (0x80000000) zurück und protokolliert die entsprechenden Logs. Der Server unterstützt nur die folgenden Befehle:

1. EnquireLink-Befehl (0x00000015)
2. Unbind-Befehl (0x00000006)
3. SubmitSM-Befehl (0x00000004)
4. DeliverSMResp-Befehl (0x80000005)
5. BindTransceiver-Befehl (0x00000009)

Keepalive

Der Client muss alle 30 Sekunden (Toleranz: ±5 Sekunden) den Befehl EnquireLink (0x00000015) senden, um sicherzustellen, dass die Verbindung aktiv bleibt.

Bedeutung des Sendestatus

Terminologie

• SMPP: Short Message Peer-to-Peer Protocol, verwendet für den Nachrichtenaustausch mit SMS-Gateways.
• SUBMIT_SM: Der SMPP-Befehl zum Übermitteln von SMS-Nachrichten.
• DELIVER_SM: Der vom Server verwendete SMPP-Befehl zur Meldung des Nachrichtenzustellstatus.

Wenn Sie Fragen haben, wenden Sie sich bitte an den OTP Technical Support.