This is the current API V1 documentation. Explore our API V2 beta if you’d like to test new features.

Docs

Character and Rate Limitscharacter-and-rate-limits

This guide covers everything you need to know about character and rate limits with Telnyx, so you can make informed decisions when it comes to your message content and delivery.

Character Limitscharacter-limits

Telnyx will always use the most compact encoding to deliver your message. Longer messages may be split into multiple parts, and you are billed per-part. Where possible, we recommend altering the characters used in messages so they can be encoded in the fewest number of parts. Each part can hold 140 bytes. In each part of a multi-part message, 6 bytes are reserved.

We support two encodings:

  1. 1GSM-safe characters: ASCII charactersTelnyx Developers (U+0020 to U+007E), excepting the grave accent (U+0060, `), and including the control characters new-line (U+000A, \n) and carriage-return (U+000D, \r).

    GSM encoding can pack up to 160 characters into a 140 byte message. The characters ~^|\{}[] each require an escape code, so when we encode your message they will end up using two characters. Messages that only use characters from the GSM-safe set and are 160 characters or less will be billed as one part. Messages beyond 160 characters will be split into two or more parts, and each part will only hold 153 characters.

  2. 2UTF-16 (UCS2): all Unicode characters.

    Other messages will be encoded using UTF-16, and each character will use two or four bytes, so a maximum of 70 characters can fit into a single-part message. Some characters, for instance emojis, will take four bytes per character, while characters from the Unicode Basic Multilingual PlaneTelnyx Developers will only use two bytes.

Example Single-Part Character Limitsexample-single-part-character-limits

The character limit for a single part message where the message contains:

  • only GSM-safe characters, none that require an escape: 160
  • only GSM-safe characters, including one pair of square brackets ([]): 158
  • one or more non-GSM-safe characters, but where all are in the Basic Multilingual Plane: 70
  • only characters from Supplementary Planes e.g. emojis: 35

Example Multi-Part Calculationsexample-multi-part-calculations

  • A message of 307 ASCII letters and punctuation from the GSM-safe set.

    The SMS must be split because it is over 160 characters. Each part of a split message can only hold 153 characters, and because 307 (GSM-7 characters) / 153 (GSM-7 characters/part) = 2.01 parts, it will be billed as 3 parts.

  • A message containing 134 ASCII letters + 1 interrobang (U+203D, ).

    Because the interrobang lies outside the GSM-safe character list, the message will be encoded as UTF-16, using twice the number of bytes. The 135 characters will use 270 bytes. 270 bytes / 134 (bytes/part) = 2.01 parts, so it will take 3 parts.

  • A message containing 68 tacos (U+1F32E, 🌮).

    Emojis take two UTF-16 code-units (two-byte pairs) per character, so the total message length is 136 code-units or 272 bytes. As above, 134 bytes will fit into each message part, so as 272 bytes / 134 (bytes/part) = 2.02 parts, it will take 3 parts.

Rate Limitsrate-limits

We recommend enforcing your own rate limits on outbound messages to help prevent issues with delivery.

Telnyx will rate limit outbound messages as follows:

  • Long Code: 10 messages/minute/number
  • Toll Free: 1200 messages/minute/number
  • Account: 1 message/second

In general, long code numbers will encounter deliverability issues downstream if you attempt to send more than 200 messages per day. Please contact Telnyx sales (sales@telnyx.com) to discuss your use case and options for enabling higher message throughput.

Messages that exceed the limits will be queued for your account. Messages will be added to the queue until it becomes full, after which all subsequent messages will be rejected. Messages won't appear in a MDR search while in the queue.