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.
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
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.
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.
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.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createService() {11const service = await client.messaging.v1.services.create({12friendlyName: "My First Messaging Service",13});1415console.log(service.sid);16}1718createService();
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}
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:
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createPhoneNumber() {11const phoneNumber = await client.messaging.v112.services("MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")13.phoneNumbers.create({14phoneNumberSid: "PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",15});1617console.log(phoneNumber.sid);18}1920createPhoneNumber();
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}
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.
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.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createMessage() {11const message = await client.messages.create({12body: "Hello from your Messaging Service!",13messagingServiceSid: "MG9752274e9e519418a7406176694466fa",14to: "+15553332222",15});1617console.log(message.body);18}1920createMessage();
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}
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.
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.
Ready to build? Check out the following resources: