Tropo WebAPI with Ruby on Rails and Heroku

What is Tropo?

Tropo is a cloud-based voice and text messaging solution provider. Essentially if you have an application that needs to talk on the phone or over text, this is the way to make it happen. As someone who has designed and configured a lot of call center systems in my career, let me tell you that this is a game-changer. What would normally take a lot of servers and software with weeks of configuration can now be accomplished with a quick script. Features like call recording, speech recognition, and text messaging (which would normally be considered advanced options for these kinds of systems) are all included by default and are very easy to set up. There’s a simple scripting language that you can run right on Tropo servers, or you can get fancy and configure your own WebAPI applications for more advanced integrations. Check out Tropo’s blog for some cool examples of how the service can be used.

Hello World!

Since joining the Cloverhound team I’ve been learning how to develop Tropo WebAPI applications – mostly by working my way through the Tropo Quickstart documentation (which is very good as far as these things go). Example code is provided for Ruby, Node.js, PHP, and Python so you can try whatever you are most comfortable with. Since I have a little experience with Ruby (and because a lot of development at Cloverhound is done with Ruby on Rails) I have focused mostly on the Ruby examples.

The issue I quickly ran into was that Sinatra is used in all of the examples. Sinatra provides a simple web framework for the documentation, so I understand why it was used in examples, but for production purposes Ruby on Rails is more commonly used (and much easier to get working on cloud services like Heroku). Before diving further into the documentation I wanted to make sure that I got a simple example working with Ruby on Rails (in this case saying “Hello World!” when a number is dialed). I also wanted be able to run my code on a Heroku server, which lets me avoid having to use an SSH tunneling service back to my development machine.

Below are the steps I took to get this working on OS X – if you are using Windows or Linux you may have to do a few steps slightly differently, but the pages I link to will have more information. It seems like a lot of steps but it should probably take less than an hour to run through, which is much less time than it would take to set up a bunch of servers and routers to do the same thing with your own infrastructure…

Install Homebrew

First, we need to install Homebrew. Homebrew allows us to install and compile software packages easily from source. Homebrew comes with a very simple install script. Open Terminal and run the following command (when it asks you to install XCode CommandLine Tools, say yes):

ruby -e "$(curl -fsSL"

Install Ruby

Now that we have Homebrew installed, we can use it to install Ruby. To do this, run the following commands in your Terminal:

brew install rbenv ruby-build

# Add rbenv to bash so that it loads every time you open a terminal
echo 'if which rbenv > /dev/null; then eval "$(rbenv init -)"; fi' >> ~/.bash_profile
source ~/.bash_profile

# Install Ruby
rbenv install 2.2.3
rbenv global 2.2.3
ruby -v

Configure Git

We’ll be using Git for our version control system so we’re going to set it up to match our Github account. If you don’t already have a Github account, make sure to register. It will come in handy for the future.

Replace the example name and email address in the following steps with the ones you used for your Github account.

git config --global color.ui true
git config --global "YOUR NAME"
git config --global ""
ssh-keygen -t rsa -C ""

The next step is to take the newly generated SSH key and add it to your Github account. You want to copy and paste the output of the following command and paste it here.

cat ~/.ssh/

Once you’ve done this, you can check and see if it worked:

ssh -T

You should get a message like this:

You've successfully authenticated, but GitHub does not provide shell access.

Installing Rails

Installing Rails is as simple as running the following command in your Terminal:

gem install rails -v 4.2.4

Rails is now installed, but in order for us to use the rails executable, we need to tell rbenv to see it:

rbenv rehash

And now we can verify Rails is installed:

rails -v
# Rails 4.2.4

Install PostgreSQL

You can install PostgreSQL server and client from Homebrew:

brew install postgresql

Once this command is finished, it gives you a couple commands to run. Follow the instructions and run them:

