Messaging Services

To create a Messaging Service, go to Messaging > Services in the Twilio Console and then Create Messaging Service. You will then:

1. Name the Messaging Service and select a use case
2. Add senders to the Messaging Service's sender pool
3. Set up the integration with your system
4. Add compliance info

To add senders to a Messaging Service that already exists, go to Messaging > Services in the Twilio Console, select a Messaging Service, and use Add Senders in the Sender Pool section.

In the Integration section of your Messaging Service, you can update how your Messaging Service handles incoming messages, set a status callback URL, or set a custom validity period.

By default, Twilio sets your Messaging Service to "Defer to sender's webhook," meaning inbound messages to any sender within the Messaging Service's sender pool will hit the webhook configured on each sender. However, you can instead configure the Messaging Service to use a common webhook set on the Messaging Service or have Twilio automatically create a new Conversation. Using the Autocreate a Conversation option requires additional configuration changes in the Conversations section of the Twilio Console.

The delivery status of your message, including any delivery errors, is 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.

You can customize the validity period for outbound messages — the number of seconds they remain in Twilio's platform before failing — between 1 and 36,000 seconds (default: 36,000).

If you use a Messaging Service to send a message, your request to Twilio is similar to sending an SMS with the REST API. However, instead of including a From phone number, include a MessagingServiceSid. When you send a message with a Messaging Service, Twilio immediately sets the message's status to accepted. The Messaging Service then automatically selects a From sender — see Sender selection for details.

The following example shows how to send a message with a Messaging Service:

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function createMessage() {
11
  const message = await client.messages.create({
12
    body: "Revenge of the Sith was the best of the prequel trilogy.",
13
    messagingServiceSid: "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
14
    to: "+18005550100",
15
  });
16

17
  console.log(message.body);
18
}
19

20
createMessage();

1
{
2
  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3
  "api_version": "2010-04-01",
4
  "body": "Revenge of the Sith was the best of the prequel trilogy.",
5
  "date_created": "Thu, 30 Jul 2015 20:12:31 +0000",
6
  "date_sent": "Thu, 30 Jul 2015 20:12:33 +0000",
7
  "date_updated": "Thu, 30 Jul 2015 20:12:33 +0000",
8
  "direction": "outbound-api",
9
  "error_code": null,
10
  "error_message": null,
11
  "from": null,
12
  "messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
13
  "num_media": "0",
14
  "num_segments": "1",
15
  "price": null,
16
  "price_unit": null,
17
  "sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18
  "status": "queued",
19
  "subresource_uris": {
20
    "media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"
21
  },
22
  "to": "+18005550100",
23
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
24
}

When sending a message, the Messaging Service selects a From sender from the pool by sender type, in this priority order:

1. RCS sender: See RCS Regional Availability to learn where RCS is supported.
2. Short code: See What carriers are supported on Twilio short codes.
3. Alphanumeric Sender ID: See International support for Alphanumeric Sender ID and Alphanumeric Sender IDs in Messaging Services.
4. Long code and toll-free phone numbers: In Canada, toll-free numbers are prioritized over long codes.

Within a sender type, the Messaging Service distributes traffic evenly by selecting a sender that isn't in use. Country Code Geomatch, Area Code Geomatch, and Sticky Sender can each further influence which specific sender is selected.

If you want to turn off automatic sender selection and still use other Messaging Service features (such as Advanced Opt-Out), specify both a MessagingServiceSid and From sender.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function createMessage() {
11
  const message = await client.messages.create({
12
    body: "Revenge of the Sith was the best of the prequel trilogy.",
13
    from: "+18005550199",
14
    messagingServiceSid: "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
15
    to: "+18005550100",
16
  });
17

18
  console.log(message.body);
19
}
20

21
createMessage();

1
{
2
  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3
  "api_version": "2010-04-01",
4
  "body": "Revenge of the Sith was the best of the prequel trilogy.",
5
  "date_created": "Thu, 24 Aug 2023 05:01:45 +0000",
6
  "date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",
7
  "date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",
8
  "direction": "outbound-api",
9
  "error_code": null,
10
  "error_message": null,
11
  "from": "+18005550199",
12
  "num_media": "0",
13
  "num_segments": "1",
14
  "price": null,
15
  "price_unit": null,
16
  "messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
17
  "sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18
  "status": "queued",
19
  "subresource_uris": {
20
    "media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"
21
  },
22
  "to": "+18005550100",
23
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
24
}

