How to Receive SMPP Delivery Reports through the SMPP API

The Short Message Peer-to-Peer (SMPP) protocol is a cornerstone of modern SMS communication, enabling External Short Message Entities (ESMEs) to exchange messages and delivery reports with Short Message Service Centers (SMSCs). For developers using the SMPP API with Ozeki SMS Gateway, understanding how to receive delivery reports is critical for tracking the status of sent SMS messages. This article provides a comprehensive guide on receiving SMPP delivery reports at the protocol level, focusing on the necessary SMPP Protocol Data Units (PDUs) for connection setup, maintenance, and delivery report reception using Ozeki SMS Gateway as the primary SMPP API server platform.

Introduction to SMPP Delivery Reports and Ozeki SMS Gateway

SMPP delivery reports are notifications sent by the SMSC to inform the ESME about the status of a previously sent SMS, such as whether it was delivered, failed, or rejected. These reports are essential for applications requiring confirmation of message delivery, such as transactional notifications or marketing campaigns. Ozeki SMS Gateway, a robust SMPP software supporting versions 3.3, 3.4, and 5.0, simplifies the process of handling SMPP delivery reports through its intuitive interface and powerful configuration options. This article details the SMPP PDUs involved in setting up an SMPP API client connection, maintaining it, and receiving delivery reports, with practical guidance for Ozeki SMS Gateway users.

Understanding SMPP PDUs for Delivery Reports

The SMPP protocol relies on Protocol Data Units (PDUs) to manage communication between the SMPP client (e.g., Ozeki SMS Gateway) and the SMSC. To receive delivery reports, the client must establish a connection, maintain it, and process incoming delivery reports. The key PDUs involved are:

  • bind_transceiver: Establishes a connection for sending and receiving SMS and delivery reports.
  • enquire_link: Maintains the connection to ensure continuous reception of delivery reports.
  • deliver_sm: Delivers incoming delivery reports (and SMS messages) from the SMSC to the client.
  • unbind: Terminates the SMPP session.

Below, we explore each PDU, their structure, and their role in receiving SMPP delivery reports using the SMPP API with Ozeki SMS Gateway.

Setting Up an SMPP API Client Connection

Receiving SMPP delivery reports requires a stable SMPP API client connection to the SMSC. Ozeki SMS Gateway streamlines this process, but understanding the protocol-level operations is essential for advanced users and troubleshooting.

1. Configuring the SMPP Client in Ozeki SMS Gateway

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

  1. Access the Management Console: Log in to the Ozeki SMS Gateway web interface using the administrator account (default username: "admin").
  2. Create a New Connection: In the "Connections" panel, click "Add new connection" and select "SMPP client" from the "IP SMS Connections" section.
  3. Enter SMPP Settings: Provide the following details, typically supplied by your SMS service provider:
    • Host Name: The SMSC’s IP address or hostname (e.g., "192.168.1.1").
    • Port Number: The TCP/IP port for SMPP communication (default is 9500, confirm with your provider).
    • Username (System ID): Your SMSC account identifier (e.g., "smppuser").
    • Password: The password for the System ID (e.g., "password123").
    • SMPP Version: Select v3.4 for transceiver support, which is optimal 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 or reports for specific numbers.
  4. Bind Mode: Select "Transceiver" to enable both sending SMS and receiving delivery reports over a single connection.
  5. Enable Delivery Reports: In the "Advanced" tab, check "Request delivery report" to ensure the SMSC sends delivery reports for sent messages.
  6. Keepalive Settings: Enable "Send keepalive packets" to maintain the connection for continuous report reception.
  7. Enable Logging: In the "Advanced" tab, enable "Log Communication Events" to capture SMPP PDUs for debugging.
  8. Save and Connect: Click "OK" to save, then click "Connect" to initiate the SMPP API connection.

These settings prepare Ozeki SMS Gateway to establish an SMPP API connection using the bind_transceiver PDU, enabling the reception of delivery reports.

2. The bind_transceiver PDU

The bind_transceiver PDU authenticates the SMPP client with the SMSC and establishes a connection for both sending SMS and receiving delivery reports. It’s the first step in enabling SMPP API functionality.

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 or reports

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" with a null terminator.
  • Password (70617373776F726431323300): ASCII for "password123" with a null terminator.
  • System Type (534D505000): ASCII for "SMPP" with a null terminator.
  • Interface Version (34): Indicates SMPP v3.4.
  • Address Range (00): Null, as it’s optional.

The SMSC responds with a bind_transceiver_resp PDU. A command status of 0x00000000 indicates a successful connection. Ozeki SMS Gateway logs this interaction in the "Communication Events" log, which is useful for verifying the connection.

Maintaining the SMPP API Connection

A stable connection is crucial for receiving SMPP delivery reports, as interruptions can result in missed status updates. The enquire_link PDU is used to keep the connection alive.

The enquire_link PDU

The enquire_link PDU is sent periodically by the SMPP client to confirm the connection’s status, preventing disconnection due to inactivity.

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 to confirm the connection’s status. In Ozeki SMS Gateway, enabling "Send keepalive packets" in the "Communication" tab ensures that enquire_link PDUs are sent automatically (e.g., every 30 seconds). This is critical for maintaining a reliable SMPP API connection for delivery report reception.

Receiving SMPP Delivery Reports

