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.
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…
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 https://raw.githubusercontent.com/Homebrew/install/master/install)"
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
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 user.name "YOUR NAME" git config --global user.email "YOUR@EMAIL.com" ssh-keygen -t rsa -C "YOUR@EMAIL.com"
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.
Once you’ve done this, you can check and see if it worked:
ssh -T email@example.com
You should get a message like this:
You've successfully authenticated, but GitHub does not provide shell access.
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:
And now we can verify Rails is installed:
rails -v # Rails 4.2.4
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. Email: firstname.lastname@example.org 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' end
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:
You will have to run bundle install from the app directory to ensure Rails includes the modified Gemfile:
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 = Tropo::Generator.new t.say(:value => "Hello World!") render :json => t.response end end
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 tropo.com). 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:
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: https://evening-scrubland-5986.herokuapp.com/ deployed to Heroku remote: 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:
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:
Create Tropo Application
Log into tropo.com 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!