How you can read delivery reports in the SMS Gateway

On this page you can find detailed information on how you can enable a function in Ozeki NG SMS Gateway that will allow you to read delivery reports coming from the the SMS center. Please follow the instructions to enable this function properly.

Introduction

If you sent out an SMS message from a mobile device or an application, Ozeki NG SMS Gateway will forward it to the mobile network either with GSM modem connection or IP SMS connection. In the first case, there is one or more GSM modem attached to the PC with a datacable. IP SMS connection means that the SMS gateway connects directly to the SMS center (SMSC) of the mobile service provider over the Internet.

Delivery reports are messages that show the exact status of your sent messages. In this way you can receive delivery reports when the message arrives at the SMSC (SMS center of a mobile service provider). This is called "Delivered to network" status. Or there is a "Delivered to handset" report when the message is received on the mobile device of the recipient. This guide provides instructions on how you can enable the function that allows you to read delivery reports about the fact that your sent message has been forwarded to the mobile phone of the recipient.

Configuration guide

First log into Ozeki NG SMS Gateway with your username and password. Go to "Edit" menu and click on "Server preferences" menu item (Figure 1).

On "Advanced" tab enable "Copy delivery reports for users" option (Figure 2).

Click on "Compose" icon in the "Toolbar" (Figure 3).

Figure 1 - Compose icon

Compose a text message. You need to provide the recipient phone number and the message text (Figure 4).

compose a message — Figure 1 - Compose a message

If you send out the message you can see a notification about the delivery: "Message delivery is acknowledged by returned delivery reports" (Figure 5).

In "Inbox" folder of the user you can see the delivery report (Figure 6).

delivery report in inbox — Figure 6 - Delivery report in Inbox folder

Dig deeper!
People who read this also read...

FAQs

What is a delivery report?

While submitting an SMS message to the network (SMSC) generates a confirmation report (containing a message reference ID), this only signifies the SMSC's acceptance for delivery. It doesn't guarantee the message reached the recipient's phone.

The Crucial Delivery Report:
The true confirmation of successful message delivery comes in the form of a delivery report. This is a separate SMS message sent back to the sender by the network after the message has been delivered to the recipient's handset.

What the Delivery Report Contains:

Recipient Phone Number: This confirms who received the message.
Message Reference ID: This ID, originally returned in the submission report, helps match the delivery notification to the specific message sent.
Delivery Timestamp: This indicates the exact time the recipient's phone received the message.

Key Points to Remember:

Delivery reports provide a more accurate confirmation of message arrival compared to submission reports.
The delivery process can be delayed if the recipient's phone is switched off. Delivery can occur once the phone is back online, potentially taking days.

In essence, when discussing delivery reports, we primarily refer to the SMS message sent back to the sender confirming the successful delivery of the original message to the recipient's phone.

Why are my delivery reports dropped?

Your SMS gateway relies on a system to match incoming delivery reports with the messages they confirm. When this matching fails, the delivery reports get dropped.

Here's how it works:

Reference ID: The Key Link: When your gateway sends a message, it receives a unique reference ID from the SMSC (message center) in a confirmation report. This ID acts like a code for that specific message.
Delivery Report Match: Ideally, any incoming delivery report should have the same reference ID received earlier. This helps the gateway connect the report to the right message.
The Dropped Report Problem: Sometimes, delivery reports get dropped. This happens when the reference ID in the report doesn't match any message stored in the gateway's system.

Why the Match Fails: There are four main reasons why the reference ID might not match:

SMSC Inconsistency: In some cases, the SMSC might not always return the exact same reference ID used in the initial confirmation report. Even a single character difference can cause the gateway to miss the match.
Unreliable Service Provider: Certain service providers might not consistently assign unique reference IDs to all messages. This is an issue on their end.
Message Age Limits: The Ozeki software keeps reference IDs only for a week (configurable limit). Delivery reports for messages older than a week won't be matched because their reference IDs are no longer stored. This is done to maintain database efficiency.
Premature Message Deletion: If you delete the original message from the sent folder before the delivery report arrives, the gateway won't have it to match against. This could happen through manual deletion or automatic deletion settings.

Finding the Cause:

Check the Event Log: Look for the original message in the service provider's connection event log within Ozeki NG. Verify the reference ID there and compare it to the delivery report.
Investigate Service Provider: If inconsistency seems to be from the service provider, consider contacting them for a solution.

