123eworld Knowledge Hub → Transactional SMS API → Page 287
SMS API Concatenated Messages: Multipart SMS, UDH, Segments and Developer Handling
A practical developer reference designed to solve real implementation and production problems around sms api concatenated messages: multipart sms, udh, segments and developer handling.
What concatenated SMS means
A long SMS is usually transmitted as multiple physical segments. Metadata tells the receiving device how to combine them into one displayed message.
Why developers need to care
The API may accept one logical message while the provider bills and transmits several segments. Segment count affects cost, throughput and delivery statistics.
UDH concept
Concatenated messages commonly use a User Data Header containing a reference identifier, total segment count and sequence number. Exact protocol behaviour depends on the downstream network.
Ordering
Segments need consistent sequence information. The platform should generate the multipart structure and avoid exposing low-level UDH construction to ordinary application developers.
Partial delivery
If some segments arrive and others do not, the user may see incomplete content. Delivery reporting should distinguish logical message status from individual segment evidence where provider data supports it.
Retries
Retrying one segment incorrectly can create confusing duplicate or incomplete messages. The logical message should own the retry strategy.
Segment limits
Provider and route limits may differ. Validate the final message against the selected provider's maximum supported segments.
Encoding interaction
Unicode reduces payload capacity, so the same text can require more segments when encoding changes.
Testing
Test two-, three- and multi-part messages, out-of-order segments and partial failures where a simulator is available.
Reporting
Expose logical message count and segment count separately.
Developer abstraction
Application developers should send one logical message. The messaging platform should handle multipart construction and provider-specific fields.
Reference flow
Content → encoding decision → segment calculation → multipart generation → provider submission → segment/receipt correlation → logical status.
Developer implementation principle
Keep the customer-facing API simple. Application developers should submit a logical message and receive stable identifiers and status semantics. Encoding, segmentation, routing and provider-specific transport should be handled by the messaging platform unless an advanced integration explicitly requires lower-level control.
Production reliability
Test the failure path as seriously as the success path. Provider throttling, delayed callbacks, ambiguous timeouts, configuration changes and failover can expose bugs that ordinary send tests never find.
Security and privacy
Avoid placing phone numbers, message content, credentials or authentication values unnecessarily into logs and metrics. Use tenant-aware authorization and stable opaque identifiers for troubleshooting.
Reference architecture
A robust design normally follows: API authentication → validation → logical message creation → encoding/segment calculation → routing → durable queue → provider adapter → delivery evidence → normalized status → reporting/webhook.
Related 123eworld guides
Continue through the 123eworld SMS & WhatsApp Knowledge Hub for related developer architecture, integration and production guides.
How multipart SMS works internally
A long logical SMS is divided into physical segments before submission. Each segment carries information that allows the destination handset to associate it with the same logical message. The exact implementation can use a concatenation reference, total segment count and sequence number. Developers generally should not construct this metadata themselves. The messaging platform should own segmentation because it also controls encoding, provider capabilities, retries and reporting.
Why UDH reduces capacity
Multipart metadata consumes part of the payload, so the number of user-visible characters available per segment is smaller than for a single-segment message. This is why a message can fit in one segment before it crosses the boundary and then require substantially different capacity once it becomes concatenated. The platform's calculator should therefore apply the correct single-versus-multipart capacity rules after encoding is known.
Segment correlation
A logical message ID should map to every physical segment attempt. Provider message IDs may be returned per submission, and delivery receipts may refer to those IDs. Store a clear relationship between logical message, segment number, provider attempt and receipt. This enables the platform to determine whether the entire logical message has sufficient delivery evidence.
Partial and out-of-order delivery
Mobile networks can deliver segments at different times. A handset may temporarily display an incomplete message or wait for missing segments. The messaging platform cannot guarantee handset reassembly behaviour, but it can provide accurate delivery evidence and avoid creating inconsistent retry behaviour. If one segment fails, retrying the entire logical message without reconciliation can create duplicates.
Segment limits and route policy
Some providers or routes may impose maximum segment counts. A platform should validate the selected route before submission. If a message is too long for that route, the API should return a useful error or apply a documented truncation policy only if the customer explicitly requested it. Silent truncation is dangerous for OTPs, financial notifications and URLs.
Developer-facing abstraction
The best customer API accepts a normal text string and returns logical message metadata. Advanced customers can inspect segment count, encoding and provider attempt information, but ordinary application code should never need to construct UDH or sequence numbers. This abstraction reduces integration defects and makes provider migration easier.
Deep architecture and production guidance
Concatenation creates an important distinction between logical delivery and physical delivery. The business application usually cares whether its complete notification reached the recipient, while the telecom network processes segments independently. The messaging platform should therefore maintain a logical state and, where evidence is available, segment-level evidence. Suppose a three-segment message produces two successful delivery receipts and one failure. Marking the logical message as delivered would be misleading. Conversely, treating every segment as an independent customer-visible message would make reporting confusing. A good model aggregates segment evidence according to a documented policy. The platform should also prevent retries from changing the intended segment structure unexpectedly. If a retry uses a different encoding or provider, the physical segmentation may change. That is acceptable only if the logical message remains the same and duplicate protection is maintained. Providers may also expose only logical or partial delivery information, so the platform should document the limits of its evidence. Developers building payment, banking or authentication workflows should never assume that one HTTP response represents delivery of every physical segment. They should use the documented final status or webhook event.
Developer implementation note
A multipart message should have one logical lifecycle even though it has multiple physical submissions. Billing, customer reporting and application status should normally be based on the logical message, while internal diagnostics can expose segment-level detail. When a provider returns one receipt per segment, aggregate those receipts using explicit rules. When only one logical receipt is available, do not invent segment-level delivery states. Document the evidence level clearly.
Practical troubleshooting and decision guide
For multipart troubleshooting, start with the logical message ID and determine the expected segment count. Then inspect each provider attempt and its segment identifiers. Confirm that sequence metadata was generated consistently and that the provider accepted the complete set. If receipts are available, correlate them to segment attempts and apply the documented aggregation policy. Do not troubleshoot only from what appears on a handset because device behaviour can obscure network evidence. When duplicates occur, check whether a timeout caused the logical message to be retried before the first attempt's outcome was known. If only one segment is duplicated, inspect the provider adapter's attempt handling rather than simply resending the complete message. The safest architecture keeps segmentation, retry and reconciliation under one logical message controller.
Operational reference note
The platform should also expose enough segment information for billing reconciliation without forcing customers to understand telecom protocol details. A report can show one logical message, its segment count, provider attempts and final outcome. If a message is retried after an uncertain provider response, keep the retry attempt separate from the logical message count. This prevents both operational confusion and accidental double counting. For developers integrating ERP, CRM or banking systems, this distinction is especially important because their application normally creates one business notification even when the network requires several physical submissions.
Advanced developer guidance
For provider-specific multipart limits, the adapter should validate the number of physical segments before submission. If the route supports fewer segments than the logical message requires, the API should fail before queueing or route to another eligible provider according to policy. This avoids discovering an unsupported message size after consuming worker and provider resources. Segment validation belongs near the final route decision because only then are provider capabilities known. The customer-facing error should remain stable and explain the corrective action, such as shortening the message or selecting a supported route. Historical attempt records should preserve the calculated segment count so support can reconcile the decision later.