123eworld Knowledge Hub → Transactional SMS API → Page 265
Transactional SMS API Long SMS Handling: Multipart Messages, Concatenation and Delivery Tracking
A practical developer reference focused on solving real implementation and production problems around transactional sms api long sms handling: multipart messages, concatenation and delivery tracking.
Why long SMS needs architecture
Long SMS is not simply a larger text field. The message may be split into multiple SMS segments that travel independently and are reassembled by the handset. The API must therefore track logical message identity and individual segments.
Concatenation
Multipart SMS uses concatenation metadata so the receiving device can reassemble segments. Segment ordering and identifiers must be preserved across provider submission.
Segment limits
The number of characters per segment depends on encoding and concatenation. Developers should use the provider's documented calculation rather than assuming one universal limit.
Logical versus physical messages
One customer notification can become several physical SMS segments. Reporting should distinguish the logical message from the number of segments used.
Partial delivery
It is possible for some segments to be delivered while another segment fails. The platform should define how the overall logical status is represented.
Retries
Retrying one failed segment can have different consequences from retrying the entire logical message. Track segment-level attempts so a successful segment is not unnecessarily duplicated.
Delivery receipts
Providers may return delivery receipts per segment or aggregate them. Normalize these into a logical message status while retaining physical evidence.
Templates
Personalized variables can increase length unpredictably. Calculate segmentation after substitution, not only on the template body.
Cost
Multipart messages consume multiple billable units under many commercial models. Reporting should expose segment count so customers understand usage.
Testing
Test boundary lengths, Unicode, segment loss, duplicate segment callbacks and out-of-order delivery reports.
Operational monitoring
Track average segments per message, unusually large messages, segment failure rates and provider-specific differences.
Reference flow
Compose text → encode → segment → assign concatenation identity → submit segments → track receipts → aggregate logical status.
Production architecture
A reliable transactional SMS API separates synchronous API admission from asynchronous delivery processing. The API validates input, authenticates the tenant, applies quotas and creates a durable logical message. Queue workers then perform provider interaction, retries and status processing. This separation keeps customer HTTP requests fast while allowing downstream work to recover from temporary failures.
Security and tenant isolation
Every operation should remain scoped to the authenticated tenant. API credentials, templates, sender identities, message records, webhooks and reporting data must not cross tenant boundaries. Logs and support tools should expose only the minimum information needed for diagnosis.
Observability
Use request IDs, message IDs, provider attempt IDs and event IDs to connect the lifecycle. Monitor latency, queue age, provider errors, retry counts, delivery outcomes and resource saturation. Good observability should answer what happened, where it happened and what the system will do next.
Failure handling
Design for timeouts, duplicate requests, duplicate callbacks, provider outages, worker restarts and partial failures. Idempotency and reconciliation are essential because distributed systems cannot always know whether a remote operation completed before a local failure.
Developer experience
Documentation should provide request examples, response schemas, error codes, retry guidance, limits and production checklists. Developers should understand the difference between API acceptance, provider submission and final handset delivery.
Testing and release
Use unit, contract, integration, load, security, failure-injection and end-to-end tests. Include realistic edge cases and turn production incidents into regression tests. A feature should not be considered complete until its failure behaviour is documented and tested.
Practical checklist
Before production, verify authentication, authorization, rate limits, idempotency, queue durability, provider routing, timeout policy, observability, data retention, reconciliation, backup and recovery procedures. Test both normal traffic and realistic dependency failures.
Knowledge-base connection
This guide is part of the 123eworld developer knowledge base. Continue through the 123eworld Knowledge Hub for related SMS API, gateway, security, reliability and integration topics.
Concatenation identity
Multipart segments require identifiers that allow the handset to reassemble them. The provider adapter should retain enough information to correlate every physical segment with the logical message.
Segment ordering
Segment sequence must remain stable. Retries should not accidentally create a second copy of a segment or change the intended order.
Partial failure policy
If one segment fails permanently, define the logical message outcome. In some applications a partial notification is unusable; in others the customer may prefer a visible partial result. The API should state the policy.
Long-message limits
Set a maximum logical message length that protects both provider cost and operational resources. The limit should be expressed in terms developers can understand and tested with actual encoding.
Provider differences
Different providers may report multipart messages differently. Normalize provider-specific segment IDs and receipt formats while retaining the raw evidence needed for reconciliation.
Cost estimation
A cost estimator should use final encoded content and segmentation rules. Estimating from character count alone can produce material billing surprises.
Testing
Use boundary cases immediately below and above segment thresholds, Unicode transitions, multiple segments, missing segment receipts, duplicate receipts and delayed segment delivery.
Segment correlation
Maintain a segment table or equivalent event model containing logical message ID, segment sequence, provider segment ID and current status. This allows support to investigate one missing segment without losing the complete message context.
Logical status policy
Define whether a long message becomes delivered only when all segments are delivered. If so, document how partial delivery appears in reporting. A clear rule prevents developers from interpreting a segment receipt as complete message delivery.
Segment retry isolation
Retry only the affected physical segment when the provider contract allows it and when doing so is safe. Avoid resubmitting already delivered segments simply because another segment failed.
Long-message observability
Monitor segment count distribution, multipart failure rate, missing segment receipts and reassembly-related complaints. These metrics can reveal encoding or provider issues that ordinary message-level delivery rates hide.
Production implementation guidance
Long SMS handling should model the logical notification and its physical segments separately. The logical message identifies the customer's intended communication, while each segment has its own sequence, provider identifier and delivery state. This allows the platform to retry a failed segment without resending segments that were already delivered, where the provider contract makes that safe. The overall logical status should be calculated from segment outcomes using a documented policy. For example, a message may remain incomplete until every required segment is delivered. Delivery receipts can arrive out of order or more than once, so the state machine must tolerate duplicates and late events. Template substitution should occur before segmentation because variable values can change the number of segments. Reporting should expose both logical message count and physical segment count so customers understand usage. Boundary tests around encoding changes and segment thresholds are essential because a single character can change the physical delivery model and cost.
Final production checklist
Before production long-SMS support, verify segmentation thresholds, concatenation identifiers, sequence ordering, segment-level retries, partial delivery policy, duplicate receipts, late receipts, provider differences and segment-based reporting. Test messages immediately around every important segmentation boundary.
Operational runbook guidance
A useful long-SMS runbook should identify the logical message, list its physical segments, show each provider attempt and display missing or duplicate receipts. Operators should be able to reconcile a partial delivery without resending segments that already succeeded.
Design review note
Long-message status should remain stable when duplicate or late segment receipts arrive. The state machine should ignore events that cannot improve the known state and retain the evidence for troubleshooting.
Architecture review
Multipart messages should be tested through the full provider path because local segmentation alone does not prove handset behaviour. Verify that provider submission, concatenation metadata, delivery receipts and logical aggregation agree. Where provider evidence differs from platform expectations, retain the raw provider identifiers so support can investigate without reconstructing the event history from incomplete application logs.
Final review
The final long-SMS review should verify segment identity, ordering, retries, receipts, partial failures, logical status and reporting. Segment-level evidence should remain available for reconciliation even after the customer-facing message reaches its final state.
Implementation note
Segment receipts should never create a second logical message.