Introducing the Copilot API for Programmable SMS


It’s simple to send a single text message using Twilio. However once you launch your application and start sending a high volume of messages, things can get complex in a hurry. It becomes essential to build logic to handle things that directly affect your software’s performance.

For example, when sending messages, you’ll want to consider:

  • How many phone numbers do you need? If you’re seeing too many messages in your Message Queue, try spreading out that traffic over several numbers.
  • Which country to choose when selecting a phone number for delivery?
  • Short code or standard long code phone number? Depending on which country and carrier you’re sending to, your application may need to keep track of whether to use a short code or standard SMS-enabled long code.
  • Alphanumeric Sender ID or numeric number? Setting your brand name as the Alpha Sender ID makes your brand identifiable to your customers (e.g. “TWILIO”). However, customers won’t be able to reply to messages sent with an Alpha Sender ID as they’re one-way.

To help you with this, we brought you Copilot, a tool available in the Console that allows you to organize your numbers into Messaging Services, then enable or disable specific features for groups of messages. A Messaging Service contains the configuration options for your application, such as the URLs that will be requested when you receive an incoming message on one of your numbers.

Once configured, the Messaging Service intelligently selects the best phone number to send from for any given message, and formats that message based on ever-changing carrier requirements…automatically!

Double-byte characters and emojis rejoice!

Today, we’re excited to introduce the Copilot API beta. You can do all of the same things that Copilot did before, but now you can do it…programmatically!

No matter if you choose to configure Copilot via the Console or the API, you’ll get the same great intelligence powering your app.

How Copilot selects the best phone numbers

Copilot is great for instances when you need to achieve higher throughput. It can automatically spread out traffic over multiple numbers and improve response rates for your messages by using the same local recognizable number for each person.

Copilot does this using the following four features:

  • Geo-Match: Selecting local phone numbers to create a local, familiar experience for your users.
  • Sticky Sender: Using the same recognizable number to send messages from in order to maintain conversation history.
  • Scaler: Distributing messages across a group of numbers to reach large audiences in a short amount of time.
  • Reroute: Reverting to standard long code phone numbers when a carrier is unable to receive messages from short codes.

Sound good so far? If so, getting started with the Copilot API is easy. Let’s next take a look at how.

1. Create a Messaging Service

Before Copilot can intelligently select the phone numbers to send your messages and apply message content changes, a Messaging Service must first be created. The Messaging Service resource holds all the configurations you want applied to your messages.

Here’s how to create a Messaging Service:

You’ll also want to make sure to set the StatusCallback property because any phone number validation errors, message delivery updates, and queuing errors will be sent via webhook to your application through this URL. This will let you know when your messages are delivered, if your message fails, and if there are any errors you may be experiencing.

Upon creating a Messaging Service, some of the 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.

2. Add phone numbers to the Messaging Service

Once your Messaging Service has been created, you’ll need to add phone numbers, short codes, or an Alpha Sender ID to the Service to be able to send from it. This provides Copilot with the numbers or Alphanumeric Sender ID’s to select when sending your messages.

To add phone numbers to your Messaging Service, you first need to purchase the phone numbers for your Account. If you haven’t purchased any phone numbers yet, start by buying numbers here or alternatively you can use the Incoming Phone Numbers API to buy numbers through the API.

For carrier compliance, messages to the US and CA via long codes will be automatically rate limited at the rate of about 1 message per second. To make sure your Messaging Service can handle your volume, go ahead and add a few numbers to your Messaging Service and it will automatically distribute your traffic over all the phone numbers in the Service.

Copilot’s Geomatch will select the phone number that is local to your user, if a matching local country number is available. By adding local numbers in UK, Germany and Australia your British, German, and Australian customers will now receive messages from a local number and be able to respond without international charges.

To add multiple numbers you need to make a request to Twilio for each number you want to add. Customers that want to do this in bulk can write a loop, however each Messaging Service is limited to 100 long code phone numbers. For more information on this, view the docs.

Wrap up

Copilot offers a global routing and delivery system that you can count on, without requiring ongoing attention – or engineering resources. Now that power is available with the public beta of the Copilot API, which gives you programmatic access to Copilot’s Geo-match, Sticky Sender, Scaler, and Reroute features.

Now go and let your messages fly with the Copilot API!

Have any questions about the Copilot API or anything else? Feel free to reach out at @thedonniew on Twitter.

We can’t wait to see what you build – programmatically!