Send SMS Messages with Copilot in Node.js

Messaging Copilot improves your customers' SMS message experience with routing and content intelligence features that you can control from the Twilio console. This guide will help you understand what Copilot can do for you and show you how to send SMS messages with Copilot in your Node.js application. The code snippets in this guide are written using modern JavaScript language features in Node.js version 6 or higher, and make use of the Twilio Node.js SDK.

Let's get started!

Copilot Features

So what can Copilot do for you? Let's dive into some of the features:

Sticky Sender

Sticky Sender makes sure the same From phone number is selected when messaging a particular recipient. This allows your application to consistently send messages to your user from a single recognizable phone number.

When Sticky Sender is enabled, Twilio will maintain a mapping of the To and From phone numbers. This mapping is created after the first message is sent from your Messaging Service to a particular recipient. Any future messages sent to that recipient from that Messaging Service will also use the same From number.

If Sticky Sender is turned off, any established mapping will not be referenced. However, if you toggle Sticky Sender back on in the future, any mappings previously created will be referenced again.

When a Twilio phone number is removed from your Messaging Service, all Sticky Sender mappings associated to the removed Twilio number are deleted.

Alpha Sender ID

For branded one-way messaging, many countries allow an alphanumeric string as the sender ID. Alpha Sender ID allows you to add your company name or brand to your Messaging Service. When sending messages to a country where an alphanumeric sender ID is accepted, Twilio will use your Alpha Sender ID as the From parameter to deliver your message. A phone number from your Messaging Service will be selected if your recipient is in a country where alphanumeric sender IDs are not supported.

Alpha Sender IDs may be up to 11 characters. Accepted characters include both upper- and lower-case ASCII letters, the digits 0 through 9, and space: [A-Za-z0-9 ].

Please email help@twilio.com to enable alphanumeric sender IDs for your account before using Alpha Sender ID.

Scaler

Scaler distributes your outbound messaging traffic evenly across the phone numbers in your Messaging Service to help you handle higher messaging volume. When a message is sent from your Messaging Service, the From number is selected from among the phone numbers not currently being used to send a message.

When Sticky Sender is enabled, Copilot will prioritize any existing Sticky Sender mappings first then select the next available phone number from your Messaging Service that has the least amount of mappings.

Geomatch

Geomatch automatically selects the Twilio phone number in your Messaging Service to match the country of your recipient’s phone number. If your Service does not include a Twilio phone number that is local to your user, Twilio will first attempt to select a SMS-enabled US phone number before falling back to another SMS-enabled phone number to deliver your message. Your message will fail if there are no phone numbers in your Service that can deliver your message.

To use Geomatch, simply add phone numbers to your Messaging Service that match the countries of your end users. Geomatch is disabled when a phone number local to your recipient cannot be found in your Messaging Service.

Geographic proximity and area codes are not taken into consideration when selecting a phone number.

When a phone number of a new geographic country is added to your Messaging Service, Twilio will automatically select and remap Sticky Sender so that the From number can match the same country as your recipient's phone number.

Shortcode Reroute

When your Messaging Service includes a shortcode, Twilio will always prioritize message delivey with the shortcode. If a carrier is not supported by a Twilio short code, Twilio will automatically deliver the message with a long code in your Messaging Service.

Please note, shortcode reroute, does not attempt to redeliver your message over a long code due to a Failed or Undelivered delivery status.

MMS Converter

