Drupal as an IVR? Just add Twilio.

Before the web was used to provide users data access and to automate customer service, there were IVRs. You know these ubiquitous technologies by experience if not by name. You use them to pay bills by phone, check account balances or even register for classes.

If you have ever wanted to integrate telephony into your website, you should checkout Twilio. Not only is the integration pretty straightforward, it's amazing all that you can do.

Using Twilio’s quick start tutorials, I put together a short demo to help you jump in.

Answering the call

To start you will need to install the Twilio module. You will also need a Twilio number. You can get a demo number for free.

Next we want to use Drupal to answer calls to that number. Start in Drupal by going to admin > configuration > twilio (admin/config/system/twilio). At the bottom of the page under Module callback, you will notice two urls with the voice one ending in twilio/voice. If you point your Twilio number to this endpoint, the hook hook_ twilio_voice_incoming will fire enabling you to custom program how you want the call handled.

For our demo we are going to avoid custom programming, so we are going to use the TwiML feature of the Twilio module. TwiML is a messaging protocol for providing instructions to Twilio. To create a TwiML, simply click the TwiML Manager tab from the Twilio configuration page (i.e. admin/config/system/twilio/twiml)

Note: don’t worry about inputting the Account SID and other required fields for this demo. They are only needed for outbound phone calls and SMS messages.

Create a "demo start" TwiML using the form at the bottom of the TwiML Manager and input:

Name: Demo start
Machine name: demo_start
TwiML:

<Response>
  <Say>Hello.</Say>
  <Gather action="https://getlevelten.com/twilio/twiml/demo_uid_check" method="POST">
    <Say>To proceed, enter your user I.D. followed by the pound sign.</Say>
  </Gather>
</Response>

(Note: just make the action = "/twilio/twiml/demo_uid_check". The text filters on our blog keep adding the full domain which is not intended.)

When you save the TwiML, a new endpoint URL is created and displayed in the TwiML Manager list table. It should follow the format: http://[yourdomain]/twilio/twiml/demo_start

Copy this url and paste it into the voice request URL in Twilio. This setting can be found in your Twilio account by click the Numbers menu then clicking your demo phone number.

Once you have saved the setting, call your demo number. If everything is setup correctly, the “Say” messages in the demo TwiML will be played back to you.

Looking at the code for the TwiML we just executed, the “Say” tag function should be self-explanatory. The Gather tag allow us to do something pretty interesting. It enables us to request input from the user's phone. This tag is instructing Twilio to gather user input and then submit the result to the action /twilio/twiml/demo_uid_check.

UID check TwiLM

Next we want to create the "Demo uid check" TwiML to process the user input. From the TwiML Manager in Drupal add another TwiML using the settings:

Name: Demo uid check
Machine name: demo_uid_check
TwiML:

<?php
  $account = user_load($_REQUEST['Digits']);
  if(empty($account->name)) {
    header("Location: /twilio/twiml/demo_uid_error");
    die;
  }
?>
<Response>
  <Say>Thank you, <?php echo $account->name; ?>. I will now transfer you.</Say>
  <Dial>+10015551212</Dial>
  <Say>The call failed or the remote party hung up. Goodbye.</Say>
</Response>

(Replace +10015551212 with an actual number you want to forward to.)

Now call your demo number back and enter a valid user id from your site. If everything is connected correctly you should hear the Say tags from the uid check TwiML and the phone call should be transferred to the number specified in the Dial tag.

This script contains some dynamic PHP elements. The PHP code is designed to lookup the user account from Drupal using the inputted digits ($_REQUEST['Digits']) to both validate the user and to play back the name.

Summing up

This was just a quick example of how you can use Twilio to interact with Drupal to provide data and IVR functionality. Twilio offers an array of quickstart recipes that show you how to do all kinds of useful tricks with both phone calls and SMS texts. Following the recipes you can use Drupal to implement call tracking, click to call features, phone number verification, call recording/voice mail, call routing and auto attendant and more.

The use case I was working on was call tracking and SMS notifications upon receiving phone calls and form submissions. If you would like to see it in action, check out the Intelligence Twilio submodule in the latest dev release of Intelligence. I am hoping to get a release rolled out in the next couple of weeks.

Important note: for security reasons, I recommend putting any php code that returns dynamic data into a custom module using the Twilio hooks rather than the TwiML Manager. The TwiML Manager comes in quite handy for a quick demo, however for a production app if you are not careful the PHP eval feature of the TwiML output can create security vulnerabilities.

Are you using Twilio and Drupal to do some cool stuff? I would love to hear your comments.

photo by: pixle