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.

  • James R Carr

    Very cool. Just one question… is it possible to run this example locally or does it have to be deployed?

    • http://john-sheehan.com/blog John Sheehan

      You can run it locally but expose it to the public internet (where TwiML URLs must be for us to access them) using localtunnel: http://progrium.com/localtunnel/

  • James R Carr

    Very cool. Just one question… is it possible to run this example locally or does it have to be deployed?

    • http://john-sheehan.com/blog John Sheehan

      You can run it locally but expose it to the public internet (where TwiML URLs must be for us to access them) using localtunnel: http://progrium.com/localtunnel/

  • Langdon Oliver

    There a 2 errors in the last example … (1) ‘answered needs a close quotation, and (2) Let’s needs to be escaped.

    Also you should instruct folks that port 31337 needs to be opened for this stuff to work. Is that port configurable?

    • http://twitter.com/jonmarkgo Jonathan Gottfried

      Hey Langdon, Thanks for pointing out those bugs – I’ve updated the post to correct them! As for the port #, I don’t see that mentioned anywhere in the post – could you point me in the right direction?

      • Langdon Oliver

        Sorry I assumed the author of this article was the author of the module… clearly I didn’t read the first two paragraphs so well.

        Anyway, auto-uri.js (in node_modules/twilio/lib/) calls createServer, I assume, to accept callbacks from the Twilio API.  The port defaults to 31337 (which needs to be open on the machine/server you’re using).

        You can configure it by passing port in options when you create a client.

  • Langdon Oliver

    There a 2 errors in the last example … (1) ‘answered needs a close quotation, and (2) Let’s needs to be escaped.

    Also you should instruct folks that port 31337 needs to be opened for this stuff to work. Is that port configurable?

    • http://twitter.com/jonmarkgo Jonathan Gottfried

      Hey Langdon, Thanks for pointing out those bugs – I’ve updated the post to correct them! As for the port #, I don’t see that mentioned anywhere in the post – could you point me in the right direction?

      • Langdon Oliver

        Sorry I assumed the author of this article was the author of the module… clearly I didn’t read the first two paragraphs so well.

        Anyway, auto-uri.js (in node_modules/twilio/lib/) calls createServer, I assume, to accept callbacks from the Twilio API.  The port defaults to 31337 (which needs to be open on the machine/server you’re using).

        You can configure it by passing port in options when you create a client.