Menu

Expand
Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

The Twilio Node Helper Library

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.

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 plain HTML/CSS/Javascript. For general HTTP requests to the Twilio API, consider writing a Twilio Function and making an HTTP request to the Function from within your app. Twilio also has several Javascript libraries that run in the browser, which you can find 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.

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));

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.

Rate this page:

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.