The Twilio Node Helper Library - Twilio
Register for SIGNAL by 8/31 for $250 off. Register now.

The Twilio Node Helper Library

Deprecation notice: New functionality will only be added to the new library (Node Helper Library 3.x). The old library (2.x) will be officially supported until 8/31/2017. After that day, Twilio will stop providing bug fixes and Support might ask you to upgrade before debugging issues. Learn how to migrate your existing application.

The twilio-node helper library lets you write Node.js code to make HTTP requests to the Twilio API.

This library is open source, so if you find a feature missing or a bug, we encourage you to file an issue or contribute back to the twilio-node project.

Installation

The easiest way to install twilio-node is from NPM. You can run the command below from your project directory to install the library:

npm install twilio

Then in your code:

var twilio = require('twilio');

Testing your installation

Try sending yourself an SMS message, like this:

var accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'; // Your Account SID from www.twilio.com/console
var authToken = 'your_auth_token';   // Your Auth Token from www.twilio.com/console

var twilio = require('twilio');
var client = new twilio(accountSid, authToken);

client.messages.create({
    body: 'Hello from Node',
    to: '+12345678901',  // Text this number
    from: '+12345678901' // From a valid Twilio number
})
.then((message) => console.log(message.sid));

Important Note - Server Side only, not Front End

This library is only for back end applications running on Node.js, not for front end, client side applications that you might build with React, Angular, Vue, or other toolkits. For the client side Twilio Javascript libraries that run in the browser, take a look at the SDKs page, under the Javascript SDKs header.

If you want to see how to put this Node.js library together with the Twilio Client Javascript library for voice, check out the Browser Dialer with Node.js and Vue.js. You'll see how to secure your Twilio account credentials from your end users. The example creates capability tokens with a Node.js endpoint. Not using Vue? That guide also has example code for React, Angular, and Ember, if you prefer any of those frameworks.

Using This Library

Authenticate Client

const accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
const authToken = 'your_auth_token';
const client = require('twilio')(accountSid, authToken);

Create A New Record

const accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
const authToken = 'your_auth_token';
const client = require('twilio')(accountSid, authToken);

client.calls
  .create({
    url: 'http://demo.twilio.com/docs/voice.xml',
    to: '+14155551212',
    from: '+15017250604',
  })
  .then(call => process.stdout.write(call.sid));

Get Existing Record

const accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
const authToken = 'your_auth_token';
const client = require('twilio')(accountSid, authToken);

client
  .calls('CA42ed11f93dc08b952027ffbc406d0868')
  .fetch()
  .then(call => console.log(call.to));

Iterate Through Records

const accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
const authToken = 'your_auth_token';
const client = require('twilio')(accountSid, authToken);

client.calls.each(call => console.log(call.direction));

Handling Exceptions

If the Twilio API returns a 400 or a 500 level HTTP response, the twilio-node library will include information in the error parameter of the callback. 400-level errors are normal during API operation ("Invalid number", "Cannot deliver SMS to that number", for example) and should be handled appropriately.

More Documentation

Once you're up and running with the Node helper library, you'll find code samples using the latest version in our REST API docs and in the documentation for every Twilio product. You can also find auto-generated library docs for the latest SDK here.

Accessing the 2.x Version of the SDK

The most recent version of the Node SDK is not API compatible with the previous 2.x version of the Node SDK you may have used in previous Twilio applications. The older version will continue to work, and you will continue to find sample code for this version throughout our documentation. Should you need to install this version from NPM, you can do so with the following command.

npm install twilio@2.1.1

Alternately, you can view this version of the SDK on GitHub and download it directly from there.

Getting Help

We'd love to hear your feedback on the Twilio Node Helper Library and help you past any issues you may encounter. Feel free to drop us a line, and we'll make sure to get you sorted!

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.