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 Copilot

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 Twilio’s Copilot. When enabled Twilio's Copilot features will assist our application to improve the performance of our messages. To use Twilio's Copilot features, first we'll need to setup a Messaging Service, where we'll define our Copilot configuration.

In this guide, we'll walk through setting up our Messaging Service, via the REST API. Once configured, we'll use our Messaging Service to send messages instead of specifying the phone number ourselves. Twilio's Copilot will then 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 extremely 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

Before Copilot can intelligently select the phone numbers to send your messages and applying message content changes, a Service must first be created. The Service resource holds all the configurations we want applied 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 Copilot 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. Copilot’s Scaler will help 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. Copilot’s Geomatch will select the phone number that is local to my user, if available. So my British and Australian customer will now receive messages from the country that matches their phone number.


                    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 Copilot

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

                                            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.