This post is sponsored by Twilio, a Node Knockout 2013 service sponsor.

The Node Knockout is nigh! As you make last minute preparations for your weekend masterpiece, you may be planning Android, iOS, and browser-based UI for your application. But there’s another client platform that’s even more ubiquitous - that’s the telephone, particularly mobile phones. If you’d like to create experiences for all these devices, Twilio can help you get it done.

In this tutorial, we’ll explore how to use the Twilio module for node.js to make and receive phone calls and text messages. This is slightly adapted from a series of introductory blog posts on the Twilio module, which are worth checking out as well if you’re interested!

Getting Started

In order to use the Twilio API, you will first need to sign up for a free account. If you sign up with the promo code NKO2013, you will receive an additional $30 USD of credit :) Once you sign up for a Twilio account, you’ll need to purchase a phone number before you can start making calls or sending texts. You should have purchased a number in the getting started flow, but if not, you can purchase one in your account portal. Click on one of your phone numbers, and let’s get hacking!

Receiving a Phone Call

When Twilio receives an incoming call or text message to your phone number, we will send your web app an HTTP request to ask how we should respond to the call or message. The way you will tell Twilio how to reply to a text or call is by responding to Twilio’s HTTP request using a set of roughly a dozen XML tags called TwiML.

Let’s write a little Express app that serves TwiML in response to a POST request to /inbound. Create a file called app.js. Don’t forget to npm install express first! Place the following code in app.js:

var express = require('express');

var app = express();
app.use(express.urlencoded());

app.post('/inbound', function(request, response) {
    response.type('text/xml');
    response.send('<Response><Say>Hello there! Thanks for calling.</Say></Response>');
});

app.listen(3000);

Run node app.js to start your web app on port 3000.

Next, we’ll need to get this app on the internet so Twilio can send a request to it. One quick and easy way to do that is using ngrok. This will forward a local port on your laptop to the public internet. This is super useful for testing local webhooks like this one.

Once you download ngrok, run the command ngrok 3000. This will create a new, public URL for your local machine. Take that url and configure your Twilio number with this URL, with /inbound appended:

phone number config

Now, give your phone number a call! You should hear the Twilio text to speech engine read back a friendly message, as you instructed with the <Say> tag.

Sending a Text Message

Sending an outbound text message or phone call requires that you use the Twilio REST API with your account SID and auth token, which can be found on your account dashboard.

To test sending an outbound message, create a new file called outbound.js. Before editing it, install the Twilio node module with npm install twilio. Now, place the following code in this file, replacing TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN with the values for your account. Alternately, the module will automatically pull in environment variables of the same names and use those to authenticate - but for now, you can just hard code your credentials.

You will also need to replace the to number to be your own mobile phone, and the from number to be your Twilio-controlled phone number:

var client = require('twilio')('TWILIO_ACCOUNT_SID', 'TWILIO_AUTH_TOKEN');

client.sendMessage({
    to:'+16512080532', // the number for the phone in your pocket
    from:'+16518004844', // your Twilio number
    body:'Node Knockout! Woo!' // The body of the text message
}, function(error, message) {
    // This callback is executed when the request completes
    if (error) {
        console.error('Dagnabit.  We couldn\'t send the message');
    } else {
        console.log('Message sent! Message id: '+message.sid);
    }
});

That’s it! Run the code with node outbound.js to send yourself a text message.

More Resources

The Twilio module’s official docs are hosted on GitHub pages. You’ll find extensive documentation there on the features of the module.

If you have any questions or feedback, tweet @kevinwhinnery or send a note to kw at twilio.com. Good luck in the knockout!

Blog comments powered by Disqus