How to Receive SMS Using the SMPP API

The Short Message Peer-to-Peer (SMPP) protocol is a powerful, industry-standard protocol designed to facilitate the exchange of SMS messages between External Short Message Entities (ESMEs) and Short Message Service Centers (SMSCs). For developers and businesses leveraging the SMPP API with Ozeki SMS Gateway as their primary platform, understanding the protocol's low-level operations is essential for building robust SMS solutions. This article provides a comprehensive guide on how to receive SMS messages using the SMPP API, focusing on the protocol-level interactions and the specific Protocol Data Units (PDUs) involved in setting up, maintaining, and utilizing an SMPP API client connection with Ozeki SMS Gateway.

Introduction to the SMPP API and Ozeki SMS Gateway

The SMPP API is widely used in the telecommunications industry for its efficiency in handling bulk SMS messaging over TCP/IP connections. Ozeki SMS Gateway, a versatile SMPP software, serves as both an SMPP client and server, making it an ideal platform for sending and receiving SMS messages. By implementing the SMPP protocol (versions 3.3 and 3.4, with support for 5.0 in Ozeki 10 SMS Gateway), Ozeki enables seamless connectivity with SMSCs, supporting applications such as marketing campaigns, two-factor authentication, and notification systems. This article focuses on receiving SMS messages, detailing the SMPP PDUs required for connection setup, maintenance, and message reception.

Understanding SMPP PDUs

SMPP operates by exchanging Protocol Data Units (PDUs) between the SMPP client (e.g., Ozeki SMS Gateway) and the SMPP server (e.g., an SMSC). Each PDU is a structured message that carries specific instructions or data, such as authentication credentials, SMS content, or connection status queries. To receive SMS messages using the SMPP API, the client must establish a connection, maintain it, and process incoming messages. The key PDUs involved are:

• bind_transceiver: Establishes a connection for both sending and receiving SMS.
• enquire_link: Maintains the connection by checking its status.
• deliver_sm: Delivers incoming SMS messages from the SMSC to the client.
• unbind: Terminates the SMPP session.

Below, we’ll explore each PDU in detail, including their structure, configuration in Ozeki SMS Gateway, and their role in receiving SMS messages via the SMPP API.

Setting Up an SMPP API Client Connection

To receive SMS messages, the first step is to establish a stable SMPP API client connection with the SMSC. Ozeki SMS Gateway simplifies this process with its intuitive interface, but understanding the underlying protocol-level operations is crucial for advanced users.

1. Configuring the SMPP Client in Ozeki SMS Gateway

To set up an SMPP API client connection in Ozeki SMS Gateway, follow these steps:

1. Log in to the Management Console: Access the Ozeki SMS Gateway web interface using the administrator account (default username: "admin").
2. Add a New Connection: Navigate to the "Connections" panel, click "Add new connection," and select "SMPP client" from the "IP SMS Connections" section.
3. Configure SMPP Settings: Provide the following details, typically supplied by your SMS service provider:
   • Host Name: The IP address or hostname of the SMSC (e.g., "192.168.1.1").
   • Port Number: The TCP/IP port for SMPP communication (default is 9500, but confirm with your provider).
   • Username (System ID): Your account identifier for the SMSC.
   • Password: The password associated with the System ID.
   • SMPP Version: Select v3.4 for transceiver support (recommended for sending and receiving).
   • System Type: Optional, often "SMPP," as specified by the provider.
   • Sender Address: The default phone number for outbound SMS (e.g., "+1234567890").
   • Address Range: Optional, used for receiving messages from multiple numbers.
4. Bind Mode: Choose "Transceiver" to enable both sending and receiving SMS over a single connection.
5. Advanced Settings: Enable "Connect automatically on startup" for seamless reconnection and check "Send keepalive packets" to maintain the connection.
6. Enable Logging: In the "Advanced" tab, enable "Log Communication Events" to capture SMPP PDUs for debugging.
7. Save and Connect: Click "OK" to save the configuration, then click "Connect" to initiate the connection.

These settings prepare Ozeki SMS Gateway to establish an SMPP API connection using the bind_transceiver PDU.

2. The bind_transceiver PDU

The bind_transceiver PDU is the first PDU sent by the SMPP client to authenticate and establish a connection with the SMSC. It enables both sending and receiving SMS messages over a single TCP/IP connection, making it ideal for most SMPP API applications.

