Gather User Input with Keypad

Learn to gather user input through a phone's keypad with Twilio Programmable Voice by using the TwiML <Gather> verb to capture DTMF tones during a live call. You can use this guide to send voice notifications, create self-service automation, build inbound contact centers, and create outbound contact centers.

See Related reference documentation to learn more about the TwiML elements used in this guide.

Complete the prerequisites

Complete the Twilio prerequisites

Create a Twilio account.
In the Twilio Console, create a compliance profile, then buy a voice-enabled phone number.
In the legacy Console, buy a voice-enabled phone number. Only Messaging-enabled phone numbers need a compliance profile.

Complete the language prerequisites

Select your programming language and complete the prerequisites:

PythonNode.jsPHPC# or .NETJavaRuby

Install Python 3.3 or later.
Install Flask and the Twilio Python Helper Library. Using pip, run the following command:
pip install flask twilio
Install and set up ngrok.

Install Node.js 20 or later.
Install Express with body-parser, and the Twilio Node.js helper library:
npm install twilio express
Install and set up ngrok.

Install PHP 7.2 or later.
Install the Composer dependency manager globally.
Install the Twilio PHP Helper Library:
composer require twilio/sdk
Install and set up ngrok.

Install Ruby 2.6 or later.
Install Sinatra and the Twilio Ruby Helper Library:
gem install sinatra rackup puma twilio-ruby
Install and set up ngrok.

Get credentials and set as environment variables

Extract your credentials from your Twilio account then save these credentials as environment variables.

Twilio ConsoleLegacy Console

Go to the Twilio Console. The Let's get building page appears.
Click API keys and Auth tokens. The API keys & auth tokens page appears with the Auth Tokens tab selected.
Scroll to your Account SID.
Click the copy button next to your Account SID.
Run the following command, replacing YOUR_ACCOUNT_SID with your Account SID.
macOS TerminalWindows command linePowerShell
export TWILIO_ACCOUNT_SID=YOUR_ACCOUNT_SID
set TWILIO_ACCOUNT_SID=YOUR_ACCOUNT_SID
$Env:TWILIO_ACCOUNT_SID="YOUR_ACCOUNT_SID"
This command creates an environment variable on your development system for your account SID.
To display the Auth Token, click the eye button in the Primary auth token box.
Highlight and copy the Auth Token.
Run the following command, replacing YOUR_AUTH_TOKEN with your Authentication Token.
macOS TerminalWindows command linePowerShell
export TWILIO_AUTH_TOKEN=YOUR_AUTH_TOKEN
set TWILIO_AUTH_TOKEN=YOUR_AUTH_TOKEN
$Env:TWILIO_AUTH_TOKEN="YOUR_AUTH_TOKEN"
This command creates an environment variable on your development system for your auth token.

To learn more about features, see Interactive Voice Response.

Collect user input

To collect input from the user during a phone call, use the <Gather> TwiML verb. IVR systems rely on user input from the keypad.

Using the TwiML <Say> and <Play> verbs, you program the IVR voice prompts. When the IVR answers a call, it asks end users to make decisions using their phone keypad.

To forward the call to one department, the IVR tells the end user to press 1. For a different department, the IVR tells the end user to press 2.

This guide prompts the end user for a number that connects them to a certain department within the IVR system.

PythonNode.jsPHPC# or .NETJavaRuby

Python only requires the Twilio Python helper library as noted in the prerequisites.

Use <Gather> to collect user input via the keypad (DTMF tones)

1from flask import Flask
2from twilio.twiml.voice_response import VoiceResponse, Gather
3
4app = Flask(__name__)
5
6
7@app.route("/voice", methods=['GET', 'POST'])
8def voice():
9    """Respond to incoming phone calls with a menu of options"""
10    # Start our TwiML response
11    resp = VoiceResponse()
12
13    # Start our <Gather> verb
14    gather = Gather(num_digits=1)
15    gather.say('For sales, press 1. For support, press 2.')
16    resp.append(gather)
17
18    # If the user doesn't select an option, redirect them into a loop
19    resp.redirect('/voice')
20
21    return str(resp)
22
23if __name__ == "__main__":
24    app.run(debug=True)

Beyond Express and the Twilio Node.js helper library as noted in the prerequisites, Node.js requires the body-parser middleware.

Use <Gather> to collect user input via the keypad (DTMF tones)

1const express = require('express');
2const VoiceResponse = require('twilio').twiml.VoiceResponse;
3const urlencoded = require('body-parser').urlencoded;
4
5const app = express();
6
7// Parse incoming POST params with Express middleware
8app.use(urlencoded({ extended: false }));
9
10// Create a route that will handle Twilio webhook requests, sent as an
11// HTTP POST to /voice in our application
12app.post('/voice', (request, response) => {
13  // Use the Twilio Node.js SDK to build an XML response
14  const twiml = new VoiceResponse();
15
16  // Use the <Gather> verb to collect user input
17  const gather = twiml.gather({ numDigits: 1 });
18  gather.say('For sales, press 1. For support, press 2.');
19
20  // If the user doesn't enter input, loop
21  twiml.redirect('/voice');
22
23  // Render the response as XML in reply to the webhook request
24  response.type('text/xml');
25  response.send(twiml.toString());
26});
27
28// Create an HTTP server and listen for requests on port 3000
29console.log('Twilio Client app HTTP server running at http://127.0.0.1:3000');
30app.listen(3000);

PHP only requires the Twilio PHP helper library as noted in the prerequisites.

Use <Gather> to collect user input via the keypad (DTMF tones)

1<?php
2// Create a route that will handle Twilio webhook requests, sent as an
3// HTTP POST to /voice in our application
4require_once '/path/to/vendor/autoload.php';
5
6use Twilio\TwiML\VoiceResponse;
7
8// Use the Twilio PHP SDK to build an XML response
9$response = new VoiceResponse();
10
11// Use the <Gather> verb to collect user input
12$gather = $response->gather(array('numDigits' => 1));
13// use the <Say> verb to request input from the user
14$gather->say('For sales, press 1. For support, press 2.');
15
16// If the user doesn't enter input, loop
17$response->redirect('/voice');
18
19// Render the response as XML in reply to the webhook request
20header('Content-Type: text/xml');
21echo $response;

C# requires the .NET 6 framework and the Twilio C# helper library as noted in the prerequisites.

Use <Gather> to collect user input via the keypad (DTMF tones)

1// In Package Manager, run:
2// Install-Package Twilio.AspNet.Mvc -DependencyVersion HighestMinor
3
4using System.Web.Mvc;
5using Twilio.AspNet.Mvc;
6using Twilio.AspNet.Common;
7using Twilio.TwiML;
8using System;
9
10public class VoiceController : TwilioController
11{
12    [HttpPost]
13    public TwiMLResult Index()
14    {
15        var response = new VoiceResponse();
16
17        // Use the <Gather> verb to collect user input
18        response.Gather(numDigits: 1)
19		                .Say("For sales, press 1. For support, press 2.");
20        // If the user doesn't enter input, loop
21        response.Redirect(new Uri("/voice", UriKind.Relative));
22
23        return TwiML(response);
24    }
25}

Java requires Gradle or Maven and the Twilio Java helper library as noted in the prerequisites.

Use <Gather> to collect user input via the keypad (DTMF tones)

1import com.twilio.twiml.voice.Gather;
2import com.twilio.twiml.voice.Redirect;
3import com.twilio.twiml.voice.Say;
4import com.twilio.twiml.TwiML;
5import com.twilio.twiml.TwiMLException;
6import com.twilio.twiml.VoiceResponse;
7
8import javax.servlet.http.HttpServlet;
9import javax.servlet.http.HttpServletRequest;
10import javax.servlet.http.HttpServletResponse;
11import java.io.IOException;
12
13public class VoiceServlet extends HttpServlet {
14
15    public void doPost(HttpServletRequest request, HttpServletResponse response) throws IOException {
16
17        // Create a TwiML response and add our friendly message.
18        TwiML twiml = new VoiceResponse.Builder()
19                .gather(
20                        new Gather.Builder()
21                                .numDigits(1)
22                                .say(new Say.Builder("For sales, press 1. For support, press 2.").build())
23                                .build()
24                )
25                .redirect(new Redirect.Builder().url("/voice").build())
26                .build();
27
28        response.setContentType("application/xml");
29        try {
30            response.getWriter().print(twiml.toXml());
31        } catch (TwiMLException e) {
32            throw new RuntimeException(e);
33        }
34    }
35}

