Multi-segment SMS Status Handling
Long SMS messages are automatically split into multiple segments by carrier networks and then reassembled on the recipient’s device so the full text appears as a single message. This document explains how the Messages API handles delivery receipts (DLRs) for multi-segment SMS and how this affects status callbacks.
Multi-segment SMS introduces complexity because each segment is delivered independently over the carrier network. In most cases, all segments arrive successfully within a short time window, but partial failures can occur.
To provide delivery reporting, the Messages API aggregates delivery receipts for all segments before sending a final status callback.
The logic is:
- The API waits up to 5 minutes after receiving the first segment’s delivery receipt.
- During this window, it collects delivery receipts for all segments.
- A single aggregated status callback is sent with a breakdown of each segment’s outcome.
A message is marked as rejected if either of the following occurs:
- At least one segment is rejected.
- Not all segments are confirmed as delivered within 5 minutes of the first delivery receipt.
Aggregated Status Callbacks
Status callbacks for multi-segment SMS represent the outcome of the entire message, not just the first segment received. This ensures that the reported status reflects whether the full message was successfully delivered to the end user.
Aggregated status callbacks provide:
- A single unified callback for the message.
- A segment-level breakdown of delivery results.
- More accurate delivered and rejected statuses for long messages.
Example of status callback
{
"message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
"to": "447700900000",
"from": "447700900001",
"timestamp": "2025-02-03T12:14:25Z",
"status": "delivered",
"channel": "sms",
"destination": {
"network_code": "12345"
},
"sms": {
"total_count": "2",
"segments": [
{
"timestamp": "2025-02-03T12:14:25Z",
"status": "delivered"
},
{
"timestamp": "2025-02-03T12:14:58Z",
"status": "delivered"
}
]
}
}