Skip to main content

Messaging configuration and usage

Messaging features are configured primarily using Messaging Profiles. You can set up several messaging profiles in order to differentiate between use cases.

You can enable messaging on a phone number by assigning it to a Messaging Profile. Multiple phone numbers can be assigned to a Messaging Profile. Additional configuration, including setting webhooks, is also available using our HTTP API and an API Key.

To send messages from, and retrieve message details for one of your phone numbers, use our HTTP API.

Queuing​

If you send more messages than your rate limit allows, messages will be held in a queue. If the queue time is more than 1hr, the message will immediately be rejected.

Throttling​

  • Proper throttling is important to limit the risk of having SMS messages flagged as SPAM. US long code numbers are restricted to sending 10 messages per minute for any single long code. If you require faster throughput, then you must purchase more long codes. If you ignore these recommendations, the mobile operators will block your numbers.

  • By default, your Telnyx Portal account is limited to sending one message per second. If you require a higher limit, please reach out to [email protected].

  • If you create messages at a faster rate, Telnyx will queue up the messages and send them at a reduced rate. Messages that are queued (and not yet sent) will not appear in the MDR reports.

Characters​

  • Multi-part messaging is allowed.

  • Each part has 160 characters limitation if it’s in the gsm 7-bit character set.

  • If using characters outside of gsm 7 bit, then encoding is switched to utf-16, which will limit the user to 70 characters in a message.

  • Spaces and commas are counted as characters.

  • If the message contains more than 160 characters it will be separated into, and billed as, multiple messages. The mobile operator may combine into a single message on the recipient’s device. Read more about character limits here.

Auto-Responses​

  • If a mobile user sends a message containing only the following words or phrases (case-insensitive, surrounding whitespace-insensitive) to one of our numbers via SMS, that number and the account will be blocked from sending SMS to the mobile number. The customer will receive an HTTP 409 if they try.

    • Cancel
    • End
    • Stop
    • Stopall
    • Stop all
    • Quit
    • Unsubscribe

  • To unblock the customer, the mobile user must send the blocked number one of the following words or phrases (case-insensitive, surrounding whitespace-insensitive).

    • Start
    • Unstop

Error codes​

You can find detailed information about error codes here.

For more information on how to make sure your long code SMS messages get through, check out our support article on Long Code Deliverability Best Practices.

Glossary​

MDR

A Message Detail Record (MDR) details information about a specific message that you sent from, or received on a Telnyx phone number.

Messaging Profile

Used to configure messaging settings on one or more of your Telnyx messaging-enabled phone numbers.

Messaging-Capable

A phone number that could be used for text messaging. If a phone number is messaging-capable, but is not messaging-enabled, first check that it is assigned to a messaging profile, and then that the profile is the profile is enabled.

Messaging-Enabled

A phone number that is ready and able to send and receive messages. All messaging-enabled phone numbers are messaging-capable.

Alphanumeric Sender ID

A sender value that can be used in place of a phone number. Alphanumeric Sender IDs can only be used for outbound messages; it is not possible to receive messages on an Alphanumeric Sender ID. They are also not supported for all destinations, in which case the sender might be substituted with a different value (the specific number that shows up to the recipient can vary, and it cannot receive inbound messages). An Alphanumeric Sender ID must be 1–11 characters in length, can only contain Latin letters, numbers, and spaces, and must contain at least one letter.

Webhook

An HTTP callback used to send notifications to your server. Can be used to receive inbound text messages and also delivery status updates for outbound text messages.

On this page​