Ruby requires Sinatra and the Twilio Ruby helper library as noted in the prerequisites.

Use <Gather> to collect user input via the keypad (DTMF tones)

1# Get twilio-ruby from twilio.com/docs/ruby/install
2require 'sinatra'
3require 'twilio-ruby'
4
5post '/voice' do
6  Twilio::TwiML::VoiceResponse.new do |r|
7    r.gather numDigits: 1 do |g|
8      g.say(message: 'For sales, press 1. For support, press 2.')
9    end
10    r.redirect('/voice')
11  end.to_s
12end

Twilio waits for end user input. How long Twilio waits depends on the timeout you set. If the end user doesn't enter any input within this period, Twilio processes the call using other instructions in the TwiML document. When Twilio reaches the end of the TwiML document, it ends the call.

Without any end user input, Twilio repeats the prompt. To repeat the prompt, this code uses the <Redirect> verb.

The previous code doesn't include any logic that processes end user input.

Twilio repeats the prompt endlessly regardless of end user actions.

By default, if the user does enter input in the <Gather>, Twilio sends another HTTP request to the current webhook URL with a POST parameter containing the Digits entered by the user.

In the sample above, we weren't handling this input at all. Let's update that logic to also process user input if it is present.

PythonNode.jsPHPC# or .NETJavaRuby

Branch your call logic based on the digits sent by the user

1from flask import Flask, request
2from twilio.twiml.voice_response import VoiceResponse, Gather
3
4app = Flask(__name__)
5
6
7@app.route("/voice", methods=['GET', 'POST'])
8def voice():
9    """Respond to incoming phone calls with a menu of options"""
10    # Start our TwiML response
11    resp = VoiceResponse()
12
13    # If Twilio's request to our app included already gathered digits,
14    # process them
15    if 'Digits' in request.values:
16        # Get which digit the caller chose
17        choice = request.values['Digits']
18
19        # <Say> a different message depending on the caller's choice
20        if choice == '1':
21            resp.say('You selected sales. Good for you!')
22            return str(resp)
23        elif choice == '2':
24            resp.say('You need support. We will help!')
25            return str(resp)
26        else:
27            # If the caller didn't choose 1 or 2, apologize and ask them again
28            resp.say("Sorry, I don't understand that choice.")
29
30    # Start our <Gather> verb
31    gather = Gather(num_digits=1)
32    gather.say('For sales, press 1. For support, press 2.')
33    resp.append(gather)
34
35    # If the user doesn't select an option, redirect them into a loop
36    resp.redirect('/voice')
37
38    return str(resp)
39
40if __name__ == "__main__":
41    app.run(debug=True)

Use <Gather> to collect user input via the keypad (DTMF tones)

1const express = require('express');
2const VoiceResponse = require('twilio').twiml.VoiceResponse;
3const urlencoded = require('body-parser').urlencoded;
4
5const app = express();
6
7// Parse incoming POST params with Express middleware
8app.use(urlencoded({ extended: false }));
9
10// Create a route that will handle Twilio webhook requests, sent as an
11// HTTP POST to /voice in our application
12app.post('/voice', (request, response) => {
13  // Use the Twilio Node.js SDK to build an XML response
14  const twiml = new VoiceResponse();
15
16  // Use the <Gather> verb to collect user input
17  const gather = twiml.gather({ numDigits: 1 });
18  gather.say('For sales, press 1. For support, press 2.');
19
20  // If the user doesn't enter input, loop
21  twiml.redirect('/voice');
22
23  // Render the response as XML in reply to the webhook request
24  response.type('text/xml');
25  response.send(twiml.toString());
26});
27
28// Create an HTTP server and listen for requests on port 3000
29console.log('Twilio Client app HTTP server running at http://127.0.0.1:3000');
30app.listen(3000);

Branch your call logic based on the digits sent by the user

1<?php
2// Create a route that will handle Twilio webhook requests, sent as an
3// HTTP POST to /voice in our application
4require_once '/path/to/vendor/autoload.php';
5
6use Twilio\TwiML\VoiceResponse;
7
8// Use the Twilio PHP SDK to build an XML response
9$response = new VoiceResponse();
10
11// If the user entered digits, process their request
12if (array_key_exists('Digits', $_POST)) {
13    switch ($_POST['Digits']) {
14    case 1:
15        $response->say('You selected sales. Good for you!');
16        break;
17    case 2:
18        $response->say('You need support. We will help!');
19        break;
20    default:
21        $response->say('Sorry, I don\'t understand that choice.');
22    }
23} else {
24    // If no input was sent, use the <Gather> verb to collect user input
25    $gather = $response->gather(array('numDigits' => 1));
26    // use the <Say> verb to request input from the user
27    $gather->say('For sales, press 1. For support, press 2.');
28
29    // If the user doesn't enter input, loop
30    $response->redirect('/voice');
31}
32
33// Render the response as XML in reply to the webhook request
34header('Content-Type: text/xml');
35echo $response;

Branch your call logic based on the digits sent by the user

1// In Package Manager, run:
2// Install-Package Twilio.AspNet.Mvc -DependencyVersion HighestMinor
3
4using System.Web.Mvc;
5using Twilio.AspNet.Mvc;
6using Twilio.AspNet.Common;
7using Twilio.TwiML;
8using System;
9
10public class VoiceController : TwilioController
11{
12	[HttpPost]
13	public TwiMLResult Index(VoiceRequest request)
14	{
15		var response = new VoiceResponse();
16
17		if (!string.IsNullOrEmpty(request.Digits))
18		{
19			switch (request.Digits)
20			{
21				case "1":
22					response.Say("You selected sales. Good for you!");
23					break;
24				case "2":
25					response.Say("You need support. We will help!");
26					break;
27				default:
28					response.Say("Sorry, I don't understand that choice.").Pause();
29					RenderMainMenu(response);
30					break;
31			}
32		}
33		else
34		{
35			// If no input was sent, use the <Gather> verb to collect user input
36			RenderMainMenu(response);
37		}
38
39		return TwiML(response);
40	}
41
42	private static void RenderMainMenu(VoiceResponse response)
43	{
44		response.Gather(numDigits: 1)
45			.Say("For sales, press 1. For support, press 2.");
46
47		// If the user doesn't enter input, loop
48		response.Redirect(new Uri("/voice", UriKind.Relative));
49	}
50}

Branch your call logic based on the digits sent by the user

1import com.twilio.twiml.*;
2
3import javax.servlet.http.HttpServlet;
4import javax.servlet.http.HttpServletRequest;
5import javax.servlet.http.HttpServletResponse;
6import java.io.IOException;
7
8public class VoiceServlet extends HttpServlet {
9
10    public void doPost(HttpServletRequest request, HttpServletResponse response) throws IOException {
11
12        // Create a TwiML response and add our friendly message.
13        VoiceResponse.Builder builder = new VoiceResponse.Builder();
14
15        String digits = request.getParameter("Digits");
16        if (digits != null) {
17            switch (digits) {
18                case "1":
19                    builder.say(new Say.Builder("You selected sales. Good for you!").build());
20                    break;
21                case "2":
22                    builder.say(new Say.Builder("You need support. We will help!").build());
23                    break;
24                default:
25                    builder.say(new Say.Builder("Sorry, I don\'t understand that choice.").build());
26                    appendGather(builder);
27                    break;
28            }
29        } else {
30            appendGather(builder);
31        }
32
33        response.setContentType("application/xml");
34        try {
35            response.getWriter().print(builder.build().toXml());
36        } catch (TwiMLException e) {
37            throw new RuntimeException(e);
38        }
39    }
40
41    private static void appendGather(VoiceResponse.Builder builder) {
42        builder.gather(new Gather.Builder()
43                        .numDigits(1)
44                        .say(new Say.Builder("For sales, press 1. For support, press 2.").build())
45                        .build()
46                )
47                .redirect(new Redirect.Builder().url("/voice").build());
48    }
49}

Branch your call logic based on the digits sent by the user

1# Get twilio-ruby from twilio.com/docs/ruby/install
2require 'sinatra'
3require 'twilio-ruby'
4
5post '/voice' do
6  if params['Digits']
7    case params['Digits']
8    when '1'
9      Twilio::TwiML::VoiceResponse.new do |r|
10        r.say(message: 'You selected sales. Good for you!')
11      end.to_s
12    when '2'
13      Twilio::TwiML::VoiceResponse.new do |r|
14        r.say(message: 'You need support. We will help!')
15      end.to_s
16    else
17      Twilio::TwiML::VoiceResponse.new do |r|
18        r.say(message: 'Sorry, I don\'t understand that choice.')
19        r.pause
20        r.gather(numDigits: 1) do |g|
21          g.say(message: 'For sales, press 1. For support, press 2.')
22        end
23        r.redirect('/voice')
24      end.to_s
25    end
26  else
27    Twilio::TwiML::VoiceResponse.new do |r|
28      r.gather(numDigits: 1) do |g|
29        g.say(message: 'For sales, press 1. For support, press 2.')
30      end
31      r.redirect('/voice')
32    end.to_s
33  end
34end

Channel input to an action

You may want to have an entirely different endpoint in your app handle the processing of user input. This is possible using the "action" attribute of the <Gather> verb. Let's update our example to add a second endpoint that will be responsible for handling user input.

PythonNode.jsPHPC# or .NETJavaRuby

Add another route to handle the input from the user

1from flask import Flask, request
2from twilio.twiml.voice_response import VoiceResponse, Gather
3
4app = Flask(__name__)
5
6
7@app.route("/voice", methods=['GET', 'POST'])
8def voice():
9    """Respond to incoming phone calls with a menu of options"""
10    # Start our TwiML response
11    resp = VoiceResponse()
12
13    # Start our <Gather> verb
14    gather = Gather(num_digits=1, action='/gather')
15    gather.say('For sales, press 1. For support, press 2.')
16    resp.append(gather)
17
18    # If the user doesn't select an option, redirect them into a loop
19    resp.redirect('/voice')
20
21    return str(resp)
22
23
24@app.route('/gather', methods=['GET', 'POST'])
25def gather():
26    """Processes results from the <Gather> prompt in /voice"""
27    # Start our TwiML response
28    resp = VoiceResponse()
29
30    # If Twilio's request to our app included already gathered digits,
31    # process them
32    if 'Digits' in request.values:
33        # Get which digit the caller chose
34        choice = request.values['Digits']
35
36        # <Say> a different message depending on the caller's choice
37        if choice == '1':
38            resp.say('You selected sales. Good for you!')
39            return str(resp)
40        elif choice == '2':
41            resp.say('You need support. We will help!')
42            return str(resp)
43        else:
44            # If the caller didn't choose 1 or 2, apologize and ask them again
45            resp.say("Sorry, I don't understand that choice.")
46
47    # If the user didn't choose 1 or 2 (or anything), send them back to /voice
48    resp.redirect('/voice')
49
50    return str(resp)
51
52if __name__ == "__main__":
53    app.run(debug=True)

Add another route to handle the input from the user

1// Create a route that will handle Twilio webhook requests, sent as an
2// HTTP POST to /voice in our application
3app.post('/voice', (request, response) => {
4  // Use the Twilio Node.js SDK to build an XML response
5  const twiml = new VoiceResponse();
6
7  const gather = twiml.gather({
8    numDigits: 1,
9    action: '/gather',
10  });
11  gather.say('For sales, press 1. For support, press 2.');
12
13  // If the user doesn't enter input, loop
14  twiml.redirect('/voice');
15
16  // Render the response as XML in reply to the webhook request
17  response.type('text/xml');
18  response.send(twiml.toString());
19});
20
21// Create a route that will handle <Gather> input
22app.post('/gather', (request, response) => {
23  // Use the Twilio Node.js SDK to build an XML response
24  const twiml = new VoiceResponse();
25
26  // If the user entered digits, process their request
27  if (request.body.Digits) {
28    switch (request.body.Digits) {
29      case '1':
30        twiml.say('You selected sales. Good for you!');
31        break;
32      case '2':
33        twiml.say('You need support. We will help!');
34        break;
35      default:
36        twiml.say("Sorry, I don't understand that choice.");
37        twiml.pause();
38        twiml.redirect('/voice');
39        break;
40    }
41  } else {
42    // If no input was sent, redirect to the /voice route
43    twiml.redirect('/voice');
44  }
45
46  // Render the response as XML in reply to the webhook request
47  response.type('text/xml');
48  response.send(twiml.toString());
49});

Add another route to handle the input from the user

1<?php
2// Create a route that will handle Twilio webhook requests, sent as an
3// HTTP POST to /voice in our application
4require_once '/path/to/vendor/autoload.php';
5
6use Twilio\TwiML\VoiceResponse;
7
8// Use the Twilio PHP SDK to build an XML response
9$response = new VoiceResponse();
10
11// Use the <Gather> verb to collect user input
12$gather = $response->gather(array('numDigits' => 1, 'action' => '/gather'));
13// use the <Say> verb to request input from the user
14$gather->say('For sales, press 1. For support, press 2.');
15
16// If the user doesn't enter input, loop
17$response->redirect('/voice');
18
19// Render the response as XML in reply to the webhook request
20header('Content-Type: text/xml');
21echo $response;

Implement an 'action' URL to handle user input

1<?php
2// Create a route that will handle Twilio Gather verb action requests,
3// sent as an HTTP POST to /gather in our application
4require_once '/path/to/vendor/autoload.php';
5
6use Twilio\TwiML\VoiceResponse;
7
8// Use the Twilio PHP SDK to build an XML response
9$response = new VoiceResponse();
10
11// If the user entered digits, process their request
12if (array_key_exists('Digits', $_POST)) {
13    switch ($_POST['Digits']) {
14    case 1:
15        $response->say('You selected sales. Good for you!');
16        break;
17    case 2:
18        $response->say('You need support. We will help!');
19        break;
20    default:
21        $response->say('Sorry, I don\'t understand that choice.');
22        $response->redirect('/voice');
23    }
24} else {
25    // If no input was sent, redirect to the /voice route
26    $response->redirect('/voice');
27}
28
29// Render the response as XML in reply to the webhook request
30header('Content-Type: text/xml');
31echo $response;

Add another route to handle the input from the user

1// In Package Manager, run:
2// Install-Package Twilio.AspNet.Mvc -DependencyVersion HighestMinor
3
4using System.Web.Mvc;
5using Twilio.AspNet.Mvc;
6using Twilio.AspNet.Common;
7using Twilio.TwiML;
8using System;
9
10public class VoiceController : TwilioController
11{
12	[HttpPost]
13	public TwiMLResult Index()
14	{
15		var response = new VoiceResponse();
16		response.Gather(numDigits: 1, action: new Uri("/voice/gather", UriKind.Relative))
17			    .Say("For sales, press 1. For support, press 2.");
18
19		// If the user doesn't enter input, loop
20		response.Redirect(new Uri("/voice", UriKind.Relative));
21
22		return TwiML(response);
23	}
24
25
26	[HttpPost]
27	public TwiMLResult Gather(VoiceRequest request)
28	{
29		var response = new VoiceResponse();
30
31		// If the user entered digits, process their request
32		if (!string.IsNullOrEmpty(request.Digits))
33		{
34			switch (request.Digits)
35			{
36				case "1":
37					response.Say("You selected sales. Good for you!");
38					break;
39				case "2":
40					response.Say("You need support. We will help!");
41					break;
42				default:
43					response.Say("Sorry, I don't understand that choice.").Pause();
44					response.Redirect(new Uri("/voice", UriKind.Relative));
45					break;
46			}
47		}
48		else
49		{
50			// If no input was sent, redirect to the /voice route
51			response.Redirect(new Uri("/voice", UriKind.Relative));
52		}
53
54		return TwiML(response);
55	}
56}

Add another route to handle the input from the user

