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.


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.


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



  • 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!">

        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
              # base URL of this application
              BASE_URL = ""
              # Outgoing Caller ID you have previously validated with Twilio
              CALLER_ID = 'NNNNNNNNNN'
              def index
              # Use the Twilio REST API to initiate an outgoing call
              def makecall
                if !params['number']
                  redirect_to :action => '.', 'msg' => 'Invalid phone number'
                # parameters sent to Twilio REST API
                data = {
                  :from => CALLER_ID,
                  :to => params['number'],
                  :url => BASE_URL + '/reminder',
                  client =, ACCOUNT_TOKEN)
                  client.account.calls.create data
                rescue StandardError => bang
                  redirect_to :action => '.', 'msg' => "Error #{bang}"
                redirect_to :action => '', 'msg' => "Calling #{params['number']}..."

          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 
        • 3

          • Here is the template used to render the reminder.

              • howtos/appointmentreminder/reminder.xml.builder
                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."
          • 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'
                      if !params['Digits'] or params['Digits'] != '2'
                        redirect_to :action => 'reminder'
                      @redirect_to = BASE_URL + '/reminder'
                      render :action => "directions.xml.builder", :layout => false 
            • 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>.