Get started with Messaging Services

Messaging Services bundle messaging features and configuration for a defined pool of senders (long code numbers, short codes, toll-free numbers, and so on). Use Messaging Services to group and manage your messaging use cases at scale. Create a Messaging Service through the Twilio Console or using the Messaging Services API.

Learn more about what you can do with Messaging Services.

Prerequisites

You can run the following code samples in your local development environment (recommended), with the Twilio CLI, or using curl commands in your terminal.

A local development environment for your preferred programming language
A Twilio account
A Twilio phone number

Get a Twilio phone number

If you don't have a Twilio phone number with SMS functionality, you'll need to purchase one. In the Twilio Console, navigate to the Buy a Number page, check the SMS box, enter your search criteria, and click Search.

From the list of available phone numbers, choose a number and click Buy to add it to your account.

(warning)

Sending messages to the US and Canada

Sending messages to the United States with a Twilio trial account requires a toll-free number. To use a toll-free number to message recipients in the US or Canada, you must complete toll-free verification.

To use a 10-digit long code (10DLC) number to message recipients in the US, you must upgrade your account and complete A2P 10DLC registration. Learn more about A2P 10DLC registration.

A2P 10DLC registration isn't required to send messages outside of the United States.

Create a Messaging Service with the Messaging Services API

When you create the Messaging Service, take note of the Messaging Service SID (a string starting with MGXX) that the code prints to your console to use in the next step.

Create a Messaging Service

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async 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
18createService();

Response

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}

Add a number to the Messaging Service Sender Pool

You can use the Messaging Services API to add Phone Number to your Sender Pool. Get the unique Phone Number SID (starts with PNXXX) from the Phone Numbers section of the Twilio Console.

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

Add a phone number to the Sender Pool

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async 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
20createPhoneNumber();

Response

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}

(warning)

Sender Pool configuration required

You must add at least one phone number or channel address to the Sender Pool for your Messaging Service before it can send messages.

Send a message using the Messaging Services API

Sending a message with a Messaging Service is similar to 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.

This example uses the Messaging Service SID (it starts with MGXX) of the Messaging Service created in the previous step. To run the code sample, replace the Messaging Service SID with your own, and the To number with your own mobile phone number. In a few seconds, you should receive an SMS message.

Send a Message with a Messaging Service

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async 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
20createMessage();

Response

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}

Create a Messaging Service with the Twilio Console

In the Twilio Console, go to Messaging > Services and click Create Messaging Service.

The console guides you through adding a number to the Sender Pool, integration with your application, and A2P 10DLC compliance if applicable.

Insights and troubleshooting

To check the health of your Messaging Service, review Messaging Insights and Messaging logs.

When you use a Messaging Service, API requests that result in a 400 Bad Request might not include the error in the initial response. Twilio performs preliminary validation on the request before accepting it, and then attempts to send the message. If the message can't be sent, 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 record the Messaging Service only if you specify the MessageServiceSid in your request. If you don't include the MessageServiceSid, the Service isn't included in the message record, even if the From number belongs to a Messaging Service.

For inbound messages, if your Twilio number is assigned to a Messaging Service, that Service appears in Messaging logs and Insights.

What's Next?

Ready to build? Check out the following resources: