SMS Chunking

SMS chunking automatically splits an outbound SMS that exceeds the maximum number of segments allowed for its destination into multiple child messages, each within the limit, and sends them sequentially in order. The feature is controlled by the auto_chunk_long_messages flag on a messaging profile. When disabled (the default), messages that exceed the segment limit are rejected with error 40302.

SMS chunking applies to SMS only. MMS and RCS messages are not affected.

Why use SMS chunking

Most carriers reject concatenated SMS beyond 10 segments — 1,530 GSM-7 characters or 670 UCS-2 characters. Some aggregator routes accept longer messages, up to 25 segments. By default, a message that exceeds the limit for its destination is rejected with error 40302:

{
  "errors": [
    {
      "code": "40302",
      "title": "Message too large",
      "detail": "The SMS message would be divided into 11 parts. The maximum is 10."
    }
  ]
}

With SMS chunking enabled on the profile, the same request is delivered as two or more independent messages:

Body	Encoding	Total segments	Chunk 1	Chunk 2
1,600 characters	GSM-7	11 (10 + 1)	1,530 chars (10 segments)	70 chars (1 segment)
700 characters, contains non-GSM characters	UCS-2	11 (10 + 1)	670 chars (10 segments)	30 chars (1 segment)

How it works

When auto_chunk_long_messages is enabled on the messaging profile:

Telnyx counts the segments of the encoded body and the maximum segments allowed for the destination route (10 by default; some aggregator routes accept up to 25).
If the message exceeds the limit, the body is split into chunks at segment boundaries — never inside a multi-byte character or a GSM-7 escape sequence — so every chunk renders correctly. The message encoding, including any per-request encoding override, determines the split boundaries (153 characters per segment for GSM-7; 134 bytes, or 67 characters, per segment for UCS-2).
Each chunk becomes an independent SMS with its own message ID, segment count, and delivery receipt. Standard concatenation still applies within a chunk.
Chunks are sent sequentially: the next chunk is dispatched once the upstream gateway accepts the previous one (the message.sent stage), without waiting for its delivery receipt.
All chunks of one request share the same sender and route.

Chunks are dispatched as soon as the previous one is accepted by the upstream gateway, without per-message rate pacing between chunks. Rate limits still apply to the initial send.

If a chunk is rejected before it is accepted (for example, a gateway reject or a spam or 10DLC block), the remaining chunks that have not yet been sent are cancelled and are not delivered. Cancelled chunks do not generate message.sent or message.finalized webhooks. A delivery failure reported after a chunk is accepted does not stop the group: the next chunk has already been dispatched, so later chunks can still be delivered even if an earlier chunk’s message.finalized reports a failure. A chunk whose delivery receipt never arrives also does not block the chunks after it.

Enable SMS chunking

Set auto_chunk_long_messages under features on a messaging profile with the Update a Messaging Profile endpoint (or when creating a profile):

curl -X PATCH https://api.telnyx.com/v2/messaging_profiles/{id} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "features": {
      "auto_chunk_long_messages": true
    }
  }'

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env.TELNYX_API_KEY,
});

const response = await client.messagingProfiles.update(
  'your_messaging_profile_id',
  { features: { auto_chunk_long_messages: true } }
);

console.log(response.data);

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),
)

response = client.messaging_profiles.update(
    "your_messaging_profile_id",
    features={"auto_chunk_long_messages": True},
)

print(response.data)

Set auto_chunk_long_messages as a JSON boolean. The API also accepts 1/0 and the strings "true"/"false"/"1"/"0" (case-insensitive); any other value, such as "yes", is rejected with a validation error. Setting the flag preserves the other keys in the features object.

Chunk responses and webhooks

The API response to a chunked send is the first chunk. It carries the first chunk’s text slice and parts count (within the destination limit), and child_message_id pointing at the next chunk. Its own parent_message_id is null — the first chunk’s id is the original request’s ID:

{
  "data": {
    "record_type": "message",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc77ae0",
    "direction": "outbound",
    "type": "SMS",
    "from": {
      "phone_number": "+15551234567"
    },
    "to": [
      {
        "phone_number": "+15559876543",
        "status": "queued"
      }
    ],
    "text": "…first 1,530 characters of the message…",
    "parts": 10,
    "encoding": "GSM-7",
    "parent_message_id": null,
    "child_message_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

Each chunk is linked through two fields, always present in the send response, the message.sent / message.finalized webhooks, and the message detail record (Retrieve a Message) — returned as null when not applicable:

Message	`parent_message_id`	`child_message_id`
Non-chunked send	null	null
First chunk (the send response)	null	next chunk’s ID
Middle chunk	original request ID	next chunk’s ID
Last chunk	original request ID	null

The first chunk’s id is the message ID of the original request, so parent_message_id groups every chunk back to the same request. Use it for billing analysis, detail records, and grouping delivery receipts per original request. message.finalized webhook for the last chunk (abridged to the fields relevant to chunking):

{
  "data": {
    "event_type": "message.finalized",
    "id": "4ee8c3a6-4995-4309-a3c6-38e3db9ea4be",
    "occurred_at": "2026-10-28T14:20:11.317Z",
    "payload": {
      "direction": "outbound",
      "encoding": "GSM-7",
      "from": {
        "phone_number": "+15551234567"
      },
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "parent_message_id": "0ccc7b54-4df3-4bca-a65a-3da1ecc77ae0",
      "child_message_id": null,
      "parts": 1,
      "record_type": "message",
      "text": "…final 70 characters of the message…",
      "type": "SMS",
      "to": [
        {
          "phone_number": "+15559876543",
          "status": "delivered"
        }
      ]
    },
    "record_type": "event"
  }
}

Each chunk’s response and webhooks carry that chunk’s own text slice, not the full original body.

Chunk webhooks may arrive out of order: the next chunk is dispatched as soon as the previous one is accepted, so its webhook can arrive before the previous chunk’s message.finalized. Correlate by parent_message_id and the chunk’s id rather than arrival order.

Billing

Each chunk is billed as its own message based on its own segment count.

Limitations

SMS only — MMS and RCS are not chunked.
Messaging-profile scope — chunking is enabled per profile; there is no per-request parameter.
Per-chunk ceiling — each chunk holds at most the destination’s segment ceiling (10 segments, or 25 on some aggregator routes), so a body is split into as many chunks as needed. For example, a 21-segment body on a 10-segment route is sent as three chunks.

Message Encoding

Segment math for GSM-7, UCS-2, and concatenated SMS.

Smart Encoding

Reduce segment counts by substituting Unicode characters with GSM-7 equivalents.

Error Codes

Reference for error 40302 and other messaging errors.

Messaging Profiles API

API reference for updating messaging profile features.

Sending Messages

Messaging Profiles

Short Code

Hosted Numbers

Opt Outs

Phone Numbers

Toll Free Verification

10 DLC

For AI Agents

Why use SMS chunking

How it works

Enable SMS chunking

Chunk responses and webhooks

Billing

Limitations

Message Encoding

Smart Encoding

Error Codes

Messaging Profiles API

​Why use SMS chunking

​How it works

​Enable SMS chunking

​Chunk responses and webhooks

​Billing

​Limitations

​Related resources

Message Encoding

Smart Encoding

Error Codes

Messaging Profiles API

Why use SMS chunking

How it works

Enable SMS chunking

Chunk responses and webhooks

Billing

Limitations

Related resources