Routing phone calls to volunteers with Twilio

In the past week or so, I’ve been working on a Laravel application that enables groups of volunteers to be added to a call tree; a phone number comes in, then gets routed to one of the active volunteers’ phone. A lot of the core functionality is there, but the app isn’t quite ready to release to the general public. There’s something of a time-crunch, however, as the main reason for building the application is to connect people who need rides to their polling places with volunteers in the days leading up to the critical 2018 midterm elections.

Here’s the concept: someone in need of a ride calls a Twilio number, which then rings up to ten (10) volunteers’ phones. Whomever picks up first gets the call, and they can work through arranging transportation.

Building the application has been an awesome introduction to telephony service providers like Twilio, which combine voice and SMS messaging with web applications. Using Twilio’s TwiML (Twilio Markup Language), I can write simple XML documents to describe how to respond to different messages. I have a lot of features planned as far as routing calls more intelligently and letting volunteers mark themselves as unavailable, but I wanted to get the bare-bones TwiML out to the public as far ahead of Election Day as possible.

Getting started with Twilio

In order to route calls to volunteers with Twilio, you’ll need to purchase a Twilio phone number ($1/month). The only capability necessary at this point is voice, but grabbing a more capable number may be better if you plan to hold onto the number for a long time.

Once you’ve done registered a number, we’ll get started creating our first TwiML Bin: visit the Runtime › TwiML Bins page to create your new TwiML Bin.

What are TwiML Bins? Think of them as scripts that are stored on Twilio’s servers, which our Twilio phone numbers can interact with. They let us write out simple TwiML documents instead of calling out to an external HTTP service (as Volunteer Line will do).

Give your new TwiML Bin a name that’s meaningful to you, and populate it with the following TwiML:

A few things to note here:

First, all phone numbers are written using the E.164 format. When writing US phone numbers, they will always begin with “+1”, followed by the area code and number (e.g. “(555) 867-5309” becomes “+15558675309”).

Next, the callerId attribute on the Dial element is the number that will show up on the volunteers’ phones. This can’t just be any old number, but using the Twilio number will help volunteers recognize that the incoming call is from this service.

Finally, the <Dial> element can contain up to 10 child <Number> nodes. Twilio will attempt to dial all of these phone numbers, and the first number to pick up will be connected.

In the above example, any calls to our Twilio number (+15558675309) will be forwarded to our lone volunteer at +18005555555. To the volunteer, calls will appear to be coming from the Twilio number, rather than the individual caller. If more volunteers are recruited, their numbers would then be added as new <Number> nodes (again, up to 10).

Routing calls to TwiML Bins

Once your TwiML Bin has been defined and populated with [real] numbers, now it’s time to configure your Twilio number to use your TwiML Bin. Visit your list of Twilio phone numbers, then select your number from the list.

You’ll need to select “TwiML” for “A Call Comes In”, then select the name of your TwiML Bin.

Once those changes have been saved, try giving your Twilio number a call; if everything went according to plan, your phone should start ringing with a new, inbound call from your Twilio number!

Please use these newfound powers for good, and remember to vote by November 6!