StudentRND

Build.

News for students building awesome things.

Tutorial: Creating a Reddit Browser with Node.js and Twilio

reddit

Browse the code on GitHub. This tutorial will take ~30-60 mins for a beginner who has a basic understanding of C-style programming syntax, and the command line.

You’re stuck at school/work, and want to browse reddit. However, the powers that be have decided to impose an internet filter, and you don’t have a smartphone, meaning that reddit is inaccessible.

Not to worry! In this tutorial, I’m going to show you how to build a simple application that allows you to text a phone number and see a list of top posts on reddit! (It’s up to you to add more features after this tutorial!)

Technologies and Services Used

  • Node.js — a method of using the Javascript programming language to create a network application. We’re going to use this to build the bulk of the app.
  • Twilio — an API that allows you to interact with phones with web-based development tools. We’re going to use this API to power communication between your phone and your code.
  • Heroku — a fast and easy way to host server apps. We’ll use this to host your app.

Please download and install Node.js, and sign up for a Twilio and Heroku account. Download and install the Heroku Toolbelt.

Designing the App

In this app, we want this to be the general workflow:

  1. You text “reddit” to a Twilio-powered phone number.
  2. Twilio messages your app, hosted on Heroku, with your text message.
  3. Your app requests a list of top posts from the reddit
  4. Your app sends a response to Twilio, which texts you back with a list of top posts.

[[MORE]]

Setting up Your App with Heroku

Let’s start by following the first half of Heroku’s Getting Started with Node.js guide. You’ll learn how to set up a simple Node.js app using express.js, and then deploy it properly to Heroku.

After you run “git push heroku master” and successfully see “Hello World!” on your Heroku subdomain, please return to this guide.

You should now have a basic installation of express.js, a popular lightweight framework for Node.js, installed on Heroku, displaying “Hello World!”.

Where you should be

Heroku loves creating wacky names for your app. Here, mine is called “Stark-Fortress-5373″. We can rename it later, but it doesn’t really matter, as your visitors aren’t going to go to your site directly.

Request Data from reddit

The first thing we’re going to do is to request data from reddit. reddit has an API which allows you to interact with reddit with your code.

Retrieving data is pretty easy — to get a machine readable version of a page like “http://reddit.com/”, you can append “.json” or “.xml” to get the data encoded in those two formats.

For example: try going to http://reddit.com/.json and seeing what happens. It’s a bunch of machine data, but you can humanize it and navigate through it if you put it into a JSON Parser. Copy it into the JSON parser, and try navigating through the data.

JSON stands for JavaScript Object Notation. JSON is a great way of encoding and transferring data between servers, which is why many companies use it for their APIs.

It’s convenient for us, because the language for Node.js is Javascript! Meaning that we don’t have to do as much work to import it into our application.

Install Restler

To get this information into our app, it’ll be easier for us to use a library called restler to download and retrieve it. To add it to our app, let’s edit our package.json file, and add restler as a dependency:

    "dependencies": {
        "express": "2.5.x",
        "restler": "2.x.x"
    }

Then go into the command line and install restler by running:

npm install

NPM is amazing — it finds the restler package for you, and automatically installs it in the node_modules folder! Add it to your app with this code:

var restler = require('restler');

And update your main app handler (replace the code under app.get to app.all) to use restler to grab the json from reddit:

app.all('/', function(request, response) {
    restler.get('http://reddit.com/.json').on('complete', function(reddit) {
        var titles = "";
        for(var i=0; i<5; i++) {
            titles += reddit.data.children[i].data.title;
        }
        response.send(titles);
    });
});

Try running the code. (You can use foreman start to run it locally instead of pushing it to Heroku, and access it at http://localhost:5000.) You should get the first five of reddit’s frontpage articles jammed together in one long run-on sentence. Here’s a screenshot of my results.

Let’s explain this bit of code:

Parsing JSON

As you can see, we got reddit’s homepage data, (with Restler), iterate through each entry and add the titles to a response that we send back to the browser.

Why reddit.data.children[].data.title? If you copied reddit’s data into the JSON Parser from earlier, you’ll see that’s the data structure you have to navigate to get to the titles! If reddit had a better API documentation, you might be able to refer to the documentation for their data structures, but I think reddit is simple enough you don’t need as much documentation.

Callbacks

Node.js is structured to be highly asynchronous. There’re many debates on the pros and cons of this model, but what you need to know is this means that long operations, like accessing a database or remote server, are put into callbacks where commands are executed after the operation.

This means that, unlike before, where you may write:

data = timeConsumingTask()
print(data)

You would instead write in an asynchronous form:

timeConsumingTask(function(data) {
    print(data)
})

OK! Now let’s configure things with Twilio.

Set up Text Messaging with Twilio

After you register for a Twilio account, you get a Trial number. This is a semi-limited feature number where each each text message is prepended by “Sent from your Twilio trial account”. No worries, you’re using this for yourself so it doesn’t really matter.

Go into your Twilio dashboard, and modify your Twilio Number’s SMS Request URL to your Heroku address. This is where Twilio will send the request after getting a text message from someone.

Twilio Dashboard

TwiML

You need to format your response in a way that Twilio can read. Twilio uses TwiML for its requests, which is like a special version of HTML for phones.

Instead of things like this:

<html>
    <p>This is a paragraph</p>
    <img src="/logo.png" />
</html>

You would have:

<Response>
    <Say>Hello, this is a computer voice!</Say>
    <Play>https://api.twilio.com/cowbell.mp3</Play>
</Response>

Read the TwiML documentation for more info. We’re now going to modify our Node.js application to use TwiML for text messages. We want the final output to be something like:

<Response>
    <Sms>reddit title</Sms>
</Response>

Each being a text message. So we modify our response handler to be:

app.all('/', function(request, response) {
    restler.get('http://reddit.com/.json').on('complete', function(reddit) {
        var titles = "<Response>";
        for(var i=0; i<5; i++) {
            titles += "<Sms>" + reddit.data.children[i].data.title + "</Sms>";
        }
        titles += "</Response>";
        response.send(titles);
    });
});

Which then will output TwiML to Twilio.

Push this back to Heroku:

git add .
git commit -m "got to the end of the tutorial!"
git push heroku master

Final Result

Try texting something to your Twilio phone number and see what happens! If everything works properly, here’s what should happen:

reddit messages

Note: With the free tier, Heroku will shutdown your app after 1 hour of inactivity. It’ll restart when there’s another request, but the initial request may take ~20 seconds or so, meaning that Twilio won’t text you back. When that happens, simply text your test number again and it should respond.

Challenges:

Now that you’ve implemented a basic reddit Browser with Node.js and Twilio, try doing some more! Try adding some of these features:

  • Make it browse subreddits based on what you text!
    • Hint: you’ll need to read more about Twilio’s SMS Request format and Express’s BodyParser middleware.
  • Read comments via text
  • Make it support phone calls!
  • Make it support Hacker News! (Try the unofficial Hacker News API)

Thanks for reading!

This is my first time writing a tutorial, so please let me know below in the comments how you liked it! Thanks to Lane Aasen for helping me refine the formatting, and Leland Batey for testing the tutorial!

I’m Edward Jiang, and I run StudentRND, a nonprofit organization that inspires students to work on tech projects in their spare time. If you enjoyed this, please follow us on Facebook and Twitter! Or maybe donate? We’re a 501(c)(3) nonprofit, meaning that donations are tax-deductible!