Create Tasks from Phone Calls using TwiML: Receive an Incoming Call

We've seen how to create Tasks using the TaskRouter REST API and how to accept a Task Reservation using both the REST API and Assignment Callback instructions. TaskRouter also introduces new TwiML instructions that you can use to create a Task from a Twilio phone call.

Receive an Incoming Call

To receive an incoming phone call, we first need a Twilio phone number. In this example we'll use a US toll-free number, but you can use a Voice capable number from any country.

Before purchasing or setting up the phone number, we need to add on to our server.rb to handle incoming calls:

server.rb

1require 'rubygems'
2require 'twilio-ruby'
3require 'sinatra'
4require 'json'
5
6set :port, 8080
7
8# Get your Account Sid and Auth Token from twilio.com/user/account
9account_sid = 'AC99ba7b61fbdb6c039698505dea5f044c'
10auth_token = '{{ auth_token }}'
11workspace_sid = '{{ workspace_sid }}'
12workflow_sid = '{{ workflow_sid }}'
13
14client = Twilio::REST::Client.new(account_sid, auth_token)
15
16post '/assignment_callback' do
17  # Respond to assignment callbacks with accept instruction
18  content_type :json
19  {"instruction": "accept"}.to_json
20end
21
22get '/create-task' do
23  # Create a task
24  task = client.taskrouter.workspaces(workspace_sid)
25                            .tasks
26                            .create(
27                                attributes: {
28                                      'selected_language' => 'es'
29                            }.to_json,
30                                workflow_sid: workflow_sid
31                            )
32  task.attributes
33end
34
35get '/accept_reservation' do
36  # Accept a Reservation
37  task_sid = params[:task_sid]
38  reservation_sid = params[:reservation_sid]
39
40  reservation = client.taskrouter.workspaces(workspace_sid)
41                        .tasks(task_sid)
42                        .reservations(reservation_sid)
43                        .update(reservation_status: 'accepted')
44  reservation.worker_name
45end
46
47get '/incoming_call' do
48  Twilio::TwiML::VoiceResponse.new do |r|
49    r.gather(action: '/enqueue_call', method: 'POST', timeout: 5, num_digits: 1) do |gather|
50      gather.say(message: 'Para Español oprime el uno.', language: 'es')
51      gather.say(message: 'For English, please hold or press two.', language: 'en')
52    end
53  end.to_s
54end

You can use the Buy Numbers section of the Twilio Voice and Messaging web portal to purchase a new phone number, or use an existing Twilio phone number. Open the phone number details page and point the Voice Request URL at your new endpoint:

Voice call webhook settings with ngrok URL for incoming calls.

Using any phone, call the Twilio number. You will be prompted to press one for Spanish or two for English. However, when you press a digit, you'll hear an error message. That's because our <Gather> verb is pointing to another endpoint, /enqueue_call, which we haven't implemented yet. In the next step, we'll add the required endpoint and use it to create a new Task based on the language selected by the caller.

Next: Create a Task using Enqueue »