Send SMS and MMS Messages in Node.js

Before you can send messages from the Twilio API, you'll need a Twilio account and a Twilio-powered phone number.

If you're brand new to Twilio, you can sign up for a free trial account to get started.

Once you've signed up and selected a project (the "Learn and Explore" template will work for this tutorial), head over to your Console and get your Account SID and Auth Token. You will need those values for the code samples below.

Sending messages requires a Twilio phone number with SMS capabilities. If you don't currently own a Twilio phone number with SMS capabilities, you'll need to buy one. After navigating to the Buy a Number page, check the 'SMS' box and click 'Search':

Expand image

If you live in the US or Canada and also wish to send MMS messages, you can select the 'MMS' box. When viewing the search results, you can see the capability icons in the list of available numbers:

Expand image

Find a number you like and click "Buy" to add it to your account.

Now that you have a Twilio phone number you can start sending messages to mobile devices.

To send an outgoing SMS message from your Twilio account, you'll need to make an HTTP POST request to Twilio's Message resource.

Twilio's helper library for Node.js helps you create a new instance of the Message resource, specifying the To, From, and Body parameters of your message.

If you don't already have the Node helper library installed, you can do so using npm:

npm install twilio

This will install the twilio module so that Node.js scripts in the current directory can use it.

Now, create a file named sms.js and include the following code.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function createMessage() {
11
  const message = await client.messages.create({
12
    body: "This is the ship that made the Kessel Run in fourteen parsecs?",
13
    from: "+15017122661",
14
    to: "+15558675310",
15
  });
16

17
  console.log(message.body);
18
}
19

20
createMessage();

1
{
2
  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3
  "api_version": "2010-04-01",
4
  "body": "This is the ship that made the Kessel Run in fourteen parsecs?",
5
  "date_created": "Thu, 30 Jul 2015 20:12:31 +0000",
6
  "date_sent": "Thu, 30 Jul 2015 20:12:33 +0000",
7
  "date_updated": "Thu, 30 Jul 2015 20:12:33 +0000",
8
  "direction": "outbound-api",
9
  "error_code": null,
10
  "error_message": null,
11
  "from": "+15017122661",
12
  "messaging_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
13
  "num_media": "0",
14
  "num_segments": "1",
15
  "price": null,
16
  "price_unit": null,
17
  "sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18
  "status": "queued",
19
  "subresource_uris": {
20
    "media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"
21
  },
22
  "tags": null,
23
  "to": "+15558675310",
24
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
25
}

Replace the placeholder values for accountSid and authToken with your unique values. You can find these in your Twilio console.

You'll tell Twilio which phone number to use to send this message by replacing the from number with the Twilio phone number you purchased earlier.

Next, specify yourself as the message recipient by replacing the to number with your mobile phone number. Both the from and to parameters must use E.164 formatting ("+" and a country code, e.g., +16175551212).

We also include the body parameter, which contains the content of the SMS we're going to send.

Once you've updated the code sample, you can test it out by running it from the command line:

node sms.js

In just a few moments you should receive an SMS!

Let's take a moment to understand what's going on behind the scenes when you send this request to Twilio.

When Twilio receives your request to send an SMS via the REST API, it will check that you've included a valid Twilio phone number in the From field. Twilio will then either queue the SMS or return this HTTP error in its response to your request.

Expand image

Assuming your request didn't result in any errors, Twilio's HTTP response will include the SID of the new message. This unique identifier will help us reference this message later: in the code above, we printed that SID to the terminal.

Twilio's JSON response includes a robust amount of data about your message. A sample response might look like this:

1
{
2
  "accountSid":"ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3
  "apiVersion":"2010-04-01",
4
  "body":"This is the ship that made the Kessel Run in fourteen parsecs?",
5
  "dateCreated":"2018-09-11T17:29:05.000Z",
6
  "dateUpdated":"2018-09-11T17:29:05.000Z",
7
  "dateSent":null,"direction":"outbound-api",
8
  "errorCode":null,
9
  "errorMessage":null,
10
  "to":"+15558675310",
11
  "from":"+15017122661",
12
  "messagingServiceSid":null,"numMedia":"0",
13
  "numSegments":"1",
14
  "price":null,"priceUnit":"USD",
15
  "sid":"SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
16
  "status":"queued",
17
  "uri":"/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX7/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json",
18
  "subresourceUris":{
19
    "media": null
20
  }
21
}
22

