SMPP

This protocol defines the SMPP communication protocol for the EngageLab SMS service, aiming to achieve efficient and reliable message delivery and status reporting via TCP connection. Interface information includes IP address, port number, and authentication details required for connection. Please make sure to configure it correctly using the account and password provided by authorized channels.

SMPP Address

otpsmpp.api.engagelab.cc

Please obtain the following information from authorized channels (such as business or technical support):

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

Establishing Connection

Client Packet

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

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

Server Response

Success Response

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

Failure Response

• If authentication fails, the server will disconnect the TCP connection and log 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 securely uses the SMS channel for delivery.
2. Message delivery is synchronous, and the result will be responded with a SUBMIT_SM_RESP command (i.e., 0x80000004).
3. Delivery status will be reported via messages, see Delivery Report for details.
4. It is recommended to use UCS2 encoding to support special characters and internationalization.

Client Packet

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

1. service_type
   • Values: MSG / CODE / MRKT
   • Default: MSG
2. source_addr
   • Can be left empty, currently unused in SMS.
3. destination_addr
   • Message target, must be in international mobile number format (e.g., +6598765432).
4. short_message
   • Message content, using JSON format, structured as follows:
     { "id": "xxx", // Template ID "language": "default", // Used language, 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", // Used language, 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
   • Recommended to use UCS2 encoding to ensure special character {} is parsed normally.
   • If direct sending of {} is supported, default encoding (0x00) can be used.
6. status in header
   • Set to 0x00000000.

Server Response

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

Success Response

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

Failure Response

• The server populates the status field in header providing the failure reason:

Delivery Report

The server reports delivery status via the DELIVER_SM command (i.e., 0x00000005). Specific fields are as follows:

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

Status Resolution

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

Additional Information

Invalid Commands

For invalid commands submitted by the client, the server will return a GENERIC_NACK command (i.e., 0x80000000) and log it. 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 remains active.

Sending Status Meanings

Terminology Explanation

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