The ultimate guide to sending bulk SMS with Twilio and Node.js
Tags: twilio, sms, node, javascript
Published: 2018-01-16 02:28:21

---
title: The ultimate guide to sending bulk SMS with Twilio and Node.js
published: true
description: Sending an SMS with Twilio is a straightforward affair, but what if you had to send 10 messages? Or 10,000 SMS messages in bulk? Find out how in this post.
tags: twilio, sms, node, javascript
cover_image: https://www.twilio.com/blog/wp-content/uploads/2017/12/header.gif
canonical_url: https://www.twilio.com/blog/2017/12/send-bulk-sms-twilio-node-js.html
---

Sending a single SMS with Twilio is a relatively straightforward affair, but what if you had to send 10 messages? Or 10,000?

Imagine you're an ice cream seller. You want to improve business by sending SMS alerts when you're in your van so that your customers will know you're on your way to deliver some sweet refreshment.

<img src="https://twilioinc.wpengine.com/wp-content/uploads/2017/12/hot.png" alt="" width="300" height="250" class="alignright size-full wp-image-22456" alt="The iPhone weather app showing 31 degrees celsius in Brunswick" />

Look, I know what you're thinking: &ldquo;It's January, hardly time for ice cream!&rdquo; But, I'm in Melbourne right now enjoying a toasty 31°C Summer day so icy cold things are on my mind right now.

In this post we'll look at how to work up from sending the first message to subscriber number 1 to up to 10,000 messages with Node.js.

## Getting prepared

