Twilio

The appointment reminder Rails app has a single controller and several XML builder views. The index page shows a simple form that accepts a phone number from the user.

<h2>Twilio phone reminder demo</h2>
<h2 style="color: #ff0000"><%= params['msg'] %></h2>
<h3>Enter your phone number to receive an automated reminder</h3>
<form action="/appointmentreminder/makecall" method="post">
    <input type="text" name="number" />
    <input type="submit" value="Call me!">
</form>

The user enters a phone number and presses the Call me! button. The browser requests the the makecall page which makes a request to the Twilio REST URL /2008-08-01/Accounts/ACCCOUNT_SID/Calls (where ACCCOUNT_SID is your Twilio account identifier) which initiate an outgoing call.

To make the REST call we take advantage of the free Ruby REST API library provided by Twilio. It simplified the the process of making HTTPS requests to Twilio and processing the responses. You can download a copy of the of the REST Ruby libraries here. In this demo was have placed rest the REST library in 'lib/twiliorest.rb' and having included in this controller using a 'require "twiliorest.rb"' statement.

require "twiliorest.rb"

# your Twilio authentication credentials
ACCOUNT_SID = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
ACCOUNT_TOKEN = 'YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY'

# version of the Twilio REST API to use
API_VERSION = '2008-08-01'

# base URL of this application
BASE_URL = "http://demo.twilio.com/appointmentreminder"

# Outgoing Caller ID you have previously validated with Twilio
CALLER_ID = 'NNNNNNNNNN'

class AppointmentreminderController < ApplicationController
  
  # Use the Twilio REST API to initiate an outgoing call
  def makecall
      if !params['number']
          redirect_to({ :action => '.', 'msg' => 'Invalid phone number' })
          return
      end
      
      # parameters sent to Twilio REST API
      d = {
          'Caller' => CALLER_ID,
          'Called' => params['number'],
          'Url' => BASE_URL + '/reminder',
      }
      begin
          account = TwilioRest::Account.new(ACCOUNT_SID, ACCOUNT_TOKEN)
          resp = account.request(
              "/#{API_VERSION}/Accounts/#{ACCOUNT_SID}/Calls",
              'POST', d)
          resp.error! unless resp.kind_of? Net::HTTPSuccess
      rescue StandardError => bang
          redirect_to({ :action => '.', 'msg' => "Error #{ bang }" })
          return
      end
      
      redirect_to({ :action => '', 
          'msg' => "Calling #{ params['number'] }..." })
  end

When the form is submitted with a phone number, a request is made to the Twilio REST API to initiate a new outgoing call. NOTE: If you would like to copy and use this code there are several account specific variables you will need to fill in including ACCOUNT_SID, ACCOUNT_TOKEN, CALLER_ID, and BASE_URL. For more information on making outgoing calls take a look at the REST Quickstart.

When the phone picks up Twilio makes an HTTP request to the /reminder page which was indicated as part of the REST request. The Rails processes that requests and returns TwiML formatted XML with the reminder message and a short menu of options.

# TwiML response that says the reminder to the caller and presents a
# short menu: 1. repeat the msg, 2. directions, 3. good bye
def reminder
    @postto = BASE_URL + '/directions'
    
    respond_to do |format|
        format.xml { @postto }
    end
end

Here is the template used to render the reminder.

xml.instruct!
xml.Response do
    xml.Gather(:action => @postto, :numDigits => 1) do
        xml.Say "Hello this is a call from Twilio.  You have an appointment
tomorrow at 9 AM."
        xml.Say "Please press 1 to repeat this menu. Press 2 for directions.
Or press 3 if you are done."
    end
end

The caller hears the reminder and the menu and enters their choice on the phone keypad. Twilio gathers that input and makes an HTTP request to the Gather action handler '/directions' with Digits set to the input from the keypad. The 'directions' Rails handler inspects the Digits to determine which page to return.

# TwiML response that inspects the caller's menu choice:
# - says good bye and hangs up if the caller pressed 3
# - repeats the menu if caller pressed any other digit besides 2 or 3
# - says the directions if they pressed 2 and redirect back to menu
def directions
    if params['Digits'] == '3'
        redirect_to :action => 'goodbye'
        return
    end
    
    if !params['Digits'] or params['Digits'] != '2'
        redirect_to :action => 'reminder'
        return
    end
    
    @redirectto = BASE_URL + '/reminder',
    respond_to do |format|
        format.xml { @redirectto }
    end
end

Here is the template that says the directions. Notice the <Redirect> tag which instructs Twilio to redirect execution to another URL once it has completed the Say.

xml.instruct!
xml.Response do
    xml.Say "Your appointment is located in a building near a road."
    xml.Redirect @redirectto
end