Structure of bind_transceiver PDU

Command Length: 4 bytes (total length of the PDU)
Command ID: 0x00000009 (bind_transceiver)
Command Status: 0x00000000 (set to 0 for requests)
Sequence Number: Unique identifier for the PDU
System ID: Username for authentication (e.g., "smppuser")
Password: Password for authentication (e.g., "password123")
System Type: Optional, often "SMPP"
Interface Version: SMPP version (e.g., 0x34 for v3.4)
Address Range: Optional, for receiving messages from specific numbers

Example bind_transceiver PDU (hexadecimal):

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

Explanation:

• Command Length (0000002F): Total length of the PDU (47 bytes).
• Command ID (00000009): Identifies the PDU as bind_transceiver.
• Command Status (00000000): Set to 0 for the request.
• Sequence Number (00000001): A unique ID to track the PDU.
• System ID (736D70707573657200): ASCII for "smppuser" followed by a null terminator.
• Password (70617373776F726431323300): ASCII for "password123" followed by a null terminator.
• System Type (534D505000): ASCII for "SMPP" followed by a null terminator.
• Interface Version (34): Indicates SMPP v3.4.
• Address Range (00): Null, as it’s optional.

Upon receiving the bind_transceiver PDU, the SMSC validates the credentials. If successful, it responds with a bind_transceiver_resp PDU with a command status of 0x00000000, indicating a successful connection. Ozeki SMS Gateway logs this interaction, which can be viewed in the "Communication Events" log.

Maintaining the SMPP API Connection

Once the connection is established, it must be kept alive to ensure continuous SMS reception. The SMPP protocol uses the enquire_link PDU to verify the connection’s status and prevent disconnection due to inactivity.

The enquire_link PDU

The enquire_link PDU is a lightweight message sent periodically by the SMPP client to the SMSC to confirm that the connection is active. This is particularly important for maintaining long-lived connections, as proxy servers or SMSCs may terminate idle connections.

Structure of enquire_link PDU

Command Length: 0x00000010 (16 bytes)
Command ID: 0x00000015 (enquire_link)
Command Status: 0x00000000 (set to 0 for requests)
Sequence Number: Unique identifier for the PDU

Example enquire_link PDU (hexadecimal):

00000010 00000015 00000000 00000002

Explanation:

• Command Length (00000010): Total length (16 bytes).
• Command ID (00000015): Identifies the PDU as enquire_link.
• Command Status (00000000): Set to 0 for the request.
• Sequence Number (00000002): A unique ID to track the PDU.

The SMSC responds with an enquire_link_resp PDU, confirming the connection’s status. In Ozeki SMS Gateway, enabling the "Send keepalive packets" option in the "Communication" tab ensures that enquire_link PDUs are sent automatically at regular intervals (e.g., every 30 seconds). This setting is critical for maintaining a stable SMPP API connection, especially when receiving SMS messages intermittently.

Receiving SMS Messages with the SMPP API

Once the connection is established and maintained, the SMPP API client can receive SMS messages via the deliver_sm PDU. This PDU is sent by the SMSC to the client when an incoming SMS or delivery report is available.

The deliver_sm PDU

The deliver_sm PDU carries the content of an incoming SMS message or a delivery report. For receiving SMS, the PDU contains the sender’s phone number, recipient’s number (virtual number assigned by the provider), and the message text.

Structure of deliver_sm PDU

Command Length: Variable (depends on message length)
Command ID: 0x00000005 (deliver_sm)
Command Status: 0x00000000 (set to 0 for requests)
Sequence Number: Unique identifier for the PDU
Service Type: Optional, often null
Source Address TON: Type of Number for the sender
Source Address NPI: Numbering Plan Indicator for the sender
Source Address: Sender’s phone number (e.g., "+1234567890")
Destination Address TON: Type of Number for the recipient
Destination Address NPI: Numbering Plan Indicator for the recipient
Destination Address: Recipient’s phone number (e.g., virtual number)
ESM Class: Message type (e.g., 0x04 for SMS)
Data Coding: Character encoding (e.g., 0x00 for GSM 7-bit)
Short Message: The message text (up to 160 characters for GSM)

Example deliver_sm PDU (hexadecimal):

0000005F 00000005 00000000 00000003 00 01 01 2B3132333435363738393000 01 01 2B3938373635343332313000 00 00 00 00 00 48656C6C6F2C207468697320697320616E20534D5321