Solutions to Consider:

Minimize Deletion: Avoid deleting sent messages before receiving delivery reports.
Extend Reference ID Storage (if possible): If allowed, consider increasing the maximum storage time for reference IDs to match your typical delivery timelines.

By understanding these reasons and potential solutions, you can investigate why your delivery reports are being dropped and take steps to minimize the issue.

What can I see in the delivery report registry GUI?

This section shows a list of messages that haven't received a delivery report yet. It functions like a waiting area for these messages.

Each message stays in the registry for a maximum of one week. If a delivery report doesn't arrive within that time, the message is removed.

Can I change the time setting after which messages that got no delivery report are removed from the list?

Unfortunately, no. The one-week removal period is a fixed setting.

How can I reset the delivery report registry queue?

There isn't a direct way to clear the queue. However, if you delete the messages from your "sent items" folder, they'll also be removed from the delivery report registry.

The delivery report (onMessageDeliveryFailed) is retrieved for every failed attempt or is just retrieved when the max number of tries is reached?

You won't receive a delivery report for every single attempt to send a message that fails. The system waits until the maximum number of retries is reached before retrieving and sending you a "delivery failed" notification (onMessageDeliveryFailed).

Is it possible to store the incoming SMS delivery reports into SQL?

Yes, you can store incoming delivery reports in an SQL database for easy access and record keeping. Here's what you need to do:

Access Settings: Open the "Edit/Server preferences" menu.
Activate Storage: Click on the "Advanced" tab and check the box labeled "Copy delivery reports for users."
Database Integration (if applicable): If you're already using an SQL to SMS gateway configuration, incoming delivery reports will automatically be treated as standard incoming messages and saved in your database.

If you're sending messages from the "ozekimessageout" table within your SQL database (with an SQL to SMS gateway), the system automatically keeps track of message delivery status by updating a "status" field in the table. Here's what the updates might look like:

deliveredtonetwork: Message successfully entered the network.
deliveredtohandset: Message successfully reached the recipient's phone.
deliveryerror: There was a problem delivering the message.

If I send SMS from a GSM modem, the GSM protocol allows a max. number of 256 callback id's for delivery reports. How do you distinguish delivery reports that have the same id?

The Ozeki software ensures accurate matching between messages and their delivery reports. Here's what happens:

GSM Modems and Limited IDs: When using a GSM modem, the network assigns a reference ID (0-255) to each message. Delivery reports reference this ID to link back to the original message.
The Challenge of Duplicates: With more than 256 messages sent, some IDs can be reused, causing confusion (e.g., two messages might have ID "0").
Ozeki's Solution: Combining Information: To overcome this, Ozeki creates a unique "callback ID" by combining the recipient's phone number with the reference ID.
Example: Instead of just "0," the callback ID becomes "+36201234567:0" (phone number + reference ID). This extra detail allows for a much more precise match between delivery reports and their corresponding messages.

IP SMS to the Rescue:

IP SMS connections don't face this issue. They utilize a much longer and globally unique identifier (GUID), eliminating the possibility of duplicate IDs.

Delivery reports are coming in as SMS messages to my system. When I configure my connection for sending only, will it dismiss my delivery reports?

No, configuring your connection for sending only will not dismiss your delivery reports. These reports are separate SMS messages sent by the network to confirm message delivery. Even if you only configure sending, your system should still be able to receive incoming messages, including delivery reports.

How does the inbound routing table effect the incoming delivery reports?

The inbound routing table generally does not affect incoming delivery reports. This table is typically used to direct incoming SMS messages (from users) to specific applications or processes within your system based on pre-defined rules. Delivery reports, however, are system messages related to previously sent messages and wouldn't be routed based on content.

Here's a breakdown of how they differ:

Inbound SMS (from users): These are messages initiated by people sending SMS to your system.
Delivery Reports: These are system-generated messages sent by the network to confirm the delivery status of messages you previously sent.

Since delivery reports are system messages related to outgoing traffic, they wouldn't be routed like user-initiated SMS messages.

However, there's a possibility:

Some systems might allow advanced configuration where even delivery reports can be routed based on specific criteria (e.g., sender phone number or reference ID). But this wouldn't be the default behavior of an inbound routing table.