Twilio for Salesforce: How to Answer Incoming Calls With Your CRM

Time to read: 7 minutes

March 06, 2012

Written by

Twilio

Twilion

Twilio for Salesforce: How to Answer Incoming Calls With Your CRM

One of the powerful ways you can use Twilio is to buy virtual phone numbers and control what happens when people call them. For example, you can forward calls, create conferences, present an interactive phone menu or even record voicemail.

In this post, we’ll show you how to use your Salesforce org to control phone calls in this way. By the end, you’ll understand how to combine a Force.com Site and the Twilio Helper Library for Salesforce to create intelligent voice applications.

First Steps: Hello Monkey

Let’s walk through creating your first application, Hello Monkey.

Twilio Markup Language (TwiML) lets a web application control live phone calls using XML instructions. At the start of a phone call Twilio fetches new TwiML instructions from your server. Whenever the phone performs an action such as a key press, Twilio makes another request to your server with the new data asking your application for a new set of TwiML instructions.

We’ll set up a Visualforce page in a Force.com Site to respond to Twilio’s requests for TwiML instructions.

Incoming calls pass through Twilio to Force.com

Prerequisites

To begin, you’ll need a Twilio inbound phone number. You can use a free Twilio trial account or upgrade your account and get your own dedicated phone number.

You’ll also need a Salesforce org with Force.com Sites enabled. We recommend using Developer Edition for these examples.

Finally, you’ll need to install the Twilio Helper Library for Salesforce into your Salesforce org.

Hello Monkey

Create a Visualforce page called hello_monkey (under Setup | App Setup | Develop | Pages). You can accept the default content for now.
Twilio requests TwiML from your application using a simple HTTP GET or POST. To handle these requests from Salesforce you’ll need to make your Visualforce page accessible through a Force.com Site. Go to Setup | App Setup | Develop | Sites and create a new site (if you don’t already have one). Edit the Site Visualforce Pages list and add hello_monkey. Ensure you activate the site.
Let’s say your Force.com Site’s secure web address is https://companyfoo.na14.force.com. If you point your browser to https://companyfoo.na14.force.com/hello_monkey you should see your Visualforce page.
If you’re using a trial Twilio account, browse to your Dashboard page on the Twilio website. Locate the "Sandbox App" box and paste the URL of your hello_monkey page (e.g. https://companyfoo.na14.force.com/hello_monkey) in the "Voice URL" box. Hit save and your sandbox account will now point to your new hello monkey code.
If you are using a paid Twilio account, browse to the Phone Numbers page in your account on the Twilio website. If you don’t already have a Twilio phone number, you can purchase your own phone number using the "Buy a Number" button on the right hand side of the page. Click the "Edit" link next to the phone number you would like to use. Next, check the "Voice" box, and paste the URL of your hello_monkey page (e.g. https://companyfoo.na14.force.com/hello_monkey) in the "URL" box. Hit save and this phone number will now point to your new hello monkey code.
To complete the Hello Monkey example, edit the hello_monkey Visualforce page and replace its content with this basic example code:

Now, pick up your phone and dial the number of application. Twilio will fetch your URL, https://companyfoo.na14.force.com/hello_monkey in our case, and execute the XML instructions above. First, it will "hello monkey" and then it will hang up because there are no more instructions.

Make it Personal: Greet the Caller by Name

Great! You’ve got Twilio and Salesforce talking. Now let’s make things more interesting. When someone calls, we’re going to try to greet them by name.

Because we’re adding business logic to this app, we’ll need an Apex controller. Create a new class called HelloMonkeyController:

In this example, the Apex code inspects the From parameter passed by Twilio in the request to get the Caller ID of the caller. We then search for Leads or Contacts by phone number using Apex’s built-in search syntax, which lets us match any phone number field on an object—even custom phone fields we’ve added.

We still need to wire up the Apex controller to a Visualforce page so the TwiML gets passed to Twilio when the call comes in. Replace the contents of your hello_monkey Visualforce page with the following code:

Now if the phone number matches an existing Lead or Contact record, we say their name or the word “monkey” if their Caller ID isn’t recognized. To test it out, create a Lead or Contact record with your phone number, then call your application’s phone number and listen to Twilio greet you by name.

Level Up: Connect the Call to a Second Person

What if your caller wants to talk to a real person? That’s easy to do with Twilio, but who should get the call? Since we’ve already got a Contact or Lead, let’s route the call to the record owner.

First, lets add code that prompts the caller to press a key to talk to a person or any other key to replay the menu. Replace the contents of the hello_monkey Visualforce page with the following:

Notice how the block is nested inside a block. When Twilio sees a block it starts looking for input from the caller’s key pad. Because the is nested inside the , Twilio will detect if a caller presses a key even if the key is pressed while the is still running.

When the caller presses a key, the pressed key is POSTed to the URL specified by the action handler attribute of the verb. In this case, the URL is hello_monkey_handle_key.

To respond to the key press add the code below to your Salesforce org.

1. Apex class HelloMonkeyHandleKeyController:

2. Visualforce page hello_monkey_handle_key:

Finally, add hello_monkey_handle_key to your Force.com Site’s list of Visualforce pages.

The keys pressed by the caller are transferred to the action handler as the value of the Digits parameter. The Apex controller looks up the Lead or Contact owner’s phone number and passes it to the command.

The purpose of the action="{!redirect}" attribute in the element is to forward the caller back to the main menu method if the caller did not press "1." Otherwise they’ll get the command.

To simulate the Twilio Digits request and test your response handler you can put the following URL (using your own Site URL) into your web browser, which simulates the caller pressing the digit "1":

https://companyfoo.na14.force.com/hello_monkey_handle_key?Digits=1&From=%2B13105551212

Notice the behavior of the TwiML commands in this example:

Notice how there is a block below the verb. The will "fall-through" if the call fails, the person never picks up, or the line is busy. In these cases the block underneath will execute and wish the caller goodbye!
The verb will also fall-through to the if the remote caller hangs up the phone. This lets you place additional logic after the call like using to connect to another number.
The verb lets you connect one call to another. If you want to initiate a new outgoing call rather than connect an existing call to another number check out the Twilio REST API Calls resource.