Country Code Geomatch is always active — it uses the country code of the recipient's phone number to select the best, most relevant sender. The fallback behavior when no matching sender is available differs by channel:

• SMS: If no matching number is available, Twilio first attempts to select a US number — since US SMS senders typically have higher international delivery rates — then falls back to any available number in the pool. The message fails if no numbers are available.
• RCS: If no matching RCS sender is available, Twilio selects any available RCS sender in the pool regardless of the sender's approved region(s), since RCS messages route over the internet.
• WhatsApp: If no matching WhatsApp sender is available, Twilio selects any available WhatsApp sender in the pool regardless of the sender's country, since WhatsApp messages also route over the internet.

You can use Country Code Geomatch by adding senders to your Messaging Service that match the countries of your recipients. For RCS senders, supported countries are determined by where the sender has been approved — you can view a sender's approved regions in RCS > Senders in the Twilio Console.

When an SMS- or MMS-capable sender supporting a new country code 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.

Sticky Sender 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 subsequent messages sent to that recipient from the Service also use the same From number.

Twilio treats SMS phone numbers and WhatsApp senders as separate entities, so Sticky Sender maintains independent mappings for each channel—even when the underlying phone number is the same.

If Sticky Sender is turned off, your Messaging Service ignores all previously established mappings. However, if you re-enable Sticky Sender, your Messaging Service retains and references the previously existing mappings.

In some cases, Twilio invalidates an existing mapping and re-runs sender selection. This happens when the stored sender fails routing validation — for example, if a short code or alphanumeric sender is no longer eligible for the recipient's region, or if a long code mapped to a US recipient fails A2P registration checks. When a mapping is invalidated, Twilio removes it and selects a new sender as if no mapping existed.

To turn on or turn off Sticky Sender, go to Sender Pool > Sender Selection Settings in your Messaging Service.

When Sticky Sender is enabled, the Messaging Service uses the following logic to determine the From number:

Expand image

Area Code Geomatch selects a local phone number with an area code that matches or overlaps your end-user's number.

If no matching or overlay area code is available, the Messaging Service selects another US or Canadian number. Twilio doesn't consider geographic proximity in this case.

To turn on or turn off Area Code Geomatch, go to Sender Pool > Sender Selection Settings in your Messaging Service.

When sending RCS messages with native fallback enabled in a Messaging Service, you can specify which SMS or MMS sender to use during fallback in two ways:

1. Single sender in the pool: Add exactly one SMS- or MMS-capable sender to your Messaging Service's sender pool. That sender is automatically used for fallback.
2. FallbackFrom parameter: Specify the fallback sender in the FallbackFrom parameter when sending your message. This lets you use any SMS- or MMS-capable number for fallback — even one that isn't in the Messaging Service's sender pool — as long as it belongs to the same Account SID.

Smart Encoding detects hidden Unicode characters and replaces them with a similar GSM-encoded character. This helps ensure that your message stays within the GSM-7 160-character-per-segment limit and prevents it from being split into two message segments, which increases your costs.

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. 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 is 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.

To turn on or turn off Smart Encoding, go to Content Settings in your Messaging Service.

MMS Converter automatically delivers MMS messages as SMS text messages when the carrier doesn't support receiving Twilio MMS Messages.

The MMS Converter transforms the MMS to an SMS message that contains a shortened URL linking to the media. The 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). The Messaging Service selects the most appropriate SMS-capable sender based on the recipient's location to improve message deliverability and compliance with local regulations.

To turn on or turn off MMS Converter, go to Content Settings in your Messaging Service.

Advanced Opt-Out lets you deliver a customized, end-to-end compliance experience for your users. You can set the opt-in, opt-out, and help keywords and confirmation messages globally, 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 status of your campaigns.

Advanced Opt-Out is not enabled by default. In 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.

For more information, see Customize users' opt-in and opt-out experience with Advanced Opt-Out.

If you no longer need a Messaging Service, you can delete it through the Twilio Console.

In the Console, go to Messaging Services, open the service you want to delete, then click Delete Messaging Service and confirm.