123eworld Knowledge Hub → Transactional SMS → Page 170
Transactional SMS API Long SMS Handling: Concatenation, UDH, Segmentation, Reassembly and Delivery Tracking
A technical guide to long SMS segmentation, concatenation, UDH, segment identity, provider handling and delivery tracking.
What makes long SMS complex
Long SMS is not one large telecom payload. The application or provider divides it into segments that are delivered and reassembled by the receiving handset or network.
Segmentation
The platform should calculate segment boundaries based on the final encoding. Each segment must retain enough metadata for the receiving system to understand that it belongs to the same logical message.
UDH
Concatenated SMS commonly uses User Data Header information to identify a reference, total segment count and segment sequence. Exact implementation can vary by provider and protocol path.
Logical versus physical identity
The customer should have one logical message ID while the platform and provider may have several segment-level attempts. Billing, delivery and support need a mapping between these identities.
Ordering
Segments need stable sequence numbers. The platform should preserve sequence even if provider submission is asynchronous.
Partial delivery
A long SMS can have mixed segment outcomes. The customer-facing status model must define whether the logical message is delivered only when all segments are successful.
Retries
Retrying one failed segment must not duplicate successfully submitted segments. Segment-level attempt records are therefore important.
Provider handling
Some providers accept the full message and perform segmentation themselves; others expose segment-level behaviour. The platform should hide unnecessary provider differences while retaining evidence internally.
Cost
Long messages can multiply segment count. Segment estimates should be available before sending when practical.
Testing
Test boundary lengths, mixed Unicode content, missing segments, duplicate segments, out-of-order receipts and provider failover.
Production checklist
Define segmentation rules, UDH handling, segment identity, ordering, partial delivery semantics, retry behaviour, provider abstraction and billing.
Developer takeaway
Treat long SMS as one logical customer operation composed of several physical delivery units. That model makes retries, billing and support far safer.
Implementation architecture
Implement long-message processing with one logical message record and explicit segment records when the provider exposes physical segments. Store segment sequence, total count, reference identity and provider attempt ID. If the provider performs concatenation internally, retain the platform's logical segment estimate even if physical segment IDs are unavailable. Delivery aggregation should define whether every segment must succeed before the logical message becomes delivered.
Production checklist
Production check: test missing segments, duplicate segments, out-of-order delivery receipts, provider retries and logical-status aggregation.
Segment identity
A long message should have one logical message ID and a stable concatenation reference for its physical segments where the protocol requires one. Store segment number and total count so support can diagnose missing pieces.
Reassembly
The receiving network or handset may perform reassembly, but the platform should still know whether all expected segments were submitted. This distinction helps explain cases where the platform completed its work but the final handset result is uncertain.
Provider segmentation
When providers perform segmentation, the platform may not control the exact UDH values. In that case, retain provider references and the platform's logical segment estimate rather than inventing segment identifiers.
Partial provider results
If segment 1 is accepted and segment 2 is rejected, the logical status should follow a documented rule. Some platforms may classify the entire message as failed because the complete text cannot be reconstructed.
Retry safety
Retry only the failed physical unit when the provider contract permits it. If the provider accepts only complete-message retries, use the provider's idempotency mechanism or a controlled logical retry strategy.
Cost transparency
Expose estimated segment count before sending when feasible. Long SMS can create unexpected charges when applications insert large dynamic values.
Testing
Boundary testing should include messages exactly at one segment, one character above, and multiple concatenated boundaries.
Final rule
Physical segments are implementation details, but their identities must remain linked to one logical customer message.
Segment references
Concatenated references should be unique enough to avoid collisions within the applicable protocol scope. The platform should not reuse a reference while earlier segments could still be in transit.
Segment retries
A segment retry needs its own provider attempt identity but should remain linked to the same logical message and segment number. This prevents technical retries from appearing as new customer messages.
Receipt aggregation
If segment-level DLRs are available, aggregate them using explicit rules. One failed segment should normally prevent a complete logical delivery status, but the platform may expose partial physical outcomes separately.
Provider fallback
Changing provider for a partially submitted long message is especially risky. The platform must know whether the alternate provider will generate compatible concatenation metadata and whether duplicate segments could result.
Testing reassembly
Test missing final segments, duplicate sequence numbers, wrong total counts and out-of-order receipt events. These cases are difficult to reproduce manually and should be automated.
Cost controls
Long-message limits can protect customers from accidental high segment counts. If a platform supports maximum segment configuration, reject or warn before provider submission.
Closing guidance
Long SMS reliability depends on keeping logical-message state and physical-segment state separate but permanently linked.
Provider capability
Before using a provider for concatenated SMS, validate its support for long-message submission, sender IDs, Unicode and delivery receipts. A provider that accepts text does not necessarily provide identical concatenation behaviour.
Segment timeout
If a logical message's segments are submitted at widely different times, the receiving network may not reassemble them reliably. The platform should minimize unnecessary gaps between segment submissions.
Support tooling
Support should be able to view logical message ID, segment count, submitted segments, failed segments and provider references. This makes long-message incidents diagnosable without inspecting raw protocol traffic.
Operational conclusion
Long-message handling should be tested as a telecom protocol workflow, not merely as a longer version of ordinary SMS submission.
Segment billing
If billing is segment-based, segment count should be calculated before submission and retained with the billing event. Provider reports can then be reconciled against the original estimate rather than recalculated months later.
Segment-level support
Support tools should distinguish a missing segment, failed segment and delayed segment. These states point to different remediation paths.
Final implementation principle
Long-message processing is correct only when segment identity, order, retries, billing and logical status remain connected.
Reference scenario
A 250-character Unicode message becomes several physical segments. Segment two experiences a provider timeout while the other segments are accepted. The platform records the failed segment separately and retries only that physical unit when the provider contract supports safe retry. The logical message remains incomplete until the required segments are successfully accounted for.
Reference scenario conclusion
Segment-level state prevents a single retry from duplicating the entire long message.
Final engineering test
For long SMS, the final engineering test should create a multi-segment message and inject a failure into one segment after the others have been accepted. Verify that the logical message remains incomplete, the failed physical segment can be retried safely and duplicate physical segments are not created. Then replay delivery receipts in a different order and verify that the final logical status remains correct.
Documentation reference
Long-message support should document the maximum logical length and any provider-specific restrictions. Customers need to know whether the platform accepts a large message and segments it automatically or rejects content above a defined limit. Clear limits prevent oversized payloads from becoming unexpected provider failures.
Advanced reference
When a long message crosses a provider boundary, the platform should preserve the same logical message identity even if the provider adapter changes. Support should be able to see which provider handled each segment or complete-message submission. If a provider is replaced, historical records must continue to describe the original routing and segment behaviour. This is essential for billing disputes and delivery investigations because long-message failures often involve several physical attempts that customers experience as one message.
Final reference note
Store the logical-to-segment mapping as durable operational evidence.
Completion rule
Segment retries must preserve logical message identity.
Final quality rule
Keep segment sequence and total count together.
Continue through the 123eworld Knowledge Hub
Explore the complete 123eworld Knowledge Hub for practical SMS API, transactional messaging and developer architecture guides.
Visit 123eworld.com for messaging and digital communication services.