SMPP delivery reports are received via the deliver_sm PDU, which the SMSC sends to the client to report the status of a previously sent SMS. The PDU contains details such as the message ID, delivery status, and timestamp.

The deliver_sm PDU for Delivery Reports

The deliver_sm PDU is used for both incoming SMS messages and delivery reports. For delivery reports, the PDU’s ESM Class field is set to indicate a delivery receipt (typically 0x04), and the message content includes a structured report with status information.

Structure of deliver_sm PDU (Delivery Report)

Command Length: Variable (depends on report 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 (SMSC or recipient)
Source Address NPI: Numbering Plan Indicator for the sender
Source Address: Sender’s phone number or SMSC identifier
Destination Address TON: Type of Number for the recipient (ESME)
Destination Address NPI: Numbering Plan Indicator for the recipient
Destination Address: Recipient’s phone number (e.g., ESME’s virtual number)
ESM Class: 0x04 (indicates delivery receipt)
Data Coding: Character encoding (e.g., 0x00 for GSM 7-bit)
Short Message: Delivery report text (e.g., "id:12345 sub:001 dlvrd:001 submit date:2505270415 done date:2505270416 stat:DELIVRD err:000")
Optional Parameters: TLV fields like receipted_message_id and message_state

Example deliver_sm PDU (hexadecimal):

0000007A 00000005 00000000 00000003 00 01 01 2B3938373635343332313000 01 01 2B3132333435363738393000 04 00 00 00 00 69643A3132333435207375623A30303120646C7672643A303031207375626D697420646174653A3235303532373034313520646F6E6520646174653A3235303532373034313620737461743A44454C49565244206572723A303030

Explanation:

  • Command Length (0000007A): Total length (122 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 (2B3938373635343332313000): ASCII for "+9876543210" (recipient’s number).
  • Destination Address TON (01): International number.
  • Destination Address NPI (01): ISDN/telephone numbering plan.
  • Destination Address (2B3132333435363738393000): ASCII for "+1234567890" (ESME’s number).
  • ESM Class (04): Indicates a delivery receipt.
  • Data Coding (00): GSM 7-bit encoding.
  • Short Message: ASCII for "id:12345 sub:001 dlvrd:001 submit date:2505270415 done date:2505270416 stat:DELIVRD err:000".

Delivery Report Fields:

  • id: Message ID assigned by the SMSC (e.g., "12345").
  • sub: Number of recipients (e.g., "001").
  • dlvrd: Number of messages delivered (e.g., "001").
  • submit date: Submission timestamp (e.g., "2505270415" for May 27, 2025, 04:15).
  • done date: Delivery timestamp (e.g., "2505270416").
  • stat: Delivery status (e.g., "DELIVRD" for delivered, "UNDELIV" for undeliverable).
  • err: Error code (e.g., "000" for no error).

The client must respond with a deliver_sm_resp PDU to acknowledge receipt. Ozeki SMS Gateway handles this automatically and routes the delivery report to the configured application or database, logging it in the "Messages" panel.

Configuring Ozeki SMS Gateway for Delivery Report Reception

To ensure Ozeki SMS Gateway processes SMPP delivery reports correctly:

  1. Enable Delivery Reports: In the SMPP client configuration, check "Request delivery report" in the "Advanced" tab to instruct the SMSC to send delivery reports.
  2. Virtual Number Setup: Ensure the SMSC is configured to send delivery reports to the virtual number or address range specified in the SMPP client settings.
  3. Database Integration: Configure Ozeki to store delivery reports in a database by modifying the SQL SELECT statement in the "Database user" configuration (e.g., "SELECT id, sender, receiver, msg, msgtype, status FROM ozekimessagein WHERE msgtype='DLR'").
  4. Logging: Enable SMPP PDU logging to monitor incoming deliver_sm PDUs for debugging.

With these settings, Ozeki SMS Gateway will process and store delivery reports, making them accessible for applications or further analysis.

Terminating the SMPP API Connection

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

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 session termination. In Ozeki SMS Gateway, this can be initiated by clicking "Disconnect" in the "Connections" panel.

Best Practices for SMPP API Delivery Report Handling

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

  • Request Delivery Reports: Always enable the "Request delivery report" option when sending SMS to ensure the SMSC generates reports.
  • Monitor Logs: Use SMPP PDU logs to troubleshoot issues with deliver_sm PDUs, especially for delivery reports.
  • Use Transceiver Mode: Prefer transceiver mode for efficiency, as it supports both sending SMS and receiving delivery reports.
  • Secure Connections: Use SMPPS (SMPP over SSL/TLS) if supported by your provider to ensure secure delivery report transmission.
  • Parse Delivery Reports: Configure applications to parse the deliver_sm PDU’s Short Message field to extract status information (e.g., "DELIVRD" or "UNDELIV") for actionable insights.

Conclusion

Receiving SMPP delivery reports 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 delivery reports via the deliver_sm PDU. By configuring Ozeki SMS Gateway correctly and understanding the underlying SMPP protocol, developers can build reliable systems to track SMS delivery status. The SMPP API’s robustness and Ozeki’s flexible configuration make it an excellent choice for managing delivery reports in high-volume SMS applications. For more details, consult the Ozeki SMS Gateway documentation or contact your SMS service provider for specific configuration requirements.

More information