Messaging Services

Sending a high volume of messages in the United States and globally quickly becomes complex. As the complexity of your messaging application grows, it’s helpful to organize your account and message logs into separate Messaging Services using Twilio Programmable Messaging.

You can think of a Messaging Service as a higher-level “bundling” of messaging functionality around a common set of senders, features, and configuration. The same settings and feature configuration apply to all of the senders (long code numbers, short codes, toll-free numbers, etc.) in the Messaging Service’s pool.

A Messaging Service’s features can be managed and configured directly through the Console as well as using the REST API.

With each Messaging Service that you add through the console, you’ll start by configuring its incoming message handling and status callback URL. These can be configured in the Integration section of your messaging service's settings.

You’ll also need to associate one or more phone numbers or short codes to the Service to send messages. You can add additional messaging features (described below) to your application through your newly configured messaging service.

Table of Contents

• Send a message with a Messaging Service
• Using WhatsApp with Messaging Services
• “Out-of-the-box” Messaging Service features
• Configurable Messaging Services features
• Link Shortening & Click Tracking

Send a message with a Messaging Service

If you use a messaging service to send a message, your request to Twilio will look very similar to sending an SMS with the REST API. However, instead of including a From phone number, you’ll include a MessagingServiceSid. Twilio will then choose one of the phone numbers in your Messaging Service’s sender pool based on your service’s configuration.

When sending a message with a messaging service, Twilio will immediately set the message’s status to accepted. Twilio will then determine the optimal From phone number from your service.

Status Callback URL

The delivery status of your message, including any delivery errors, will be sent asynchronously to your status callback URL. This URL can be specified in your Twilio Console for your Messaging Service in the Integration > Delivery Status Callback section. Alternatively, you can specify your status callback URL using the API.

Using WhatsApp with Messaging Services

You can add a WhatsApp-enabled Twilio phone number to the other sender-types (long codes, short codes, etc.) in your Messaging Service Sender Pool. This way, you can configure and apply the relevant Messaging Service features, such as setting a Validity Period, for all sender types in one Service all at once. In the feature descriptions below, we include whether the feature is supported for both SMS and WhatsApp.

To include WhatsApp in your Sender Pool, in the Twilio Console, navigate to the Messaging > Services section and select a Messaging Service. Under that Service's Sender Pool, you can Add Senders and specify the WhatsApp-enabled Twilio number that you wish to include.

For more information about configuring the WhatsApp Business API with Twilio, please read Connect your Twilio Number to your WhatsApp Business Profile.

“Out-of-the-box” Messaging Service features

Messaging Services are designed to help you scale your application’s messaging from your first SMS to messages sent globally, in multiple languages, from more than just long code phone numbers.

As soon as you create your Messaging Service, the following features apply automatically, in contrast to configurable Messaging Services features.

Alpha Sender

Alphanumeric Sender IDs are used for branded one-way messaging. You can add an Alphanumeric Sender ID to your Sender Pool to enable this feature.

With Alpha Sender, you can send your messages to customers from a customized sender. Instead of using an E.164-formatted Twilio phone number for the From value, you can use a custom string like your own business’ branding. Alphanumeric Sender IDs may be used at no additional cost when sending an SMS to countries that support this feature.

If you add an Alpha Sender to your Twilio Messaging Service, Twilio will select the Alphanumeric Sender ID automatically when you send a message to a supported country, unless you also have a short code number in that same country.

How to add an Alphanumeric Sender ID

1. Go to your Messaging Services in the Twilio Console.
2. Select the service you wish to add an Alpha Sender to.
3. Under the Senders section, click the Add Senders IDs button.
4. From the Add Senders IDs drop-down, select Alpha Sender and enter the alphanumeric sender ID that you want to add to the Sender Pool.

To learn more about Alphanumeric Sender IDs, see the support article on getting started with Alphanumeric Sender ID.

Short Code Reroute

When your Messaging Service Sender Pool includes a short code, Twilio always prioritizes message delivery using that short code. If a carrier is not supported by a Twilio short code, Twilio automatically delivers the message with a long code in your Messaging Service instead.

Twilio automatically applies short code rerouting for messages sent through your Messaging Service. This is not a feature that you enable or disable.

Country Code Geomatch

