Telephony applications have come a long way since the days when you had to build complicated integrations with several providers, each using their own API. One of the services that is excelling at abstracting the relationship between integrators and providers is Twilio, a popular platform that lets developers put in place different types of communications applications.

While Twilio deals with the telephony complexity behind the scenes, they give developers an easy to use set of APIs that enable the creation of different types of applications. In this article, we’ll use Twilio to create a voice mail system that notifies you by email whenever someone leaves a message. As you’ll soon find out, coding will be limited, but we recommend some knowledge of HTTP and PHP.

By reading this article, you’ll also understand why Twilio is so popular among integrators. We feel that Twilio is a good model for other API providers check out. You may see the features highlighted in this walkthrough as things to similarly offer to developers that are consuming your API.

Scope of the Project

One of the biggest complaints people have when using voice mail is how unfriendly the whole system feels. One solution is to make receiving and reading messages more straightforward. Users who don’t like to use voice mail at all, for example, may prefer to receive an email message whenever a caller leaves a message.

Our project consists of the development of a voice mail system that not only records messages left by people that call your cell phone but also sends you an email notification with a link to the recording. The project is composed of several steps that you’ll need to complete before the voice mail system is up and running:

1. Creating a Twilio account
2. Getting a Twilio phone number
3. Configuring the Voice Request URL
4. Implementing the Record action URL
5. Testing the solution
6. Configuring your cell phone

Let’s start with the first step to get you up and running with a Twilio account.

1. Creating a Twilio account

Twilio makes it very easy to create a trial account. You just have to open the Twilio Website on your browser and click on the “Sign Up” button on the top right-hand corner.

After you complete the form you will be presented with a verification system that sends you an SMS message to a phone number of your choice. If you can’t receive SMS messages Twilio can call you instead. Twilio requires this first validation step in order to use your phone number as a caller ID.

2. Getting a Twilio Phone Number

After passing the validation test, Twilio will immediately present you with a phone number to play with. If, for some reason, you don’t like your number you can always choose another one from the list of available numbers.

You’ll now be able to test sending and receiving SMS messages with your new number so that you see how things work. After you’re done with this initial testing you should go to your account where you can continue implementing our project.

3. Configuring the Voice Request URL

To start, click on “Numbers” on the top navigation menu. Unfortunately, Twilio doesn’t provide a free phone number with voice capabilities so you’ll have to buy one. To do that click on “Buy a number” and make sure you select Voice on the “Capabilities” setting.

After you have your new number, go back to the “Numbers” menu option and click on it. You should now see a “Voice” section with a form entry called “Request URL.” To enable that, first make the following XML available on the Web and copy its URL:

  
  Please leave a message after the tone.  
    

Paste the URL where the XML is located in the “Request URL” form field and then click on the “Save” button at the bottom. To test it you can call your Twilio number and you should hear a voice saying the message “Please leave a message after the tone.”

The XML file you’ve just created is, in fact, called a TwiML file. TwiML is the Twilio Markup Language and it lets developers tell Twilio how it should behave in certain actions. In our case, our TwiML file provides a set of Response instructions to be executed whenever someone makes a phone call to your number.

On the second line of the TwiML file, the Say tag will instruct Twilio to voice whatever message is inside it. The third line of our TwiML file uses a Record tag. This tag tells Twilio that it should capture and record audio throughout the rest of the phone call. The timeout attribute sets the maximum duration for the recording, in seconds. The most important parameter is the action tag, which instructs Twilio what to do right after the recording has been made. Next we’ll see how to implement this URL.

4. Implementing the Record Action URL

Now that you can receive calls and greet your callers with a message, you still have to send an email notification after someone leaves a message. To do that, let’s use PHP to implement the Record action URL. Twilio makes an HTTP POST call to that URL with all the information you’ll need.

<?php  
$from = $_POST['Caller'];  
$url = $_POST['RecordingUrl'];

mail(  
     '{yourEmailAddress}',  
     'New call from ' . $from,  
     'You have a new call from ' . $from . '.' .  
     "\n\n" .  
     'A voice mail is available at ' . $url  
    );

You should replace {yourEmailAddress} with the email address where you want to receive the voice mail notifications. After that, place this PHP script somewhere where it can successfully run and copy its URL. Go back to the XML file created before and replace {actionURL} with the URL of this PHP script and you’re all set.

This PHP script starts by grabbing the caller phone number and the voice recording URL (lines 2 and 3) from the HTTP POST parameters Caller and RecordingUrl. It then uses PHP’s mail() function to send an email notification to a given email address. We use PHP’s mail() function here for simplicity but you can use any email provider of your choice, e.g., SendGrid or Mailgun.

5. Testing the Solution

Now, when you call your Twilio number you should hear a voice asking you to leave a message. After you hang up, you should also receive an email notification like this one:

You have a new call from CALLERPHONE.

A voice mail is available at https://api.twilio.com/2010-04-01/Accounts/YOURACCOUNT/Recordings/RECORDING

Click on the voice mail link and you’ll be able to listen to the voice mail message from any connected device!

6. Configuring Your Cell Phone to Use The Voice Mail System

To make everything work as intended you still need to configure your cell phone to use the voice mail system you just created. To do that, you’ll have to redirect three types of calls to your Twilio number:

• When busy: your cell provider will forward the call to your Twilio number whenever you’re busy, e.g., in the middle of another call.
• When unanswered: the call will be forwarded to your Twilio number whenever you don’t answer a call, which is the usual behavior of a voice mail system.
• When unreachable: if you’re unreachable, e.g., out of the network, calls will be forwarded to your Twilio number.

After you configure these settings the information will be shared with your cell provider and, even if your cell phone is disconnected, calls will be forwarded to your Twilio number.

Conclusion

The lack of complexity in this project demonstrates how an API provider can reduce implementation friction for developers. Twilio’s fluid approach to API call workflow is made possible with their TwiML XML-based language, and communication based on Web hooks. In fact, the only part of this project that requires writing unique code is telling Twilio to send an email notification after recording a voice mail.

After attempting this project you should feel better prepared to build other integrations using Twilio. If you’re an API provider yourself, use Twilio as a good example to follow. It’s amazing how a well structured, developer oriented product can boost creativity and allow the creation of all sorts of integrations.

Are you already using Twilio? Let us know what you think of this project. Leave a comment here or get in touch to discuss this more!