Getting Started with Twilio and Node.js

See the most updated version of this post and our new Node.js module here.

Node.js is one of the most talked about frameworks in the web development community since Rails. While still very young, node is being hailed as fast, highly-scalable and efficient. The reason for this is due to node’s event-driven, non-blocking I/O structure.

One of the reasons we’re so psyched about node.js is that combining it with Twilio makes building awesome telephony apps really easy. In this post, I’m going to take you through the basics of setting up Twilio with node.js. I’ll be using the node-twilio helper library by Stephen Walters to get you started with the basics of initiating a call and then answering it. [Update: the most recent Node.js library for Twilio can be found here]

Installation

For this project I’m working on the Ubuntu platform. You can find instructions for others at the node.js github repository. Install node.js on Ubuntu with the apt-get package manager:

[code lang="bash"]
$ sudo apt-get install python-software-properties
$ sudo add-apt-repository ppa:jerome-etienne/neoip
$ sudo apt-get update
$ sudo apt-get install nodejs
[/code]

You’ll also want to install npm, the node package manager, to assist with installing node libraries and programs.

[code lang="bash"]$ apt-get install curl[/code]

 

[code lang="bash"]$ curl http://npmjs.org/install.sh | sh[/code]

The next step is to install node-twilio.

[code lang="bash"]$ npm install twilio[/code]

Parts of node-twilio depend on the express framework so you should install express now too:

[code lang="bash"]$ npm install express[/code]

Once you’ve gotten your environment setup for node development, you’ll need to sign up for a Twilio account if you don’t already have one.

This will give you a Twilio Account Sid and an Auth Token which you’ll need to develop your application.

Creating the call object

First, require:

[code lang="js"]
var TwilioClient = require('twilio').Client,
Twiml = require('twilio').Twiml,
sys = require('sys');
[/code]

Next, instantiate a TwilioClient object:

[code lang="js"]var client = new TwilioClient('MY_ACCOUNT_SID', 'MY_AUTH_TOKEN', 'MY_HOSTNAME');[/code]

Pretty easy, right? Let’s use this client to create a PhoneNumber object:

[code lang="js"]var phone = client.getPhoneNumber('+1###########');[/code]

The ########### will be your Twilio number that you have purchased and own. Now that you’ve gotten a phone number with the client, let’s have it make a call.

To do that, you use the  setup() method to make a request to Twilio’s REST API. Once it’s done with all that, it calls a callback function with no parameters. After that, you’re ready to make a phone call with the  PhoneNumber object’s  makeCall method.

[code lang="js"]phone.setup(function() { phone.makeCall('+15555555555', null, function(call) {});[/code]

The  makeCall method accepts three paremeters:

  1. The phone number to dial
  2. a map of options
  3. a callback function.

The argument to the callback is an  OutgoingCall object. This object emits two events:

  1. 'answered'
  2. 'ended'

So you can listen for those events, and then respond to them appropriately.

Here’s an example of how you can listen for the 'answered' event and then use 'response' to tell your buddy to meet you for drinks later.

[code lang="js"]
phone.setup(function() {
phone.makeCall('+15555555555', null, function(call) {
call.on('answered', function(callParams, response) {
response.append(new Twiml.Say('Hey buddy. Let's meet for drinks later tonight.'));
response.send();
});
});
});
[/code]

The 'answered' event handler accepts two arguments

  1. callParams
  2. responsecallParams

For outgoing calls, Twilio requests your handler URI which contains information like CallSid, CallStatus, and more. Twilio’s Request documentation has more more details on this. The response argument of the 'answered' event is a Twiml.Response object. See The TwiML Interface for more details on valid responses that can be sent on Twilio.