Introducing The Twilio Module For Node.js

This is the first in a series of tutorial blog posts covering the use of Twilio’s new helper library for node.js. In this tutorial, we will cover the setup and basic features of the module to get you started fast. The next post in this series will help you learn how to turn your browser into a soft phone with Twilio Client and node.

The official node.js helper library documentation is located here.

Making Phones Ring With JavaScript

These days you can write just about any kind of software in JavaScript. Whether it’s a web front end, a 3D game, a native mobile app, or back end services on a server, today you can do it all in JavaScript. On the server, node.js is leading the charge, providing a super fast runtime built on the V8 JavaScript engine, a lean but powerful standard library, and a thriving community of module developers packing npm with useful software.

To support this growing user community, Twilio recently released a full-featured, officially supported helper library for node.js. To help introduce the module, I will do a series of blog posts in the coming weeks to show how you can implement awesome communications apps using JavaScript on the server. This week, we will cover the installation and key functional areas of the Twilio module at a high level to get you started.

Getting Started

First things first – if you have not yet installed node.js on your system, you can download an installer for your platform from The installer should place both the “node” and “npm” executable commands on your system path. To confirm this is the case, open up a command prompt or terminal window and type “node -v” and “npm -v”.

As of this writing, the latest stable versions of node and npm are 0.10.1 and 1.2.15, respectively. As you use node, you may want to install multiple versions – if so, I would recommend taking a look at nvm. But for now, using the standard installer should suffice.

Now, let’s create a simple node program which uses the Twilio API. From the terminal, create a new directory for this demo exercise. Inside this new directory, create a file called “ahoy.js”, where we will write code to send a text message using the REST API. Next, install the Twilio module using npm, in the same directory as “ahoy.js”. Note that depending on your system configuration, you may need to install the module using “sudo”:

[sudo] npm install twilio

node.js has a simple module loading system which looks for modules in a “node_modules” directory in the path where the node program is run. After installing the Twilio module from npm using the method above, you will notice a “node_modules” directory in your demo folder, and that the twilio module is inside it.

Now let’s start writing some code. The Twilio module provides three main functional areas:

  • A client for making authenticated requests against the REST API
  • A utility for generating TwiML

Writing a VoIP application with node.js will be the focus of next week’s post, so we won’t be exploring the third bullet just yet. But let’s take a look at the first two bits of functionality, starting with the REST API.

Using the REST API

Our first example will use the REST client to send a text message. Open “ahoy.js” with your favorite text editor and paste in the code below, replacing “TWILIO_ACCOUNT_SID” and “TWILIO_AUTH_TOKEN” with the appropriate values from your account dashboard. You will also need a Twilio phone number to send messages from – you can buy one here if you don’t already have one to use for testing. Replace “TWILIO_NUMBER” with this phone number. For testing, you’ll probably just want to send the message to your own mobile phone – replace “+16512223344” with your own mobile number:

To run this code, return to the terminal and run:

node ahoy.js

After a second or so, you should see information about the text message you just sent printed out to the console.
Since the REST API is the most commonly used feature of the module, we’ve tried to tighten up the API as much as possible for common functionality. In this example, we initialize a REST client with a single line of code, and use the “sendSms” function, which is a shorter alias for “sms.messages.create”:

In a production environment, you will not want to have your account SID and auth token stored directly in your source code, where they might be checked into version control by mistake. One solution is to configure your account SID and auth token as system environment variables, and access them from there. The node.js module automatically looks for this configuration in “process.env.TWILIO_ACCOUNT_SID” and “process.env.TWILIO_AUTH_TOKEN”, so if those variables are set, the following would be sufficient to initialize a REST client:

Generating TwiML to handle inbound calls and SMS

As experienced Twilio hackers know, when you receive an inbound call or text message to your Twilio number, Twilio makes an HTTP request to a URL controlled by the developer. This URL must return a special set of XML instructions called TwiML, which tells Twilio how to handle the call or SMS.

While you are free to generate TwiML using a template language or other utility, the Twilio node.js module provides a utility library which makes it very easy to create and output one of these documents. Let’s create a simple application which responds to any HTTP request with a simple set of TwiML instructions. In the terminal, create a new file called “inbound.js” and paste in the following example code:

Run this code in the terminal using the command “node inbound.js” – this will cause an HTTP server process to be created. After the server is started, visit http://localhost:1337/ in your browser and you should see an XML document that looks like this:

When you are finished testing, kill the HTTP server process in the terminal by pressing Control-C.

Nesting TwiML

Several TwiML verbs allow for nested nouns and verbs. One example is the tag, which collects input from a voice user via DTMF tones (the numeric buttons on a standard phone, plus * and #). To create a nested TwiML document, you will pass a function as an argument to a parent tag, as in the following example. Replace the contents of “twiml.js” with the following code, which will prompt the user for input:

Restart the HTTP server by running “node inbound.js”. When you visit http://localhost:1337/ you should now see an XML document that looks like the following:


With the Twilio module for node.js, you can develop a wide range of communications applications using the top server-side JavaScript platform. Today, we covered how to set up the module, use the REST API, and generate TwiML. Next week, we’ll explore VoIP in the browser with Twilio Client – be sure to stop back then!

If you have any questions or comments, please let us know (help at Or better still, fork the repo or submit an issue to let us know how we can make the module even better.

  • Lyle Pratt

    Great work Kevin! Was also very nice to meet you at Javelina during SXSW.

  • Matt Harrison

    How do I configure this to work with an http proxy?

    • kevinwhinnery

      Hey Matt,

      Sorry for the tardy reply here. I’m using the request module under the covers, which should work transparently with HTTP proxies. If this is not the case for you, could you open an issue on the GitHub repository so we can explore further?


  • c0nrad

    Awesome tutorial, thanks!

  • Charlotte Spencer

    You say “replace twiml.js” when going on to talk about Nesting Twiml. Though we have not worked with that file. I assumed you meant inbound.js?

    Anyway, great tutorial!

    • kevinwhinnery

      You’re right :( – I will change it in the tutorial. Thanks!

  • Istvan Fenesi

    Can calls be done from a regular SIP webphone, such as the mizu webphone, to/from Twilio?

    • kevinwhinnery

      I think so, though we’d need to know more about your specific use case. The relevant documentation for working with SIP is located here:

      If you can’t find what you’re looking for in the SIP docs, please reach out to with more precise information on what you’re looking to accomplish.

      • Istvan Fenesi

        Thank you, it looks doable. This is the sip client i am trying to use: The only drawback I see that i will not be able to use opus codec, which seems to have very good quality with this webphone.

        • Istvan Fenesi

          Actually it is not a big problem, since most of my calls have to go to pstn. So anyway it is converted to narrow-band.

  • Isaiah Turner

    If the request was successful, this value will be “falsy”

    umm who decided on “falsy”? False would make much more sense.

  • Renz

    Whenever I run node ahoy.js it always return “Oops! There was an error.” Do you know how I can fix this?

    • Twilio

      Can we get evangelists@ added to this
      Would help for the crew to get visibility on comments to their posts.

    • kevinwhinnery

      Sorry for the late reply, but I would console.log the “error” object and see what your error says. For further (and quicker) support, send a note to

  • ning

    it is not possible for me to send sms to different numbers

    • kevinwhinnery

      Hi there – the code for sending messages should be pretty much the same today, although “sendMessage” would be the preferred shortcut today. If you’re still having problems, I would recommend sending as much information about the error as you can to – you might also check the international message permissions for your account – those can be at play when messages are not sent: