How to Use Twilio for Voice and SMS Capabilities in PHP

This guide demonstrates how to perform common programming tasks with the Twilio API service on Windows Azure. The scenarios covered include making a phone call and sending a Short Message Service (SMS) message. For more information on Twilio and using voice and SMS in your applications, see the Next Steps section.

Table of Contents

• What is Twilio?
• Twilio Pricing
• Concepts
• Create a Twilio Account
• Verify Phone Numbers
• Create a PHP Application
• Configure Your Application to Use Twilio Libraries
• How to: Make an outgoing call
• How to: Send an SMS message
• How to: Provide TwiML Responses from your own Web site

What is Twilio?

Twilio is a telephony web-service API that lets you use your existing web languages and skills to build voice and SMS applications. Twilio is a third-party service (not a Windows Azure feature and not a Microsoft product).

Twilio Voice allows your applications to make and receive phone calls. Twilio SMS allows your applications to make and receive SMS messages. Twilio Client allows your applications to enable voice communication using existing Internet connections, including mobile connections.

Twilio Pricing and Special Offers

Information about Twilio pricing is available at Twilio Pricing. Windows Azure customers receive a special offer: a free credit of 1000 texts or 1000 inbound minutes. To sign up for this offer or get more information, please visit http://ahoy.twilio.com/azure.

Concepts

The Twilio API is a RESTful API that provides voice and SMS functionality for applications. Client libraries are available in multiple languages; for a list, see Twilio API Libraries.

Key aspects of the Twilio API are Twilio verbs and Twilio Markup Language (TwiML).

Twilio Verbs

The API makes use of Twilio verbs; for example, the <Say> verb instructs Twilio to audibly deliver a message on a call.

The following is a list of Twilio verbs.

• <Dial>: Connects the caller to another phone.
• <Gather>: Collects numeric digits entered on the telephone keypad.
• <Hangup>: Ends a call.
• <Play>: Plays an audio file.
• <Pause>: Waits silently for a specified number of seconds.
• <Record>: Records the caller’s voice and returns a URL of a file that contains the recording.
• <Redirect>: Transfers control of a call or SMS to the TwiML at a different URL.
• <Reject>: Rejects an incoming call to your Twilio number without billing you
• <Say>: Converts text to speech that is made on a call.
• <Sms>: Sends an SMS message.

TwiML

TwiML is a set of XML-based instructions based on the Twilio verbs that inform Twilio of how to process a call or SMS.

As an example, the following TwiML would convert the text Hello World to speech.

<?xml version="1.0" encoding="UTF-8" ?>
<Response>
   <Say>Hello World</Say>
</Response>

When your application calls the Twilio API, one of the API parameters is the URL that returns the TwiML response. For development purposes, you can use Twilio-provided URLs to provide the TwiML responses used by your applications. You could also host your own URLs to produce the TwiML responses, and another option is to use the TwiMLResponse object.

For more information about Twilio verbs, their attributes, and TwiML, see TwiML. For additional information about the Twilio API, see Twilio API.

Create a Twilio Account

When you’re ready to get a Twilio account, sign up at Try Twilio. You can start with a free account, and upgrade your account later.

When you sign up for a Twilio account, you’ll receive an account ID and an authentication token. Both will be needed to make Twilio API calls. To prevent unauthorized access to your account, keep your authentication token secure. Your account ID and authentication token are viewable at the Twilio account page, in the fields labeled ACCOUNT SID and AUTH TOKEN, respectively.

Verify Phone Numbers

Various phone numbers need to be verified with Twilio for your account. For example, if you want to place outbound phone calls, the phone number must be verified as an outbound caller ID with Twilio. Similarly, if you want a phone number to receive SMS messages, the receiving phone number must be verified with Twilio. For information on how to verify a phone number, see Manage Numbers. Some of the code below relies on phone numbers that you will need to verify with Twilio.

As an alternative to using an existing number for your applications, you can purchase a Twilio phone number. For information about purchasing a Twilio phone number, see Twilio Phone Numbers Help.

Create a PHP Application

A PHP application that uses the Twilio service and is running in Windows Azure is no different than any other PHP application that uses the Twilio service. While Twilio services are REST-based and can be called from PHP in several ways, this article will focus on how to use Twilio services with Twilio library for PHP from Github. For more information about using the Twilio library for PHP, see http://readthedocs.org/docs/twilio-php/en/latest/index.html.

Detailed instructions for building and deploying a Twilio/PHP application to Windows Azure are available at How to Make a Phone Call Using Twilio in a PHP Application on Windows Azure.

Configure Your Application to Use Twilio Libraries

You can configure your application to use the Twilio library for PHP in two ways:

1. Download the Twilio library for PHP from Github (https://github.com/twilio/twilio-php) and add the Services directory to your application.

   -OR-

2. Install the Twilio library for PHP as a PEAR package. It can be installed with the following commands:

   $ pear channel-discover twilio.github.com/pear
   $ pear install twilio/Services_Twilio

Once you have installed the Twilio library for PHP, you can then add a require_once statement at the top of your PHP files to reference the library:

require_once 'Services/Twilio.php';

For more information, see https://github.com/twilio/twilio-php/blob/master/README.md.

How to: Make an outgoing call

The following shows how to make an outgoing call using the Services_Twilio class. This code also uses a Twilio-provided site to return the Twilio Markup Language (TwiML) response. Substitute your values for the From and To phone numbers, and ensure that you verify the From phone number for your Twilio account prior to running the code.

// Include the Twilio PHP library.
require_once 'Services/Twilio.php';

// Library version.
$version = "2010-04-01"

// Set your account ID and authentication token.
$sid = "your_twilio_account_sid";
$token = "your_twilio_authentication_token";

// The number of the phone initiating the the call.
// (Must be previously validated with Twilio.)
$from_number = "NNNNNNNNNNN";

// The number of the phone receiving call.
$to_number = "NNNNNNNNNNN";

// Use the Twilio-provided site for the TwiML response.
$url = "http://twimlets.com/message";

// The phone message text.
$message = "Hello world.";

// Create the call client.
$client = new Services_Twilio($sid, $token, $version);

//Make the call.
try
{
    $call = $client->account->calls->create(
        $from_number, 
        $to_number,
        $url.'?Message='.urlencode($message)
    );
}
catch (Exception $e) 
{
    echo 'Error: ' . $e->getMessage();
}

As mentioned, this code uses a Twilio-provided site to return the TwiML response. You could instead use your own site to provide the TwiML response; for more information, see How to Provide TwiML Responses from Your Own Web Site.

• Note: To troubleshoot SSL certificate validation errors, see http://readthedocs.org/docs/twilio-php/en/latest/usage/rest.html

How to: Send an SMS message

The following shows how to send an SMS message using the Services_Twilio class. The From number, 4155992671, is provided by Twilio for trial accounts to send SMS messages. The To number must be verified for your Twilio account prior to running the code.

// Include the Twilio PHP library.
require_once 'Services/Twilio.php';

// Library version.
$version = "2010-04-01"

// Set your account ID and authentication token.
$sid = "your_twilio_account_sid";
$token = "your_twilio_authentication_token";


$from_number = "4155992671"; // With trial account, texts can only be sent from this number.
$to_number = "NNNNNNNNNNN";
$message = "Hello world.";

// Create the call client.
$client = new Services_Twilio($sid, $token, $version);

// Send the SMS message.
try
{
    $client->account->sms_messages->create($from_number, $to_number, $message);
}
catch (Exception $e) 
{
    echo 'Error: ' . $e->getMessage();
}

How to: Provide TwiML Responses from your own Web site

When your application initiates a call to the Twilio API, Twilio will send your request to a URL that is expected to return a TwiML response. The example above uses the Twilio-provided URL http://twimlets.com/message. (While TwiML is designed for use by Web services, you can view the TwiML in your browser. For example, click http://twimlets.com/message to see an empty <Response> element; as another example, click http://twimlets.com/message?Message%5B0%5D=Hello%20World to see a <Response> element that contains a <Say> element.)

Instead of relying on the Twilio-provided URL, you can create your own URL site that returns HTTP responses. You can create the site in any language that returns HTTP responses; this topic assumes you’ll be hosting the URL in a PHP page.

The following PHP page results in a TwiML response that says Hello World on the call.

<?php    
    header("content-type: text/xml");    
    echo "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n";
?>
<Response>    
    <Say>Hello world.</Say>
</Response>

As you can see from the example above, the TwiML response is simply an XML document. The Twilio library for PHP contains classes that will generate TwiML for you. The example below produces the equivalent response as shown above, but uses the ServicesTwilioTwiml class in the Twilio library for PHP:

require_once('Services/Twilio.php');

$response = new Services_Twilio_Twiml();
$response->say("Hello world.");
print $response;

For more information about TwiML, see https://www.twilio.com/docs/api/twiml.

Once you have your PHP page set up to provide TwiML responses, use the URL of the PHP page as the URL passed into the Services_Twilio->account->calls->create method. For example, if you have a Web application named MyTwiML deployed to a Windows Azure hosted service, and the name of the PHP page is mytwiml.php, the URL can be passed to Services_Twilio->account->calls->create as shown in the following example:

require_once 'Services/Twilio.php';

$sid = "your_twilio_account_sid";
$token = "your_twilio_authentication_token";
$from_number = "NNNNNNNNNNN";
$to_number = "NNNNNNNNNNN";
$url = "http://<your_hosted_service>.cloudapp.net/MyTwiML/mytwiml.php";

$client = new Services_Twilio($sid, $token, "2010-04-01");

try
{
    $call = $client->account->calls->create(
        $from_number, 
        $to_number,
        $url.'?Message='.urlencode($message)
    );
}
catch (Exception $e) 
{
    echo 'Error: ' . $e->getMessage();
}

For additional information about using Twilio in Windows Azure with PHP, see How to Make a Phone Call Using Twilio in a PHP Application on Windows Azure.

How to: Use Additional Twilio Services

In addition to the examples shown here, Twilio offers web-based APIs that you can use to leverage additional Twilio functionality from your Windows Azure application. For full details, see the Twilio API documentation.

Next Steps

Now that you’ve learned the basics of the Twilio service, follow these links to learn more:

• Twilio Security Guidelines
• Twilio HowTo’s and Example Code
• Twilio Quickstart Tutorials
• Twilio on GitHub
• Talk to Twilio Support