Node Version 3.x Upgrade Guide

This is an upgrade guide for moving from 2.x to 3.x versions of the twilio-node helper library.

Import

In twilio-node 2.x, you would have to make a new instance of each client you used:

var Twilio = require('twilio');

var ipmClient = new Twilio.IpMessagingClient(USERNAME, PASSWORD);
var lookupsClient = new Twilio.LookupsClient(USERNAME, PASSWORD);

Now, in twilio-node 3.x, there is only 1 object to import and initialize:

var Twilio = require('twilio');
var twilio = new Twilio(USERNAME, PASSWORD);

Accessing Resources

// Old
client.messages('SM123').get(function(err, message) {
  console.log(message.sid);
  // SM123
});

// New
client.api.v2010.account.messages('SM123').fetch(function(err, message) {
  console.log(message.sid);
  // SM123
});
// or
client.messages('SM123').fetch(function(err, message) {
  console.log(message.sid);
  // SM123
});

The new library makes Twilio API subdomains (Lookups, Trunking, Monitor, etc) first-class citizens. You can now also pin your interactions to the Twilio API to specific versions of that API (so here, .v2010. ensures we always talk to the 2010-04-01 version of the API). This allows you to migrate portions of your code to future versions independently without having to do a full upgrade when you update the library.

You'll also notice that get has been updated to fetch. We updated the library to use fetch, create, update, and remove to be explicit about what action you are taking.

Promises

You may also use promises to interact with twilio-node:

var promise = twilio.messages('SM123').fetch();
promise.then(function(message) {
  console.log(message.sid);
});

Listing Resources

There are now 2 ways to get a list of resources: list and each.

• list will fetch the entire collection of resources and resolves to an array that contains the resources instances.

var promise = twilio.messages.list();
promise.then(function(messages) {
  console.log(messages);
});
// [MessageInstance, MessageInstance, MessageInstance, ...]

• each will page through the list of resources and call the callback function that you passed in with each instance and a done function. To stop iteration at any point, call the done function.

twilio.messages.each(function(message) {
  console.log(message.sid);
});
// 'SM123'

var i = 0;
twilio.messages.each(function(message, done) {
  console.log(message.sid);

  i++;
  
  // break after 10 messages
  if (i >= 10) {
    done();
  }
});

Paging

One of the biggest advantages of twilio-node 3.x is that it automatically handles paging for you! In both list and stream, you can specify the maximum number of instances to grab (limit), and the page size (pageSize). The library will take care of everything else.

twilio.messages.each(function(message) {
  console.log(message.sid);
});

var promise = twilio.messages.list();
promise.then(function(messages) {
  console.log(messages.length);
});
// 125

promise = twilio.messages.list({
  limit: 100
});
promise.then(function(messages) {
  console.log(messages.length);
});
// 100

Configurable HTTP Client

You can now plug your own HTTP client into the Twilio client! Just pass a client that conforms to the RequestClient interface and pass it in when you initialize Twilio.

var client = new CustomClient();
var twilio = new Twilio(USERNAME, PASSWORD, client);