You can access any of these attributes from your Node.js code, much like we did when we logged the message.sid.

Try updating the existing logging statement in your code to be .then(message => console.log(message.status)) instead. Save the file, then run the code again. You should see the status of your message, "queued", printed to your terminal.

If you receive an error in response from Twilio or never receive the message, you may want to check out these tips for troubleshooting undelivered messages.

If you want to send a message to several recipients, you could create a list of recipients (or get a list from a database) and iterate through each phone number in the list:

1
var numbersToMessage = ["+15558675310", "+14158141829", "+15017122661"]
2

3
numbersToMessage.forEach(function(number){
4
  var message = client.messages.create({
5
    body: 'This is the ship that made the Kessel Run in fourteen parsecs?',
6
    from: '+16468635472',
7
    to: number
8
  })
9
  .then(message =>  console.log(message.status))
10
  .done();
11
});

This will create a new Message instance for each phone number in the list.

As you send more messages via the API, Twilio will queue them up for delivery at your prescribed rate limit. API requests for messages that exceed the specified rates will be queued and executed as capacity is available.

If your application tries to enqueue more than 4 hours worth of outbound traffic (e.g., enqueuing more than 14,400 messages to Canada over one long code phone number), the API will start returning 429 errors.

If you need to enqueue a large volume of messages, you may find that it's helpful to leverage Twilio's Messaging Services. See our guide on how to set up and send messages from a messaging service in your language of choice for more tips.

To include media in your Twilio-powered text message, you need to make an addition to the code we wrote above. This time, we need to add the mediaUrl parameter.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function createMessage() {
11
  const message = await client.messages.create({
12
    body: "This is the ship that made the Kessel Run in fourteen parsecs?",
13
    from: "+15017122661",
14
    mediaUrl: [
15
      "https://c1.staticflickr.com/3/2899/14341091933_1e92e62d12_b.jpg",
16
    ],
17
    to: "+15558675310",
18
  });
19

20
  console.log(message.body);
21
}
22

23
createMessage();

1
{
2
  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3
  "api_version": "2010-04-01",
4
  "body": "This is the ship that made the Kessel Run in fourteen parsecs?",
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": "+15017122661",
12
  "num_media": "0",
13
  "num_segments": "1",
14
  "price": null,
15
  "price_unit": null,
16
  "messaging_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
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": "+15558675310",
27
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
28
}

Again, update the from and to parameters to use your Twilio phone number and your mobile phone.

The new mediaUrl parameter in this code tells Twilio where to go to get the media we want to include. This must be a publicly accessible URL: Twilio will not be able to reach any URLs that are hidden or that require authentication.

Just as when you send an SMS, Twilio will send data about the message in its response to your request. The JSON response will contain the unique SID and URI for your media resource:

"subresourceUris": {"media": "/2010-04 01/Accounts/ACxxxxxxxx/Messages/SMxxxxxxxxxxxxx/Media.json"}

When the Twilio REST API creates your new Message resource, it will save the image found at the specified mediaUrl as a Media resource. Once created, you can access this resource at any time via the API.

You can print this value from your Node.js code to see where the image is stored. Update your sms.js file's console.log to see your newly provisioned Media URI:

console.log(message.subresourceUris.media)

Save the file and run your project. In just a moment you should receive a text message with an image and see the your new Media URI printed to your console.

You've now successfully sent some messages with the Twilio Programmable Messaging API and the Node.js helper library.

Check out these in-depth resources to take your programmatic messaging a step further:

• Learn how to send an SMS during an in-progress call with Node.js and Express.
• Monitor the status of your message to confirm its delivery.
• Learn how to reply to an SMS sent to your Twilio phone number.
• Learn how to manage message state to turn individual messages into a true SMS conversation.
• Dig into the details with our API reference documentation for Messages.
• Sending high-volume messages? Check out our messaging services.