When sending messages internationally, the Country Geomatch feature automatically selects the Twilio phone number in your Messaging Service to match the country of your recipient’s phone number. If your Service does not include a Twilio phone number for the same country of the recipient, Twilio first attempts to select an SMS-enabled US phone number before selecting another phone number to deliver your message. Your message will fail if there are no phone numbers available in your Service to deliver your message.

You can use Country Code Geomatch by adding phone numbers to your Messaging Service that match the countries of your recipients.

When a phone number of a new geographic country is added to your Messaging Service, Twilio automatically selects and remaps any existing Sticky Sender mappings so that the From number matches the same country as your recipient’s phone number.

Scaler

The Scaler feature distributes your outbound messaging traffic evenly across the phone numbers in your Messaging Service so that you can handle higher volumes of messages. When your Messaging Service sends a message, it selects a From number from the numbers in your Sender Pool that are not currently being used to send other messages.

When Sticky Sender is enabled, the Messaging Service prioritizes any existing Sticky Sender mappings first. It then selects the next available phone number from your Service’s Sender Pool which has the fewest number of mappings.

Configurable Messaging Services features

In addition to the basic Messaging Service functionality discussed above, there are several, more advanced features that you can use to manage your Service’s senders, integration with your application, your messaging content, compliance, opt-out keywords, and more.

You can enable these features and change their settings in the Twilio Console.

Sticky Sender

The Sticky Sender feature ensures the same From phone number is selected every time your application sends a message to a particular end-user. This allows your application to consistently send messages to your user from a single, recognizable phone number.

With Sticky Sender enabled, Twilio maintains a mapping of all To and From phone numbers that your Messaging Service has used and interacted with. Twilio creates a new mapping after it sends the first message from your Messaging Service to a particular end-user. All future messages sent to that recipient from the Service will also use the same From number.

If Sticky Sender is turned off, your Messaging Service ignores all previously established mappings. However, if you toggle Sticky Sender back on in the future, your Messaging Service will retain and reference the previously existing mappings.

How to enable Sticky Sender

Under the Sender Pool section of your Messaging Service, expand the Sender Selection Settings box. From there, you can enable or disable the Sticky Sender feature.

Intelligent number selection within a Messaging Service

When Sticky Sender is enabled, the Messaging Service follows the logic below to determine the optimal phone number as the From number:

Area Code Geomatch

When sending messages to the United States and Canada, the Area Code Geomatch feature selects a local phone number with an area code that either matches or is an overlay of your end-user’s number.

If an overlay or matching area code is not available, the Messaging Service will select another US or Canadian phone number from your Messaging Service. Geographic proximity is not taken into consideration in this case.

How to enable Area Code Geomatch

Under the Sender Pool section of your Messaging Service, expand the Sender Selection Settings box. From there, you can enable or disable the Area Code Geomatch feature.

Fallback to Long Code - DEPRECATED

The Fallback to Long Code feature has been deprecated and can no longer be enabled via the Twilio Console.

Previously, this feature would trigger a message retry from a long code if a message sent from a short code to a US recipient returned a specific error to Twilio, indicating that the user has a block on "business messaging" on their account. These blocks were uncommon, but the error was considered a valid reason to retry. Prior to the introduction of the A2P 10DLC registration framework for long code messaging to the US, long code phone numbers were excluded from this block.

Since the full rollout of A2P 10DLC, however, such "business messaging" blocks apply to all forms of business messaging in the US (A2P 10DLC, Toll-Free, and short code).

Automated message retries for delivery errors are generally discouraged and do not tend to improve delivery success, so this feature has been deprecated.

Validity Period

Validity Period refers to the number of seconds for which messages sent from your Messaging Service will remain in Twilio’s platform. If the time taken to send the message exceeds the Validity Period, Twilio fails the message and sends a request to your status callback URL to notify your application of the failure.

How to enable Validity Period

Under the Integration section of your Messaging Service, you can enter the maximum queue time — in seconds — in the Validity period section.

You can set the Validity Period between 1 and 14,440 seconds (a maximum of four hours).

Incoming Messages Handling

By default, Twilio will set your Messaging Service to "Defer to sender's webhook," meaning inbound messages will hit whatever inbound message handler is configured on your individual phone numbers. You can also change the behavior to automatically create a new Conversation — there’s more on this feature under Inbound Message Handling & Autocreation in Conversations.

How to enable Incoming Messages Handling