MMS Converter will automatically deliver your MMS message as a SMS text message with a shortened URL linking to your image when the carrier is not supported to receive Twilio MMS Messages. The shortened URL link (http://m.twil.io/ followed by 7 unique characters) is appended to the end of the message body and will remain active for 365 days.

Messages sent this way will be billed as SMS messages. If the appended URL causes the body of the text message to be greater than 160 characters, the message will be segmented and charged accordingly.

This functionality is toggled on by default for all messages sent without a Messaging Service.

MMS Converter sends links to media via SMS where the receiving carrier does not support MMS. This will not enable you to send media if your 'From' phone number lacks MMS capabilities.

 

You can check the capabilities of numbers in the console or query the Available Phone Numbers resource to search for Twilio numbers that are MMS enabled.

Intelligent Number Selection with Copilot

When Sticky Sender is enabled, Twilio's Copilot Features will follow the logic below to determine the optimal phone number to send your message from.

Copilot Number Selection Diagram

Not yet using Twilio to send SMS messages? Sign up now!

Configure a Messaging Service

A Messaging Service contains configuration options for your application, like the URLs that will be requested when you receive an incoming message on one of your numbers. It also contains the configuration for your Copilot messaging features.

Create a Messaging Service for your account here.

You will also need to buy one or more phone numbers and add them to the messaging service. Once you have at least one phone number added to the service, you can use it to send messages.

Send SMS Message with Copilot

Sending a message with Copilot is a lot like 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.

Once you create a Messaging Service in the console, you can use its SID as the MessagingServiceSid parameter in your API request.

You must associate at least one phone number with your messaging service before it will be able to send messages.

Loading Code Samples...
Language
SDK Version:
  • 2.x
  • 3.x
Format:
  • JSON
  • XML
// Download the Node helper library from twilio.com/docs/node/install
// These vars are your accountSid and authToken from twilio.com/user/account
const accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
const authToken = 'your_auth_token';
const client = require('twilio')(accountSid, authToken);

client.sendMessage(
  {
    messagingServiceSid: 'MG9752274e9e519418a7406176694466fa',
    to: '+441632960675',
    body: 'Phantom Menace was clearly the best of the prequel trilogy.',
  },
  (err, message) => {
    console.log(message);
  }
);
// Download the Node helper library from twilio.com/docs/node/install
// These consts are your accountSid and authToken from https://www.twilio.com/console
const accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
const authToken = 'your_auth_token';
const client = require('twilio')(accountSid, authToken);

client.messages
  .create({
    messagingServiceSid: 'MG9752274e9e519418a7406176694466fa',
    to: '+441632960675',
    body: 'Phantom Menace was clearly the best of the prequel trilogy.',
  })
  .then(message => console.log(message));
{
  "sid": "SM18c9444687c240caa8b54dc9a22e14d8",
  "date_created": "Tue, 03 Nov 2015 20:26:16 +0000",
  "date_updated": "Tue, 03 Nov 2015 20:26:16 +0000",
  "date_sent": null,
  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "to": "+441632960675",
  "from": null,
  "messaging_service_sid": "MG9752274e9e519418a7406176694466fa",
  "body": "Phantom Menace was clearly the best of the prequel trilogy.",
  "status": "accepted",
  "num_segments": "0",
  "num_media": "0",
  "direction": "outbound-api",
  "api_version": "2010-04-01",
  "price": null,
  "price_unit": null,
  "uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SM18c9444687c240caa8b54dc9a22e14d8.json",
  "subresource_uris": {
    "media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SM18c9444687c240caa8b54dc9a22e14d8/Media.json"
  }
}
<?xml version='1.0' encoding='UTF-8'?>
<TwilioResponse>
    <Message>
        <Sid>SM802a848d6e5948aea0a2780200f70825</Sid>
        <DateCreated>Tue, 03 Nov 2015 20:28:44 +0000</DateCreated>
        <DateUpdated>Tue, 03 Nov 2015 20:28:44 +0000</DateUpdated>
        <DateSent/>
        <AccountSid>ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</AccountSid>
        <To>+441632960675</To>
        <From/>
        <MessagingServiceSid>MG9752274e9e519418a7406176694466fa</MessagingServiceSid>
        <Body>Phantom Menace was clearly the best of the prequel trilogy.</Body>
        <Status>accepted</Status>
        <NumSegments>0</NumSegments>
        <NumMedia>0</NumMedia>
        <Direction>outbound-api</Direction>
        <ApiVersion>2010-04-01</ApiVersion>
        <Price/>
        <PriceUnit/>
        <Uri>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SM802a848d6e5948aea0a2780200f70825.xml</Uri>
        <SubresourceUris>
            <Media>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SM802a848d6e5948aea0a2780200f70825/Media.xml</Media>
        </SubresourceUris>
    </Message>
</TwilioResponse>
Send a Message with Copilot
David Prothero
Jose Oliveros
Jarod Reyes
Kat King

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.

1 / 1
Loading Code Samples...
SDK Version:
  • 2.x
  • 3.x
Format:
  • JSON
  • XML
// Download the Node helper library from twilio.com/docs/node/install
// These vars are your accountSid and authToken from twilio.com/user/account
const accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
const authToken = 'your_auth_token';
const client = require('twilio')(accountSid, authToken);

client.sendMessage(
  {
    messagingServiceSid: 'MG9752274e9e519418a7406176694466fa',
    to: '+441632960675',
    body: 'Phantom Menace was clearly the best of the prequel trilogy.',
  },
  (err, message) => {
    console.log(message);
  }
);
// Download the Node helper library from twilio.com/docs/node/install
// These consts are your accountSid and authToken from https://www.twilio.com/console
const accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
const authToken = 'your_auth_token';
const client = require('twilio')(accountSid, authToken);

client.messages
  .create({
    messagingServiceSid: 'MG9752274e9e519418a7406176694466fa',
    to: '+441632960675',
    body: 'Phantom Menace was clearly the best of the prequel trilogy.',
  })
  .then(message => console.log(message));
{
  "sid": "SM18c9444687c240caa8b54dc9a22e14d8",
  "date_created": "Tue, 03 Nov 2015 20:26:16 +0000",
  "date_updated": "Tue, 03 Nov 2015 20:26:16 +0000",
  "date_sent": null,
  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "to": "+441632960675",
  "from": null,
  "messaging_service_sid": "MG9752274e9e519418a7406176694466fa",
  "body": "Phantom Menace was clearly the best of the prequel trilogy.",
  "status": "accepted",
  "num_segments": "0",
  "num_media": "0",
  "direction": "outbound-api",
  "api_version": "2010-04-01",
  "price": null,
  "price_unit": null,
  "uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SM18c9444687c240caa8b54dc9a22e14d8.json",
  "subresource_uris": {
    "media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SM18c9444687c240caa8b54dc9a22e14d8/Media.json"
  }
}
<?xml version='1.0' encoding='UTF-8'?>
<TwilioResponse>
    <Message>
        <Sid>SM802a848d6e5948aea0a2780200f70825</Sid>
        <DateCreated>Tue, 03 Nov 2015 20:28:44 +0000</DateCreated>
        <DateUpdated>Tue, 03 Nov 2015 20:28:44 +0000</DateUpdated>
        <DateSent/>
        <AccountSid>ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</AccountSid>
        <To>+441632960675</To>
        <From/>
        <MessagingServiceSid>MG9752274e9e519418a7406176694466fa</MessagingServiceSid>
        <Body>Phantom Menace was clearly the best of the prequel trilogy.</Body>
        <Status>accepted</Status>
        <NumSegments>0</NumSegments>
        <NumMedia>0</NumMedia>
        <Direction>outbound-api</Direction>
        <ApiVersion>2010-04-01</ApiVersion>
        <Price/>
        <PriceUnit/>
        <Uri>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SM802a848d6e5948aea0a2780200f70825.xml</Uri>
        <SubresourceUris>
            <Media>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SM802a848d6e5948aea0a2780200f70825/Media.xml</Media>
        </SubresourceUris>
    </Message>
</TwilioResponse>