Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Sending Messages with Messaging Services

Public Beta
Twilio's Messaging Services API is currently available as a Public Beta product. Some features are not yet implemented and others may be changed before the product is declared as Generally Available.
Public Beta products are not covered by a Twilio SLA.

Sending a single message with Twilio is simple. But once we launch our application in the US and globally, at scale, our application will need to decide which identity (phone number, shortcode, or alpha sender ID) to use to send the message. We may want to spread our messaging traffic over several US phone numbers or prioritize an alpha sender ID when sending messages to countries where alpha senders are commonly used.

Instead of attempting to handle this number selection logic in our application, we can use a Twilio Messaging Service. When enabled, the Messaging Services features improve the performance of our application's messages. To use these features, first we'll need to setup a Messaging Service, where we'll define the feature configuration.

In this guide, we'll walk through

  • setting up our Messaging Service, via the REST API.
  • send messages with the Service, instead of specifying the phone number ourselves

Twilio's Messaging Service will select the best identity, either a phone number or an alpha sender ID, to send our messages in the US and globally.

Alternatively, Messaging Services can be configured through the Twilio Console when logged in. This is valuable when we want to make configuration changes to our application in the future without deploying any code.

Let’s dive into setting up a Messaging Service.

Create a Messaging Service

First, we will create a Messaging Service before enabling features such as intelligent number selection and messaging content changes. The Service resource holds all of the configurations that we want to apply to our messages.

Here is how we’ll create a Messaging Service:


        We’ll also want to make sure we set the Status Callback property because any phone number validation errors, message delivery updates, and queuing errors will be webhooked to our application through this URL. This will let us know when our messages are delivered, and if our message fails, the errors we may be experiencing.

        Upon creating a Service, some of our Service configuration will be set by default. For more detail about all the properties of a Service and these default settings, take a look at our Service Resource Reference.

        Add phone numbers to a Service

        Once our Service has been created, we’ll need to add phone numbers, short codes or an Alpha Sender ID to the Service. This provides the Service with the identities to select when sending our messages.


              To add phone numbers to our Service, we first purchased the numbers to our Account. If you haven’t purchased any phone numbers yet, use the Incoming Phone Numbers API first to buy a few phone numbers.

              Since we’ll be sending messages to the US and CA, our messages will be throttled at the rate of about 1 message per second. To make sure our Service can handle our volume, we’ll want to add a few numbers. The Scaler feature will distribute our traffic over all our phone numbers.

              We’ll also add a few UK and Australian phone numbers for our users in those countries. Geomatch will select the phone number that is local to a given user, if available. So your British and Australian customers will now receive messages from the country that matches their phone numbers.


                    List phone numbers in a Service

                    Let’s double check and confirm all the phone numbers in our Service.


                          Adding an Alpha Sender ID

                          Since we’ll be sending messages to countries where branded messages are popular we’ll also want to add an Alpha Sender ID. This allows our users to quickly identify our messages upon receiving them.

                          Sending messages with a Messaging Service

                          Now that our Messaging Service is all configured, we ready to start sending messages! At the moment to send messages we'll need to make requests to Twilio's 2010-04-01 API version to send messages.


                                Receive Message Status Updates

                                As our message is getting delivered, Twilio will be making webhook requests to our Status Callback URL to let us know the delivery status of our message.

                                If we happen to send a message to an invalid phone number, we’ll see an error in the webhook.

                                      Twilio sends this webhook request to our Status Callback URL to let us know the delivery status of the message.

                                      Message Delivery Status

                                      Twilio sends this webhook request to our Status Callback URL to let us know the delivery status of the message.

                                      Removing a phone number

                                      Let’s say we have a phone number that we no longer need in this Service. We can go ahead and remove the phone number.


                                            Since the number is still owned by my account, we can now assign it to any other Service.

                                            Now you know all about creating and configuring your Messaging Service and sending messages that are enhanced by the Service features.

                                            Rate this page:

                                            Need some help?

                                            We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.