Send Messages with Messaging Services

Sending messages at a high volume and/or at a global scale quickly balloons in complexity. That's why Twilio Programmable Messaging encourages the use of Messaging Services to manage your senders, maintain compliance with local carrier regulations, and create a smooth and consistent messaging experience for your end users.

Some Messaging Service features include:

• Sticky Sender: Use the same From phone number to message a given customer for a consistent experience
• Smart Encoding: Save space (and money!) by automatically converting hard-to-catch Unicode characters to UCS-2 compliant characters
• MMS Converter: Automatically convert links to media files for areas in which MMS is not supported
• Advanced Opt-Out: Manage your opt-out, opt-in, and help keywords and messages
• Sender ID pre-registration alert: Get notifications when you are sending messages in countries that require pre-registration of your Alphanumeric Sender ID
• ...and more!

For more information, check out the Messaging Service Overview page.

You can create a Messaging Service through the Twilio Console or using the REST API with the following code:

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 createService() {
11
  const service = await client.messaging.v1.services.create({
12
    friendlyName: "My First Messaging Service",
13
  });
14

15
  console.log(service.sid);
16
}
17

18
createService();

1
{
2
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
  "sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4
  "date_created": "2015-07-30T20:12:31Z",
5
  "date_updated": "2015-07-30T20:12:33Z",
6
  "friendly_name": "My First Messaging Service",
7
  "inbound_request_url": "https://www.example.com/",
8
  "inbound_method": "POST",
9
  "fallback_url": "https://www.example.com",
10
  "fallback_method": "GET",
11
  "status_callback": "https://www.example.com",
12
  "sticky_sender": true,
13
  "smart_encoding": false,
14
  "mms_converter": true,
15
  "fallback_to_long_code": true,
16
  "scan_message_content": "inherit",
17
  "area_code_geomatch": true,
18
  "validity_period": 600,
19
  "synchronous_validation": true,
20
  "usecase": "marketing",
21
  "us_app_to_person_registered": false,
22
  "use_inbound_webhook_on_number": true,
23
  "sending_windows": [],
24
  "links": {
25
    "phone_numbers": "https://messaging.twilio.com/v1/Services/MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/PhoneNumbers",
26
    "short_codes": "https://messaging.twilio.com/v1/Services/MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ShortCodes",
27
    "alpha_senders": "https://messaging.twilio.com/v1/Services/MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AlphaSenders",
28
    "messages": "https://messaging.twilio.com/v1/Services/MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages",
29
    "us_app_to_person": "https://messaging.twilio.com/v1/Services/MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Compliance/Usa2p",
30
    "us_app_to_person_usecases": "https://messaging.twilio.com/v1/Services/MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Compliance/Usa2p/Usecases",
31
    "channel_senders": "https://messaging.twilio.com/v1/Services/MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ChannelSenders",
32
    "destination_alpha_senders": "https://messaging.twilio.com/v1/Services/MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/DestinationAlphaSenders"
33
  },
34
  "url": "https://messaging.twilio.com/v1/Services/MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
35
}

Take note of the Messaging Service SID (a string starting with MGXX) that the code prints to your console: you need this SID in future steps in this guide.

Sending SMS messages requires an SMS capable phone number. You can search for and purchase available phone numbers in the Console. When you search, make sure that the number you choose is SMS capable. Check the appropriate box in the search UI to filter available numbers to those that are SMS capable.

Expand image

When viewing the search results, you can see the which numbers are SMS capable.

Expand image

With your shiny new Twilio phone number, you can start sending messages to mobile devices.

Now, associate your Twilio number with the Messaging Service that you created.

You can do this in the Twilio Console in the Senders section under your Messaging Service. Click the Add Senders button, select the Sender Type, and assign the senders to your Messaging Service.

You can also use the Messaging Services REST API to add the Phone Number you purchased to your sender pool. To do this, you will need the Phone Number's unique SID, which starts with PNXXX. You can find this in the Phone Numbers Section of the Twilio Console.

Expand image

Use the Phone Number's SID and your Messaging Service's SID to attach your Twilio number to the Messaging Service that you created:

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 createPhoneNumber() {
11
  const phoneNumber = await client.messaging.v1
12
    .services("MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13
    .phoneNumbers.create({
14
      phoneNumberSid: "PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
15
    });
16

17
  console.log(phoneNumber.sid);
18
}
19

20
createPhoneNumber();

1
{
2
  "sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4
  "service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
5
  "date_created": "2015-07-30T20:12:31Z",
6
  "date_updated": "2015-07-30T20:12:33Z",
7
  "phone_number": "+987654321",
8
  "country_code": "US",
9
  "capabilities": [
10
    "MMS",
11
    "SMS",
12
    "Voice"
13
  ],
14
  "url": "https://messaging.twilio.com/v1/Services/MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/PhoneNumbers/PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
15
}

Sending a message with a Messaging Service is a lot like sending a message from a Twilio number, with one key difference. Instead of specifying a From telephone number in your API request, you specify a Messaging Service SID, its unique identifier.

In this example, we'll use the Messaging Service SID (it starts with MGXX) of the Messaging Service that we just created.

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: "Hello from your Messaging Service!",
13
    messagingServiceSid: "MG9752274e9e519418a7406176694466fa",
14
    to: "+15553332222",
15
  });
16

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

20
createMessage();

1
{
2
  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3
  "api_version": "2010-04-01",
4
  "body": "Hello from your Messaging Service!",
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": "+14155552345",
12
  "num_media": "0",
13
  "num_segments": "1",
14
  "price": null,
15
  "price_unit": null,
16
  "messaging_service_sid": "MG9752274e9e519418a7406176694466fa",
17
  "sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18
  "status": "queued",
19
  "subresource_uris": {
20
    "media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"
21
  },
22
  "tags": {
23
    "campaign_name": "Spring Sale 2022",
24
    "message_type": "cart_abandoned"
25
  },
26
  "to": "+15553332222",
27
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
28
}

Run the code sample, replacing the Messaging Service SID with the SID you created earlier, and the To number with your own mobile phone number. In a few seconds, you should receive an SMS message!

You can check the health of your Messaging Service by reviewing the Messaging Insights and Messaging logs.

When you use a Messaging Service, some API requests that result in a 400 Bad Request don't include the error in the initial response. Twilio performs preliminary validation on the API request before accepting it, and then attempts to send the message. If Twilio is unable to send the message, then Twilio marks the message as Failed and logs an error. You can find the error in Messaging logs and Insights.

For outbound messages, Messaging logs and Insights include the Messaging Service only if you specify the MessageServiceSid in your message request. If you don't include the MessageServiceSid, the Service isn't recorded in the message record, even if the From number belongs to a Messaging Service.

For inbound messages, if the Twilio number is assigned to a Messaging Service, that Service will appear in Messaging logs and Insights.

Sending an SMS or WhatsApp message using a Twilio Messaging Service sets you up for efficient scaling. As your messaging needs grow, your Messaging Service will automatically handle the multiple senders in your pool as well as maintain consistent interactions with your end users around the world.

Ready to build more? Check out the following resources:

• The Service Resource in the Messaging Services REST API
• Messaging Service Overview
• Onboard your WhatsApp Business Account to send WhatsApp messages with Twilio
• How to Configure Advanced Opt-Out keywords for your Messaging Service