# To have launchd start postgresql at login:
ln -sfv /usr/local/opt/postgresql/*plist ~/Library/LaunchAgents

# Then to load postgresql now:
launchctl load ~/Library/LaunchAgents/homebrew.mxcl.postgresql.plist

By default the postgresql user is your current OS X username with no password.

Create Rails Application

# Create Rails Application
rails new helloworld -d postgresql

# Move into the application directory
cd helloworld

# If you setup MySQL or Postgres with a username/password, modify the
# config/database.yml file at this time to contain the username/password that you specified
# Create the database
rake db:create

# Start Rails Server
rails server

If you received an error that said Access denied for user 'root'@'localhost' (using password: NO) then you need to update your config/database.yml file to match the database username and password.

You can now visit http://localhost:3000 to view your new website – it won’t do much for our purposes, but it’s nice to know that everything up to this point is working. Once you are done testing you can use CNTRL-C to terminate the local Rails server.

Sign Up For Heroku

Go here and sign up for a free development account. The free account tier provides one web process and one worker process (which is enough for development / testing purposes). Free apps will sleep after 30 minutes of inactivity and must sleep at least 6 hours out of the day. Pricing information is available for other tiers, so if you get your app up and running and need it to run in production you just have to upgrade your account.

Once your account is activated, download and install the Heroku Toolbelt and then ensure you can log in from the command line:

$ heroku login
Enter your Heroku credentials.
Password (typing will be hidden):
Authentication successful.

Set Up Tropo Account

Register for a free Tropo account. Your free Tropo account will give you everything you need to develop voice and messaging applications, including phone numbers and file hosting. Enabling outbound dialing and texting features requires opening a support ticket, but inbound dialing will work right away.

At this point you should also install the Tropo WebAPI Ruby Library:

sudo gem install tropo-webapi-ruby

Create Rails Controller

Let’s go back to the Rails application that we created a few steps ago and create a new controller. Controllers are the core of a web request in Rails. They are made up of one or more actions that are executed on request and then either it renders a template or redirects to another action. An action is defined as a public method on the controller, which will automatically be made accessible to the web-server through Rails Routes.

# Ensure you are in the Rails application folder created earlier
cd helloworld

# Generate a controller called "test"
rails generate controller test

Create Route to Test Controller

Before we add our Hello World code to the test controller, let’s set up a route to it in Rails. The routes.rb file (located in your project folder under /config) tells Rails which controllers handle which incoming requests. For this example we simply want to ensure that any HTTP request to http://ourserver/test is handled by our test controller (and sent to the index function).

Modify config/routes.rb in your favorite text editor so it matches the code below and save:

Rails.application.routes.draw do
post 'test' => 'test#index'

Modify Gemfile

We need to modify a file called Gemfile located in your project folder to include the Tropo WebAPI Ruby Gem installed earlier. Add this line of code anywhere below the first line and save the Gemfile:

gem 'tropo-webapi-ruby'

You will have to run bundle install from the app directory to ensure Rails includes the modified Gemfile:

bundle install

Add Tropo Code to Test Controller

At this point our Rails application is all set to accept an inbound request and do something with it. Now we just have to tell it what to do! Using your handy text editor modify app/controllers/test_controller.rb to match the code below and save:

class TestController < ApplicationController
skip_before_action :verify_authenticity_token

def index

t =
t.say(:value => "Hello World!")
render :json => t.response


The skip_before_action :verify_authenticity_token line is required to allow requests from outside the local application/server (since in this case they will be coming from The index function contains the relevant Tropo code for saying a simple text-to-speech prompt.

Initialize Git Repository

We are all done building the application! Now all we have to do is get the code all ready to push out to Heroku. The first step in this is to initialize a git repo in the project folder and add all of the files. After this is done you commit the changes.

git init
git add .
git commit -m "Initial add"

Create Heroku App

Still working from in the project folder, run the following command to create a new Heroku application instance:

heroku create

This will generate a unique Heroku URL so if you see an odd combination of two random words and some numbers that’s why. You can add a name after heroku create to specify this name but it has to be unique across Heroku.

Deploy Heroku App

We’re getting really close now. I promise. Run the following to push the code to Heroku:

git push heroku master

You’ll see a bunch of messages after this point (hopefully none of them errors). Note the URL created and deployed to Heroku as we will need this in a minute. Mine looked like this:

remote: -----> Compressing... done, 28.3MB
remote: -----> Launching... done, v29
remote: deployed to Heroku
remote: Verifying deploy... done.

Add PostgreSQL to Heroku App

Log into the Heroku website and you should see your new application listed in your dashboard. Click it and make sure that your web process is started:

Screen Shot 2015-10-28 at 9.38.34 AM

Next, ensure that you have the Heroku PostgreSQL add-on installed in your site. If it is not listed then click “find more add-ons” and add it:

Screen Shot 2015-10-28 at 9.36.23 AM

Create Tropo Application

Log into and go to MY APPS and click Create New App. Give it a new name, leave it in Development, and select the WebAPI option. Paste your Heroku application link from the last step and add test to the end. Mine looked like this:

Then you will assign a phone number to your application. Once this is saved give it a call and you should hear “Hello World!” Nice work!