Under the Integration section of your Messaging Service, you can update how your messaging service handles incoming messages. Please be aware that using the Autocreate a Conversation option requires additional configuration changes under the Conversations section of the Twilio Console.

Smart Encoding

Your Messaging Service’s Smart Encoding feature detects easy-to-miss Unicode characters and replaces them with a similar GSM-encoded character. This helps ensure that your message gets segmented at 160 characters and saves you from sending two message segments, which increases your spend.

For example, sometimes a Unicode character such as a smart quote ( 〞), a long dash (—), or a Unicode whitespace accidentally slips into your carefully crafted 125-character message. Now, your message is segmented and priced at two messages instead of one.

This is because when Unicode characters are used in an SMS message, they must be encoded as UCS-2. However, UCS-2 characters take 16 bits to encode, so when a message includes a Unicode character, it will be split or segmented between the 70th and 71st characters. This means that the character limit for UCS-2 encoded messages is shorter than the 160-character per message segment limit that you get with GSM-7 character encoding.

How to enable Smart Encoding

Under the Content Settings section of your Messaging Service, you can enable or disable the Smart Encoding feature for SMS messages.

MMS Converter

The MMS Converter feature automatically delivers your MMS message as an SMS text message if the carrier does not support the receiving of Twilio MMS Messages. In these cases, the MMS Converter will transform the MMS to an SMS (text) message that contains a shortened URL linking to your image. MMS Converter appends the shortened URL link (https://p.twil.io/ followed by seven unique characters) to the end of the message body; this link remains active for 365 days (one year).

How to enable MMS Converter

You can enable or disable the MMS Converter feature under the Content Settings section of your Messaging Service.

Sender ID Pre-registration Alert

The Sender ID Pre-registration Alert feature automatically alerts you when you send messages to countries that require pre-registered Sender IDs. Some countries that support Alphanumeric Sender IDs require pre-registration of the Sender ID prior to use.

To help you remain compliant, enable Sender ID Pre-registration Alert as you scale your messaging traffic. Once it is enabled, this feature issues warnings when you send unregistered messaging traffic in countries where registration is recommended or required. You can find the alerts in the Debugger section of the Twilio Console.

How to enable the Sender ID pre-registration alert

You can enable or disable the Sender ID pre-registration alert feature under the A2P & Compliance section of your Messaging Service.

Advanced Opt-Out

The Advanced Opt-Out feature gives you the ability to deliver a customized, end-to-end compliance experience for your users. You have the ability to set the opt-in, opt-out, and help keywords and confirmation messages on a global basis as well as add per-language and per-country overrides. For example, you can customize the message that your end-users receive if they reply with "STOP" in English or with "AYUDA" in Spanish.

In addition, Advanced Opt-Out gives you deeper insight into your campaign performance and user engagement with your Messaging Service. When a user triggers one of your opt-in, opt-out, or help keywords, Twilio includes the OptOutType in its request to your configured webhook URL so that you can keep track of the health of your campaigns.

How to enable Advanced Opt-Out

Under the Opt-Out Management section of your Messaging Service, you can select Enable Advanced Opt-Out as well as customize all of the keyword and confirmation messages for opt-out, opt-in, and help interactions with your end users.

We recommend that you read the guide to customizing users’ opt-in and opt-out experience with Advanced Opt-Out to ensure that you configure this feature properly for your messaging needs.

Link Shortening & Click Tracking

Overview

Link Shortening is a feature under Twilio Messaging Services that enables you to shorten links in your communications, with your company branded registered domain, and track engagement across SMS, MMS, and WhatsApp. Link Shortening features are embedded into the Twilio Messaging API so that there is minimal implementation change required.

Link Shortening example:

Bring Your Own Domain

Link Shortening will require you to register and use your own domain for the shortened links. Unlike third party link shortening solutions, you will not need to share a domain with other customers and you will be able to brand the shortened links to your own business.

Shortened Links Retention

We will store the original link and shortened link associations for 90 days. When a recipient clicks on the URL in the message within the first 90 days, they will be redirected to the original link. 90 days after the message is delivered, a click will redirect to a fallback URL, which can be set up in the your Messaging Service's Link Shortening section of the Twilio Console or via the Domain Config API. A fallback URL can be set per domain.

Account-Based Rate Limits

Link Shortening has an account based rate limit of 100 requests per second for links shortened. This means that you can send requests to the Messaging API with link shortening enabled at 100 requests per second rate limit. If you exceed the rate limit, the following happens:

• You will receive a 20429 error code.
• We will not shorten the links.
• The messages will not be delivered to the recipients.

If you would like to request for a higher account based rate limit, please reach out to support@twilio.com.

Click Tracking

Twilio's shortened links with unique identifiers allow you to track who clicks on your links. You can also configure callback URLs to receive link clicked events and metadata about those events.

Unique Shortened Links

Different from other standalone link shortening solutions, each link that we shorten will get a unique ten alphanumeric character slug ID. This enables us to track engagement data per link, message, and recipient. Even when the shortened links expire after 90 days, the ten character slugs that have been previously used will never be recycled.

Click Events to Your Webhooks

You will also be able to set up callback URLs (webhooks) to receive a link clicked event that is generated whenever a recipient clicks on a shortened link via the Domain Config API. Each link clicked event will contain information such as the number the message was sent to, the original link contained in the message, and the time the recipient clicked on the link. If the recipient clicks on the link multiple times, multiple events will be generated.

Click event example:

{
  "event_type": "click",
  "sms_sid": "SMxxx",
  "to": "+11234567890",
  "from": "+10987654321",
  "link": "https://www.longlink.com/original_link",
  "click_time": "2022-10-24T17:17:26.529Z",
  "messaging_service_sid": "MGxxx",
  "account_sid": "ACxxx",
  "user_agent": "some_user_agent"
}

Domain Certificate API

The Domain Certificate API helps you manage your domain certificates for Link Shortening. You will only need to upload the certificate once from one account as the Domain resource resides under an Organization. Once a domain has a valid TLS certificate and private key uploaded, that domain can be used for Link Shortening in all accounts under the same Organization without needing to upload the certificate again. After the TLS certificate is uploaded, it may take at most 5 minutes for the certificate to be validated.

API Endpoint

https://messaging.twilio.com/v1/LinkShortening/Domains/$DOMAIN_SID/Certificate

POST (First time uploading the certificate)

When you are uploading the certificate for the first time, the certificate will be validated which may take up to 5 minutes. Once the certificate has been validated, cert_in_validation field will become null and all other fields will be populated with the uploaded certificate details.

Request (required parameter: TlsCert):

curl -X POST https://messaging.twilio.com/v1/LinkShortening/Domains/$DOMAIN_SID/Certificate \
--data-urlencode "TlsCert=$TLS_CERT_AND_PRIVATE_KEY" \
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN 

Response (201 Created):

{
    "certificate_sid": "CWxxx",
    "date_updated": "2022-11-07T19:41:39.570Z",
    "domain_sid": "DNxxx",
    "domain_name": "example.com",
    "date_expires": null,
    "url": "https://messaging.twilio.com/v1/LinkShortening/Domains/DNxxx/Certificate",
    "date_created": "2022-11-07T19:41:39.570Z",
    "cert_in_validation": {
        "status": "pending",
        "date_expires": "2023-05-25T17:56:09Z"
    }
}

POST (Uploading a new certificate)

When you are uploading a new certificate when a certificate already exists, you will see the new certificate's details in cert_in_validation field while the new certificate is being validated. Once the new certificate has been validated, the cert_in_validation field will become null and the other fields will be updated with the new certificate's details.

Request (required parameter: TlsCert):

curl -X POST https://messaging.twilio.com/v1/LinkShortening/Domains/$DOMAIN_SID/Certificate \
--data-urlencode "TlsCert=$TLS_CERT_AND_PRIVATE_KEY" \
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN 

Response (201 Created):

{
    "certificate_sid": "CWxxx",
    "date_updated": "2022-11-07T19:41:39.570Z",
    "domain_sid": "DNxxx",
    "domain_name": "example.com",
    "date_expires": "2023-05-25T17:56:09Z",
    "url": "https://messaging.twilio.com/v1/LinkShortening/Domains/DNxxx/Certificate",
    "date_created": "2022-11-07T19:41:39.570Z",
    "cert_in_validation": {
        "status": "pending",
        "date_expires": "2023-11-25T17:56:09Z"
    }
}

GET (When certificate has been validated)

When you retrieve a certificate that has already been validated, you will see the cert_in_validation field as null. If you try to retrieve the certificate details while the certificate is being validated, you will see the details in the cert_in_validation field.

Request:

curl -X GET https://messaging.twilio.com/v1/LinkShortening/Domains/$DOMAIN_SID/Certificate \
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Response (200 OK):

{
    "certificate_sid": "CWxxx",
    "date_updated": "2022-11-07T19:41:39.570Z",
    "domain_sid": "DNxxx",
    "domain_name": "example.com",
    "date_expires": "2023-05-25T17:56:09Z",
    "url": "https://messaging.twilio.com/v1/LinkShortening/Domains/DNxxx/Certificate",
    "date_created": "2022-11-07T19:41:39.570Z",
    "cert_in_validation": null
}

Domain Config API

The Domain Config APIs helps you configure the callback URL, fallback URL, delivery preference, and HTTPS prefix preference for the domain. If you wish to use the same domain in multiple Messaging Services, the same configurations will be used.

API Endpoint

https://messaging.twilio.com/v1/LinkShortening/Domains/$DOMAIN_SID/Config

POST

Request:

curl -X POST 
https://messaging.twilio.com/v1/LinkShortening/Domains/$DOMAIN_SID/Config \
--data-urlencode "FallbackUrl=$FALLBACK_URL" \
--data-urlencode "CallbackUrl=$CALLBACK_URL" \
--data-urlencode "ContinueOnFailure=true" \
--data-urlencode "DisableHttps=false" \
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Response (200 OK):

{
  "config_sid": "ZKXXXX",
  "fallback_url": "https://www.example.com",
  "callback_url": "https://www.example.com/webhook",
  "continue_on_failure": true,  
  "disable_https": false,
  "date_created": "2020-08-27T04:36:56Z",
  "date_updated": "2020-08-27T04:36:56Z"
}

GET

Request:

curl -X GET 
https://messaging.twilio.com/v1/LinkShortening/Domains/$DOMAIN_SID/Config \
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN 

Response (200 OK):

{
  "config_sid": "ZKXXXX",
  "fallback_url": "https://www.example.com",
  "callback_url": "https://www.example.com/webhook",
  "continue_on_failure": true,  
  "disable_https": false,
  "date_created": "2020-08-27T04:36:56Z",
  "date_updated": "2020-08-27T04:36:56Z"
}

Associate/Disassociate a Messaging service with a Domain

After you have set default preferences for a domain configuration with Domain Config API, you will need to associate the domain configuration to a specific Messaging Service. Associating the domain configuration to a Messaging Service will allow you to use the domain and its preferences when using Link Shortening with that Messaging Service.

API Endpoint

https://messaging.twilio.com/v1/LinkShortening/Domains/$DOMAIN_SID/MessagingServices/$MESSAGING_SERVICE_SID

POST (Associate a domain configuration to a Messaging Service)

Request:

curl -X POST https://messaging.twilio.com/v1/LinkShortening/Domains/$DOMAIN_SID/MessagingServices/$MESSAGING_SERVICE_SID \
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Response (201 Created):

{
   "messaging_service_sid": "MGXXX",
   "domain_sid": "DNxxx",       
   "url": "https://messaging.twilio.com/v1/LinkShortening/Domains/DNXXX/MessagingServices/MGXXX”
}

DELETE (Disassociate a domain configuration with a Messaging Service)

Request:

curl -X DELETE https://messaging.twilio.com/v1/LinkShortening/Domains/$DOMAIN_SID/MessagingServices/$MESSAGING_SERVICE_SID \
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Response (204 No content)

Get the Domain Configuration Associated to a Messaging Service

You can retrieve which domain configuration is associated with a Messaging Service using this API.

API Endpoint

https://messaging.twilio.com/v1/LinkShortening/MessagingService/$MESSAGING_SERVICE_SID/DomainConfig

GET

Request:

curl -X GET https://messaging.twilio.com/v1/LinkShortening/MessagingService/$MESSAGING_SERVICE_SID/DomainConfig \
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Response (200 OK):

{
   "domain_sid": "DNxxx",
   "config_sid": "ZKXXX",
   "messaging_service_sid": "MGXXX",
   "fallback_url": "https://www.example.com",
   "callback_url": "https://www.example.com/webhook",
   "continue_on_failure": true,  
   "disable_https": false,
   "date_created": "2023-03-15T15:13:04.091Z",
   "date_updated": "2023-03-23T20:33:03.256Z",
   "url": "https://messaging.twilio.com/v1/LinkShortening/MessagingService/MGXXX/DomainConfig"
}