To follow along with this post and code the same features you're going to need a couple of things:
* Node.js and npm (I'm using <a href="https://nodejs.org/en/download/">the latest LTS version of Node.js, 8.9.1</a>)
* A <a href="https://www.twilio.com/try-twilio">Twilio account</a> and a <a href="https://www.twilio.com/console/phone-numbers/incoming">Twilio number that can send SMS messages</a>

Once you've got those bits sorted create a new directory to work with and initialise it with npm and install the modules we'll need:

```bash
mkdir ice-cream-alerts
cd ice-cream-alerts
npm init -y
npm install twilio dotenv node-env-run --save
```

In this case I'm using `dotenv` to store the credentials that we need to interact with the API. For loading them even easier I've included <a href="https://www.twilio.com/blog/2017/08/working-with-environment-variables-in-node-js.html">Dominik's node-env-run</a> too. Let's add those credentials now. Create a file called `.env` and enter the following, replacing the placeholders with your account credentials and Twilio number:

```bash
TWILIO_ACCOUNT_SID=YOUR_ACCOUNT_SID
TWILIO_AUTH_TOKEN=YOUR_AUTH_TOKEN
TWILIO_NUMBER=YOUR_TWILIO_NUMBER
```

Got all that? Good, let's send some messages!

## The first scoop

It all starts with a single message to your first subscriber. This is your alpha test for your ice cream delivery alerts subscription. You only need to send one message, let's write that code.

Create a file called `firstscoop.js` open it up and add the following:

```javascript
// firstscoop.js
const twilio = require('twilio')(
  process.env.TWILIO_ACCOUNT_SID,
  process.env.TWILIO_AUTH_TOKEN
);
const body = 'Ice creams are coming!';
```

This code imports the Twilio Node.js module and initialises a new API client using your Account Sid and Auth Token. We also setup the message that we are going to send.

We need a number to send the message to. This is the alpha test, so maybe just add your own number for now. Make sure your number here, and throughout this post, is in <a href="https://www.twilio.com/docs/glossary/what-e164">E.164 format</a>.

```javascript
const number = YOUR_NUMBER_HERE;
```

Now, use the API client we created above to send the message from your Twilio number to your number.

```javascript
twilio.messages
  .create({
        to: number,
        from: process.env.TWILIO_NUMBER,
        body: body
  })
  .then(message => {
        console.log(message.sid);
  })
  .catch(err => console.error(err));
```

This creates the message and sends it. If the request is successful the message Sid is logged, otherwise the error message will be logged.

To make this easy to run add the following to your `package.json` file:

```json
  "scripts": {
    "firstscoop": "nodenv firstscoop.js"
  },
```

Test the code by running `npm run firstscoop`. You should see the message Sid on the command line and receive your first ice cream alert. It's working, go get yourself an ice cream in celebration!

<img alt="An animation of a happy looking ice cream skateboarding and doing tricks." src="https://twilioinc.wpengine.com/wp-content/uploads/2017/12/S0FKU_bqMtJUiLqmZsMCfmueeTyDPUUwidJGxEJ39D-txy7jJ4MzOXLIuC7TCyLp6NbkoYqSe_WJ9Wy0bDUYqitJK1t0JoAozdBwHx2G0e_2_vUtMc6EQafGnQSv8eaXxwLT_4.png" class="aligncenter">

## Multi pack

News of your ice cream alerts service has spread amongst your friends. You now have a small group of willing volunteers to act as your beta testing group. They think they're getting free ice creams too, but you can decide on that later.

You could just run the existing file once for each of them, changing the number each time, but that's not very scalable. Let's look at how to update it to send messages to multiple numbers.

Create a new file, `multipack.js`, and open it up in your editor. The code then starts the same:

```javascript
// multipack.js
const twilio = require('twilio')(
  process.env.TWILIO_ACCOUNT_SID,
  process.env.TWILIO_AUTH_TOKEN
);
const body = 'Ice creams are coming!';
```

This time, we'll use an array of subscribers. If you only have one number to test with still, turning it an array will allow us to approximate a group.

```javascript
const numbers = [YOUR_NUMBER_HERE, OTHER_NUMBER, ... ];
```

Now we need to loop over these numbers and send the messages. Before we do, it's worth considering that this is a growing enterprise. You might have 5 or 10 subscribers now, but hopefully more will be coming in the future. A regular Twilio number can only send 1 message per second. If we get up to 60 subscribers this is going to take a whole minute to send the messages and it gets worse from there. [Carriers in some countries implement filtering](https://support.twilio.com/hc/en-us/articles/223181848-How-Does-Carrier-Filtering-Work-) on your numbers and sending messages to more than 200 subscribers from a single number can trigger this filtering.

We can prepare for this with a <a href="https://www.twilio.com/docs/api/messaging/send-messages-copilot">messaging service</a>. Messaging services can pool numbers and scale sending out over the whole pool. As our subscriber base grows we can add numbers to keep up with demand.

Jump into the Twilio console and create a new <a href="https://www.twilio.com/console/sms/services">Messaging Service</a>, enter a friendly name "Ice cream notifications" and select "Notifications, outbound only" from the use case drop down.

<img alt="A view of the form to create a messaging service. Fill in the Friendly Name field with 'Ice cream notifications' and choose 'Notifications, Outbound Only' as the use case." src="https://twilioinc.wpengine.com/wp-content/uploads/2017/12/6AsscVH_Q0R0AUr38h5DC7bDFTUsDfG2DvGRPBhsV6AQODRZwMlw0HxNIrAGQE-qJ2kGq8YkO6iAW3nAqrkoL77A1rvfouiaNFgL9gf5-bZ4cj2MGHzpqQmc0kN4dooGYXDUhLo.png" class="aligncenter">

Now go to the numbers section for this service and add the number you have been using to send SMS messages.

<img alt="On the configure screen for the newly created messaging service click on 'Numbers' in the menu to configure the numbers for this service" src="https://twilioinc.wpengine.com/wp-content/uploads/2017/12/Gf0rXzAqhM3g_I704kWUs65T540XGehqKu1P9JhnF90XyzyXbcWC5YzTN80VScnOarkU_ctDTMh2KscMqIh2fvao5kbQIV3ow7dAIThaWF04pHIiyM4-MCnLj_UU51cFPLNPyOU.png" class="aligncenter">

Instead of using a "From" number to send messages, we can now use this messaging service's Sid. Grab hold of the Sid and add it to your `.env` file.

```bash
TWILIO_MESSAGING_SERVICE_SID=YOUR_MESSAGING_SERVICE_SID
```

Back in `multipack.js`  we can loop over the array of numbers and send them each an alert using the messaging service.

```javascript
Promise.all(
  numbers.map(number => {
    return twilio.messages.create({
      to: number,
      from: process.env.TWILIO_MESSAGING_SERVICE_SID,
      body: body
    });
  })
)
  .then(messages => {
    console.log('Messages sent!');
  })
  .catch(err => console.error(err));
```

In this code we actually map over the numbers and send a message for each of them. This returns a promise each time, so we collect the results of all the promises using `Promise.all` and when they are all complete, print out a success message. If one of the promises fails, we'll print out the error.

Let's add another line to `package.json` to make it easy to run this file.

```json
  "scripts": {
        "firstscoop": "nodenv firstscoop.js",
        "multipack": "nodenv multipack.js"
  },
```

Now run the code with `npm run multipack` and we're sending multiple messages using our new messaging service.

<img alt="Patrick Star, from Spongebob Squarepants, enjoying an ice cream cone." src="https://twilioinc.wpengine.com/wp-content/uploads/2017/12/hVgXWmoJ-ukCsiEZ6zt7mHXaS15IoZ_cCoYSUwx7xACCEUx0F_GLFaiZi5t1bo40uwcDaGcewg9_51oB-yA1sC7VWXn0BrQUm8btpF46dP-aWJGzYn_3hjVo4e1vcDWUBtT6GoU.png" class="aligncenter">

## 99 problems but a flake ain't one

You're public with your alerts subscription and your friends have all been telling their friends about it. As your numbers start to grow you're sending more and more notifications about impending ice cream delivery. If you're really successful you might break the 100 subscriber mark quickly, but success can breed problems. Due to the asynchronous nature of Node.js and the Twilio API's concurrency limit of 100 connections you might find errors.

We could write the code to queue the messages to be sent creating greater complexity in our application or we could reach into the bag of Twilio tricks and pull out one that is going to save us a lot of time and effort.

The trick in this case is Twilio Notify. Using Notify you can send hundreds, thousands of messages in just one API request. Let's see how.

First up you need to create yourself a new <a href="https://www.twilio.com/console/notify/services">Notify service in the Twilio console</a>. Once it's created, you need to configure it with the messaging service that you created in the last step.

<img alt="On the Notify service configuration page you need to select your messaging service that you created earlier from the drop down field called 'Messaging Service Sid'." src="https://twilioinc.wpengine.com/wp-content/uploads/2017/12/y0DG7gvSrhue-ymvOpNk5Wc6MQUneD7h8fOyhdH7tyVvG8Yt7FujtmAxDkQddQpwRX2aeyQVIYolC1_q-OWVKFVpLmKOyNxFf0vGGucgU85dZ-xQCvyc4Pk4zPHjfUq3GqCVyms.png" class="aligncenter">

Grab the Notify service Sid and add it to your `.env` file.

```bash
TWILIO_NOTIFY_SERVICE_SID=YOUR_NOTIFY_SERVICE_SID
```

Time to write the code. Create a file called `99flake.js` and open it up. Start with the same 3 lines from `multipack.js`.

```javascript
// 99flake.js
const twilio = require('twilio')(process.env.TWILIO_ACCOUNT_SID, process.env.TWILIO_AUTH_TOKEN);
const body = "Ice creams are coming!";
const numbers = [YOUR_NUMBER_HERE, OTHER_NUMBER, ... ];
```

This time we'll get a handle to our Notify service:

```javascript
const service = twilio.notify.services(process.env.TWILIO_NOTIFY_SERVICE_SID);
```

We need to turn our numbers into Notify's binding format. <a href="https://www.twilio.com/docs/api/notify/rest/bindings">Bindings</a> are normally created once and used as part of <a href="https://www.twilio.com/docs/api/notify/rest/segments-resource">segments</a> when sending notifications via SMS, iOS, Android and other channels. But if we just want to send messages straight away, we can create the bindings on the fly.

To do so, we turn each number into a JSON object of the type: `{"binding_type":"sms", "address": NUMBER}`. The code to do this looks like:

```javascript
const bindings = numbers.map(number => {
  return JSON.stringify({ binding_type: 'sms', address: number });
});
```

Twilio limits the size of an API request to 1MB total, which is typically sufficient to send to about 10,000 numbers. If you have more messages to send, then you'll want to split up the requests.

Note: if you are sending to this many numbers at a time, you may want to add many more numbers or a short code to your number pool. Check out the [guidance on carrier filtering](https://support.twilio.com/hc/en-us/articles/223181848-How-Does-Carrier-Filtering-Work-) to learn more.

Use the service to create a notification that will be sent to each of the bindings:

```javascript
notification = service.notifications
  .create({
        toBinding: bindings,
        body: body
  })
  .then(() => {
        console.log(notification);
  })
  .catch(err => {
        console.error(err);
  });
```

Save the file and add this line to `package.json`:

```json
  "scripts": {
        "firstscoop": "nodenv firstscoop.js",
        "multipack": "nodenv multipack.js",
        "99flake": "nodenv 99flake.js"
  },
```

Run `npm run 99flake` and you will send out all of your notifications using the combined power of Twilio Notify and your messaging service. Notify handles sending the messages after your one API call and the messaging service can fan it out over the numbers in your number pool.

<img alt="An animation of lots of tongues licking lots of ice creams." src="https://twilioinc.wpengine.com/wp-content/uploads/2017/12/qsbNcXS7F3W2V3ya5vb_FONCglfh5yjRCSgGTvMW_i11Mg7MGavvm6wz3iGC7jJUbz2A4K6xTnhxUlrJCyrX-0DHb7bErb0hRmBmiS5EY7f0sUVgbhNZw32bDwIno-CHTer1bAk.png" class="aligncenter">

## Ice cream for everyone

Now you know the different options you have for sending, one, a few or a lot of messages. If you need to send one at a time then the regular API is all you need. Once you need to send a few messages, then a messaging service can help to scale that sending and if you have hundreds or thousands of messages to send then Notify has got you covered. You can check out <a href="https://github.com/philnash/bulk-sms-alerts">the code from this post on GitHub</a>.

Do you have any other questions about sending bulk SMS messages with Node.js? Just let me know in the comments, on <a href="https://twitter.com/philnash">Twitter</a> or by email at <a class="c3" href="mailto:philnash@twilio.com">philnash@twilio.com</a>.

Stay frosty.

___

_[The ultimate guide to sending bulk SMS with Twilio and Node.js](https://www.twilio.com/blog/2017/12/send-bulk-sms-twilio-node-js.html) was originally published on the [Twilio blog](https://www.twilio.com/blog) on December 18, 2017._