How to Send SMS Using the SMPP API at the Protocol Level

The Short Message Peer-to-Peer (SMPP) API is a widely adopted protocol for exchanging SMS messages between SMS entities like ESMEs (External Short Message Entities) and SMSCs (Short Message Service Centers). For users of the Ozeki SMS Gateway platform, understanding SMPP protocol-level interactions is critical for optimizing performance, debugging, and custom integrations. This guide explains the SMPP PDUs (Protocol Data Units) required to establish, maintain, and use an SMPP API connection to send SMS messages.

Establishing an SMPP API Connection

To send SMS via SMPP API, you must first bind your client to the Ozeki SMS Gateway server. Three binding types exist: bind_transmitter, bind_receiver, and bind_transceiver. Each defines the direction of message flow.

Key PDUs for Connection Setup

PDU Direction Purpose Key Parameters
bind_transmitter ESME → SMSC Initiates a connection for sending SMS
  • system_id: Client username
  • password: Authentication credential
  • system_type: Identifier for the ESME
bind_receiver ESME → SMSC Sets up a connection for receiving SMS Same as bind_transmitter
bind_transceiver ESME → SMSC Enables bidirectional messaging Same as bind_transmitter

Upon successful binding, the Ozeki gateway responds with a bind_resp PDU containing a system_id acknowledgment. If authentication fails, it returns an error code like ESME_RINVPASWD.

Maintaining the SMPP API Connection

SMPP connections require periodic keep-alive signals to prevent timeout. Use the enquire_link PDU:

PDU Direction Purpose
enquire_link ESME ↔ SMSC Checks if the connection is active
enquire_link_resp ESME ↔ SMSC Confirms liveliness

Best Practice: Send enquire_link every 30-60 seconds. Ozeki SMS Gateway terminates idle connections after 5 minutes by default.

Sending an SMS via SMPP API

The submit_sm PDU is used to send a single SMS. Its structure includes source/destination addresses and message content:

Parameter Description Example
service_type Type of service (optional) “” (empty)
source_addr SMS sender address “12345”
destination_addr Recipient phone number “+1234567890”
short_message Message payload (UTF-8 or GSM-7) “Hello World”

Example submit_sm Workflow

  1. ESME sends submit_sm to Ozeki SMS Gateway.
  2. Gateway responds with submit_sm_resp containing a message_id.
  3. Gateway sends deliver_sm for delivery reports (if enabled).
  4. ESME replies with deliver_sm_resp.

Handling SMPP API Responses and Errors

Ozeki SMS Gateway uses these response PDUs:

PDU Purpose Critical Fields
submit_sm_resp Acknowledges submit_sm message_id, command_status
generic_nack Indicates malformed/invalid PDU command_status (e.g., ESME_RINVMSGLEN)

Conclusion

Mastering SMPP API PDUs like bind_transmitter, enquire_link, and submit_sm ensures reliable SMS messaging through Ozeki SMS Gateway. By implementing robust error handling and keep-alive routines, developers can build scalable SMS solutions with minimal downtime.

More information