SMPP Interface

Interface Information

This protocol defines the SMPP communication protocol for the EngageLab OTP service, aiming to achieve efficient and reliable message delivery and status reporting through TCP connections. The interface information includes the IP address, port number, and authentication information required for connection. Please ensure correct configuration according to the account and password provided by the authorized channel.

SMPP Address

SMPP address: otpsmpp.api.engagelab.cc Please obtain the following information from an authorized channel (such as business or technical support):

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

Establish Connection

Client Packet

After establishing a TCP connection, the first packet needs to send the BindTransceiver command (i.e., 0x00000009) for authentication verification. This packet needs to contain the following fields:

• system_id: The system account assigned to the customer, used to identify the identity.
• password: The access password corresponding to the system account, used for identity authentication.

Server Response

Success Response

• The server will send a BindTransceiverResp command (i.e., 0x80000009) response.
• Fill the system_id field with a value consistent with the received system_id field.

Failure Response

• If authentication fails, the server will disconnect the TCP connection and record the reason for failure.

Message Sending

Server Logic

Message sending uses the SUBMIT_SM command (i.e., 0x00000004) to submit message delivery requests. The server logic is as follows:

1. The server parses the request content and fixedly uses the SMS channel for delivery.
2. Message delivery is in synchronous mode, and the result will be responded with the SUBMIT_SM_RESP command (i.e., 0x80000004).
3. Delivery status will be reported via messages, please refer to Delivery Report for details.
4. It is recommended to use UCS2 encoding to support special characters and internationalization.

Client Packet

The client sends the SUBMIT_SM command (i.e., 0x00000004) to submit a message, which must contain the following fields:

1. service_type
   • Values: MSG / CODE / MRKT
   • Default value: MSG
2. source_addr
   • Can be left empty, currently not used in OTP.
3. destination_addr
   • Message target, must be in international mobile number format (e.g., +6598765432).
4. short_message
   • Message content, in JSON format, as follows:
     { "id": "xxx", // Template ID "language": "default", // Language used, default is default "code": "xx", // Verification code, used only when service_type is code "params": { // Custom key-value pairs "key1": "val1" // val format is string } }

                   
                   {
       "id": "xxx",          // Template ID
       "language": "default", // Language used, default is default
       "code": "xx",          // Verification code, used only when service_type is code
       "params": {            // Custom key-value pairs
         "key1": "val1"       // val format is string
       }
     }
     
                 

     This code block in the floating window
5. data_coding
   • It is recommended to use UCS2 encoding to ensure special characters {} are parsed normally.
   • If direct sending of {} is supported, the default encoding (i.e., 0x00) can be used.
6. status in header
   • Set to 0x00000000.

Server Response

The server sends the SUBMIT_SM_RESP command (i.e., 0x80000004) to respond to the message delivery result.

Success Response

• status field value in header: 0x00000000
• MESSAGE_ID field: Response message ID, used to associate the delivery report.

Failure Response

• The server fills the status field in header to provide the reason for failure:

Delivery Report

The server reports the delivery report through the DELIVER_SM command (i.e., 0x00000005). The specific fields are as follows:

1. service_type
   • Fixed value: MSG
2. source_addr
   • Leave empty.
3. destination_addr
   • Consistent with destination_addr in the SUBMIT_SM command.
4. data_coding
   • Encoding method: default value 0x00.
5. esm_class
   • Set to 0x00.
6. short_message
   • Encapsulate the delivery report in delivery receipt format.
7. ReceiptedMessageID in tlv
   • Message ID, used for association identification.
8. MessageState in tlv
   • Message status, field value 0x0427.

Status Parsing

In the short_message field, the meaning of the stat value is as follows:

Other Instructions

Invalid Commands

For invalid commands submitted by the client, the server will return the GENERIC_NACK command (i.e., 0x80000000) and record relevant logs. The server only supports the following commands:

1. EnquireLink command (i.e., 0x00000015)
2. Unbind command (i.e., 0x00000006)
3. SubmitSM command (i.e., 0x00000004)
4. DeliverSMResp command (i.e., 0x80000005)
5. BindTransceiver command (i.e., 0x00000009)

Keep Alive

The client needs to send an EnquireLink command (i.e., 0x00000015) every 30 seconds (tolerance ±5 seconds) to ensure the connection is active.

Sending Status Meanings

Terminology

• SMPP: Short Message Peer-to-Peer Protocol, used for message exchange in SMS gateways.
• SUBMIT_SM: SMPP command for submitting SMS messages.
• DELIVER_SM: SMPP command used by the server to report message delivery status.

If you have any questions, please contact OTP Technical Support.