> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SMS Chunking

> Automatically split outbound SMS that exceed the per-destination segment limit into multiple messages sent sequentially in order.

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](https://developers.telnyx.com/docs/messaging/messages/messaging-profiles-overview.md). When disabled (the default), messages that exceed the segment limit are rejected with error `40302`.

> [!NOTE]
>
> 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`:

```json theme={null}
{
  "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:

1. 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).
2. 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](https://developers.telnyx.com/docs/messaging/messages/message-encoding), determines the split boundaries (153 characters per segment for GSM-7; 134 bytes, or 67 characters, per segment for UCS-2).
3. Each chunk becomes an independent SMS with its own message ID, segment count, and delivery receipt. Standard concatenation still applies within a chunk.
4. 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.
5. 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](https://developers.telnyx.com/api-reference/profiles/update-a-messaging-profile.md) endpoint (or when [creating a profile](https://developers.telnyx.com/api-reference/profiles/create-a-messaging-profile.md)):

```bash curl theme={null}
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
    }
  }'
```

```javascript Node theme={null}
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);
```

```python Python theme={null}
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)
```

> [!NOTE]
>
> 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:

```json theme={null}
{
  "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](https://developers.telnyx.com/api-reference/messages/retrieve-a-message.md)) — 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):

```json theme={null}
{
  "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.

## Related resources

> **[Message Encoding](https://developers.telnyx.com/docs/messaging/messages/message-encoding.md)**
>
> Segment math for GSM-7, UCS-2, and concatenated SMS.

> **[Smart Encoding](https://developers.telnyx.com/docs/messaging/messages/smart-encoding.md)**
>
> Reduce segment counts by substituting Unicode characters with GSM-7 equivalents.

> **[Error Codes](https://developers.telnyx.com/docs/messaging/messages/error-codes.md)**
>
> Reference for error `40302` and other messaging errors.

> **[Messaging Profiles API](https://developers.telnyx.com/api-reference/profiles/update-a-messaging-profile.md)**
>
> API reference for updating messaging profile features.