Explanation:

• Command Length (0000005F): Total length (95 bytes).
• Command ID (00000005): Identifies the PDU as deliver_sm.
• Command Status (00000000): Set to 0 for the request.
• Sequence Number (00000003): A unique ID to track the PDU.
• Service Type (00): Null, as it’s optional.
• Source Address TON (01): International number.
• Source Address NPI (01): ISDN/telephone numbering plan.
• Source Address (2B3132333435363738393000): ASCII for "+1234567890".
• Destination Address TON (01): International number.
• Destination Address NPI (01): ISDN/telephone numbering plan.
• Destination Address (2B3938373635343332313000): ASCII for "+9876543210".
• ESM Class (00): Indicates a standard SMS.
• Data Coding (00): GSM 7-bit encoding.
• Short Message (48656C6C6F2C207468697320697320616E20534D5321): ASCII for "Hello, this is an SMS!".

Upon receiving a deliver_sm PDU, Ozeki SMS Gateway processes the message and routes it to the configured application or database. The client must respond with a deliver_sm_resp PDU to acknowledge receipt, ensuring reliable delivery. In Ozeki, this response is handled automatically, and the message is logged in the "Messages" panel or stored in the database if configured.

Configuring Ozeki SMS Gateway for SMS Reception

To ensure Ozeki SMS Gateway can receive SMS messages:

1. Virtual Number Setup: Collaborate with your SMS service provider to assign a virtual number (IMSI) for receiving SMS. This number is specified in the "Address Range" field during configuration.
2. Database Integration: Configure Ozeki to store incoming messages in a database by modifying the SQL SELECT statement in the "Database user" configuration (e.g., "SELECT id, sender, receiver, msg, msgtype FROM ozekimessagein").
3. Logging: Enable SMPP PDU logging to monitor incoming deliver_sm PDUs for debugging purposes.

Once configured, incoming SMS messages are automatically routed to the specified application or database, making Ozeki SMS Gateway a robust platform for SMPP API-based SMS reception.

Terminating the SMPP API Connection

When the SMPP API session is no longer needed, the client sends an unbind PDU to gracefully terminate the connection.

The unbind PDU

The unbind PDU signals the SMSC to close the SMPP session.

Structure of unbind PDU

Command Length: 0x00000010 (16 bytes)
Command ID: 0x00000006 (unbind)
Command Status: 0x00000000 (set to 0 for requests)
Sequence Number: Unique identifier for the PDU

Example unbind PDU (hexadecimal):

00000010 00000006 00000000 00000004

Explanation:

• Command Length (00000010): Total length (16 bytes).
• Command ID (00000006): Identifies the PDU as unbind.
• Command Status (00000000): Set to 0 for the request.
• Sequence Number (00000004): A unique ID to track the PDU.

The SMSC responds with an unbind_resp PDU, confirming the session’s termination. In Ozeki SMS Gateway, you can initiate this by clicking "Disconnect" in the "Connections" panel.

Best Practices for SMPP API Users

To optimize your SMPP API implementation with Ozeki SMS Gateway for receiving SMS:

• Enable Keepalive Packets: Ensure the "Send keepalive packets" option is enabled to maintain a stable connection.
• Monitor Logs: Regularly check SMPP PDU logs to troubleshoot issues with bind_transceiver, enquire_link, or deliver_sm PDUs.
• Use Transceiver Mode: Prefer transceiver mode for efficiency, as it supports both sending and receiving over a single connection.
• Secure Connections: If supported by your provider, use SMPPS (SMPP over SSL/TLS) for encrypted communication.
• Handle Delivery Reports: Configure Ozeki to process deliver_sm PDUs containing delivery reports to track message status.

Conclusion

Receiving SMS messages using the SMPP API with Ozeki SMS Gateway involves establishing a connection with the bind_transceiver PDU, maintaining it with enquire_link PDUs, and processing incoming messages via deliver_sm PDUs. By understanding these PDUs and configuring Ozeki SMS Gateway appropriately, developers can build reliable, high-performance SMS applications. The SMPP API’s flexibility and Ozeki’s robust implementation make it an excellent choice for businesses requiring scalable SMS solutions. For further details, refer to the Ozeki SMS Gateway documentation or contact your SMS service provider for specific configuration parameters.