1import com.twilio.twiml.*;
2
3import javax.servlet.http.HttpServlet;
4import javax.servlet.http.HttpServletRequest;
5import javax.servlet.http.HttpServletResponse;
6import java.io.IOException;
7
8public class VoiceServlet extends HttpServlet {
9
10    public void doPost(HttpServletRequest request, HttpServletResponse response) throws IOException {
11
12        // Create a TwiML response and add our friendly message.
13        TwiML twiml = new VoiceResponse.Builder()
14                .gather(new Gather.Builder()
15                        .numDigits(1)
16                        .action("/gather")
17                        .say(new Say.Builder("For sales, press 1. For support, press 2.").build())
18                        .build()
19                )
20                .redirect(new Redirect.Builder().url("/voice").build())
21                .build();
22
23        response.setContentType("application/xml");
24        try {
25            response.getWriter().print(twiml.toXml());
26        } catch (TwiMLException e) {
27            throw new RuntimeException(e);
28        }
29    }
30}

Add another route to handle the input from the user

1# Get twilio-ruby from twilio.com/docs/ruby/install
2require 'sinatra'
3require 'twilio-ruby'
4
5post '/voice' do
6  Twilio::TwiML::VoiceResponse.new do |r|
7    r.gather(numDigits: 1, action: '/gather') do |g|
8      g.say(message: 'For sales, press 1. For support, press 2.')
9    end
10
11    # If the user doesn't enter input, loop
12    r.redirect('/voice')
13  end.to_s
14end
15
16post '/gather' do
17  if params['Digits']
18    case params['Digits']
19    when '1'
20      Twilio::TwiML::VoiceResponse.new do |r|
21        r.say(message: 'You selected sales. Good for you!')
22      end.to_s
23    when '2'
24      Twilio::TwiML::VoiceResponse.new do |r|
25        r.say(message: 'You need support. We will help!')
26      end.to_s
27    else
28      Twilio::TwiML::VoiceResponse.new do |r|
29        r.say(message: 'Sorry, I don\'t understand that choice.')
30        r.pause
31        r.redirect('/voice')
32      end.to_s
33    end
34  else
35    Twilio::TwiML::VoiceResponse.new do |r|
36      r.redirect('/voice')
37    end.to_s
38  end
39end

The action attribute accepts a relative URL. This URL points to another route that your server can handle. To handle our call logic with separate code paths, use actions and redirects.

Use cases for keypad input with Twilio Programmable Voice

This guide covers a feature for the following use cases:

Send voice notifications with Twilio Programmable Voice

You can use this guide to send voice notifications that require a quick user response. For example, you can programmatically alert users about fraudulent activity on an account and prompt them to confirm or deny the transaction immediately using their phone's keypad.

To learn more advanced features that you can use with voice notifications, see Voice notifications.

Create self-service automation with Twilio Programmable Voice

You can use this guide to build phone systems that resolve customer requests without human intervention. For example, callers can securely authenticate their identity, check their bank account balance, or update an appointment status entirely by using keypad menus.

To learn more advanced features that you can use with self-service automation, see Voice self-service automation.

Create an inbound contact center with Twilio Programmable Voice

You can use this guide to route incoming customer calls to the right agent or department efficiently. By deploying an interactive keypad menu, you can direct customers based on their explicit selections, minimizing wait times and transfers.

To learn more advanced features that you can use with inbound contact centers, see Voice inbound contact center.

Create an outbound contact center with Twilio Programmable Voice

You can use this guide to enhance proactive customer outreach with immediate routing controls. For example, when an outbound dialer connects with a customer, it can offer keypad options to speak with a live agent, schedule a callback, or opt out of future communications.

To learn more advanced features that you can use with outbound contact centers, see Voice outbound contact center.

Result

After following this guide, you can successfully collect DTMF tones from a user's telephone keypad during a phone call using Twilio Programmable Voice. You can test your system by calling your Twilio phone number, pressing the keypad buttons when prompted, and verifying that your application branches its logic based on the collected digits.

Next steps

Explore the following guides to build on what you've learned in this guide:

Build an Interactive Voice Response (IVR) phone tree: Step through full sample applications to construct advanced multi-level menus.
Respond to incoming phone calls: Learn how to handle inbound webhooks and generate initial TwiML responses for your callers.
Make outbound phone calls: Learn how to programmatically initiate outbound calls and generate TwiML responses for those calls.