Get Started

Appointment Reminder

Appointment reminder is an application that calls a phone number and presents the call recipient with an automated reminder. A dentist, doctor, or even car repair shop could use a similar system to remind customers about upcoming appointments.

Usage

A customer enters a phone number and clicks the "Call" button on a webpage. Our app tells Twilio to initiate an outgoing call to that number and reads the recipient the appointment details. The recipient is then presented with a menu asking if she would like to (1) repeat the menu, (2) get direction to the appointment, or (3) hang up.

This HowTo is written in ruby using the Ruby on Rails framework. The code is written for Rails version 2.1 or higher.

Concepts

This howto shows how to make outgoing calls using the Twilio REST API, the usage of the TwiML <Say>, <Gather> and <Redirect> verbs.

Download

appointmentreminder.zip

Implementation

  • 1

    • Our 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.

      • howtos/appointmentreminder/index.html.erb
        <h1>Twilio phone reminder demo</h1>
        <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. Upon submission the user's browser requests /appointmentreminder/makecall which makes a request to the Twilio REST API using the twilio-ruby library. This initiates an outgoing call to the number the user entered.

      To make the REST API request we take advantage of the twilio-ruby gem. It simplifies the the process of making HTTP requests to Twilio and handling the responses. You can get more information about the twilio-ruby gem here or just install it with sudo gem install twilio-ruby.

      • howtos/appointmentreminder/appointmentreminder_controller.rb
        require "twilio-ruby"
        
        class AppointmentreminderController < ApplicationController
        
          # your Twilio authentication credentials
          ACCOUNT_SID = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
          ACCOUNT_TOKEN = 'YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY'
        
          # base URL of this application
          BASE_URL = "http://www.yourserver.com:3000/appointmentreminder"
        
          # Outgoing Caller ID you have previously validated with Twilio
          CALLER_ID = 'NNNNNNNNNN'
        
          def index
          end
        
          # 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
            data = {
              :from => CALLER_ID,
              :to => params['number'],
              :url => BASE_URL + '/reminder',
            }
        
            begin
              client = Twilio::REST::Client.new(ACCOUNT_SID, ACCOUNT_TOKEN)
              client.account.calls.create data
            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 that if you would like to copy and use this code there are several account specific variables you will need to replace including ACCOUNT_SID, ACCOUNT_TOKEN, CALLER_ID, and BASE_URL. For more information on making outgoing calls take a look at the REST Quickstart.

  • 2

    • When the user picks up the phone, Twilio makes an HTTP request to /reminder which was indicated as the 'Url' parameter in the Twilio REST request above. Our rails app processes that request and returns TwiML (Twilio XML) with the reminder message and a short menu of options.

      • howtos/appointmentreminder/appointmentreminder_controller.rb
          # TwiML response that reads the reminder to the caller and presents a
          # short menu: 1. repeat the msg, 2. directions, 3. goodbye
          def reminder
            @post_to = BASE_URL + '/directions'
            render :action => "reminder.xml.builder", :layout => false 
          end
            
  • 3

    • Here is the template used to render the reminder.

      • howtos/appointmentreminder/reminder.xml.builder
        xml.instruct!
        xml.Response do
            xml.Gather(:action => @post_to, :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
            
  • 4

    • The caller hears the reminder and the menu and enters a choice on the phone keypad. Twilio gathers that input and makes an HTTP request to the <Gather> 'action' handler (in this case /directions) with 'Digits' set to the input from the keypad. The /directions rails handler inspects the 'Digits' parameter to determine which response to send.

      • howtos/appointmentreminder/appointmentreminder_controller.rb
          # 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
        
            @redirect_to = BASE_URL + '/reminder'
            render :action => "directions.xml.builder", :layout => false 
          end
            
  • 5

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