NAME

WWW::Twilio::API - Accessing Twilio's REST API with Perl

SYNOPSIS

use WWW::Twilio::API;

my $twilio = WWW::Twilio::API->new(AccountSid => 'AC12345...',
                                   AuthToken  => '1234567...');

## make a phone call
$response = $twilio->POST( 'Calls',
                           Caller => '1234567890',
                           Called => '8905671234',
                           Url    => 'http://domain.tld/send_twiml' );

print $response->{content};

DESCRIPTION

WWW::Twilio::API aims to make connecting to and making REST calls on the Twilio API easy, reliable, and enjoyable.

You should have ready access to Twilio's API documentation in order to use WWW::Twilio::API.

WWW::Twilio::API knows almost nothing about the Twilio API itself other than the authentication and basic format of the REST URIs.

Users familiar with the API may skip the following section labeled "TWILIO API" and move to the "METHODS" section. Beginner should definitely continue here.

TWILIO API

This section is meant to help you understand how to read the Twilio API documentation and translate it into WWW::Twilio::API calls.

The Twilio API documentation is found here:

http://www.twilio.com/docs/api_reference/REST/

The Twilio REST API consists of requests and responses. Requests consist of Resources and Properties. Responses consist of HTTP status codes and often content. What resources, properties, status codes and content you should use is what the Twilio REST API documentation covers.

Getting started

While what comes next is covered in the Twilio documentation, this may help some people who want a quicker start. Head over to twilio.com and signup for a free demo account. Once you've signed up, visit

https://www.twilio.com/user/account/

where you'll find your Account Sid and AuthToken. Your Account Sid and AuthToken are essentially your username and password for the Twilio API. Note that these are not the same credentials as your Twilio account login username and password, which is an email address and a password you've selected. You'll never use your email address and password in the API--those are only for logging into your Twilio account at twilio.com.

Once you've signed up, be sure to add at least an Outgoing CallerID number in your account by clicking "Phone Numbers" and then "Add A Caller ID". Be sure you're near the phone whose number you entered, as Twilio will make an automated call to verify it. Once you've added a phone number, you can start playing with Twilio's Calls API, which we'll be using in some of our examples below.

Twilio requests

Twilio request resources look just like a URL you might enter into your browser to visit a secure web page:

https://api.twilio.com/2008-08-01/Accounts/{YourAccountSid}/Calls

In addition to the URI above, if the request is a POST (as opposed to a GET), you would also pass along certain key/value pairs that represent the resources's properties.

So, to place a call using Twilio, your resource is:

https://api.twilio.com/2008-08-01/Accounts/{YourAccountSid}/Calls

and the set of properties for this resource might be:

Called = 4155551212
Caller = 4158675309
Url = http://www.myapp.com/myhandler

You can see the list of properties for the Calls resource here:

http://www.twilio.com/docs/api_reference/REST/making_calls

Twilio responses

Once you have made a request to a Twilio resource, the Twilio API server will send a response back to you. The response consists of an HTTP status code (e.g., 200, 302, 404, 500) and some content (usually an XML document).

For example, if we made the POST to the Calls resource above, and if everything went well, we'd receive a status of 200 and an XML document like this, telling us that everything went great:

<TwilioResponse>
  <Call>
    <Sid>CA42ed11f93dc08b952027ffbc406d0868</Sid>
    <CallSegmentSid/>
    <AccountSid>AC309475e5fede1b49e100272a8640f438</AccountSid>
    <Called>4155551212</Called>
    <Caller>4158675309</Caller>
    <PhoneNumberSid>PN01234567890123456789012345678900</PhoneNumberSid>
    <Status>0</Status>
    <StartTime>Thu, 03 Apr 2008 04:36:33 -0400</StartTime>
    <EndTime/>
    <Price/>
    <Flags>1</Flags>
  </Call>
</TwilioResponse>

Using WWW::Twilio::API

Now that we have a basic understanding of how Twilio's REST API works, we can translate the API into WWW::Twilio::API method calls. Doing this is trivial:

Find the API resource you want to do (e.g., make a call, check accounts, verify a caller id, etc.) in the manual. Look at the Base Resource URI, and take note of everything after "/2008-08-01/Accounts/{YourAccountSid}/" (e.g., Calls).

Please see the exception for Accounts above in the section "API resource name" under the GET method.

This is your API resource: "Calls"
Determine which HTTP method you need to make to make the call. For example, to view details about a call, you'll use the GET method for the Calls resource. To make a new call, you'll use the POST method for the Calls resource. Both use the same resource, but different HTTP methods, depending on what you want to do.

This is your API method. "GET"
Determine the resource properties you'll need to send. Most GET methods don't require any parameters, but may require additional information in the resource (e.g., to view details about all calls, your resource will simply be "Calls", whereas to look at a particular call, your resource will look like "Calls/CA42ed11f93dc08b952027ffbc406d0868")

If you're using a POST method to make your call, you should see a table under Resource Properties and the phrase "Call POST Parameters" in the upper left of the table. If the phrase says "Call Resource Properties" instead, the table is describing what the results will look like, not what parameters you may send.

These are your resource parameters: Caller = '1234567890', Called = '3216540987', Url = 'http://perlcode.org/cgi-bin/twilio'.

Create a WWW::Twilio::API object and make the call using the API method, API resource, and resource parameters. The pattern you'll follow looks like this:

$response = $twilio_object->METHOD(Resource, %parameters);

For these examples, see the following pages in Twilio's API documentation:

http://www.twilio.com/docs/api_reference/REST/call
http://www.twilio.com/docs/api_reference/REST/making_calls

Here are the examples:

## create an object
my $twilio = new WWW::Twilio::API( AccountSid => '{your account sid}',
                                   AuthToken  => '{your auth token}' );

## view a list of calls we've made
$response = $twilio->GET('Calls');
print $response->{content};  ## this is an XML document

## view one particular call we've made
$response = $twilio->GET('Calls/CA42ed11f93dc08b952027ffbc406d0868');
print $response->{content};  ## this is an XML document

## make a new call
$response = $twilio->POST('Calls',
                          Caller => '1234567890',
                          Called => '3126540987',
                          Url    => 'http://perlcode.org/cgi-bin/twilio');
print $response->{content};  ## this is an XML document

Examine the response to make sure things went ok. If your response code isn't 200 (or whatever the normal code for the resource and method you're using is), something went wrong and you should check for any error codes:

$response = $twilio->POST('Calls');  ## I forgot my parameters!

unless( $response->{code} == 200 ) {
  die <<_UNTIMELY_;
  Error: ($response->{code}): $response->{message}
  $response->{content}
_UNTIMELY_
}

which would print:

(400): Bad Request
<?xml version="1.0"?>
<TwilioResponse>
  <RestException>
    <Status>400</Status>
    <Message>No called number is specified</Message>
    <Code>21201</Code>
    <MoreInfo>http://www.twilio.com/docs/errors/21201</MoreInfo>
  </RestException>
</TwilioResponse>

See how useful that is? Everything you need to know: "No called number is specified" might jog your memory into realizing that you didn't specify anything else either.

Once we've fixed everything up, we can try again:

$response->$twilio->POST('Calls',
                         Called => '1234567890',
                         Caller => '3126540987',
                         Url    => 'http://perlcode.org/cgi-bin/twilio');

print $response->{content};

which now prints:

<?xml version="1.0"?>
<TwilioResponse>
  <Call>
    <Sid>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</Sid>
    <DateCreated>Fri, 11 Sep 2009 11:33:20 -0700</DateCreated>
    <DateUpdated>Fri, 11 Sep 2009 11:33:20 -0700</DateUpdated>
    <CallSegmentSid/>
    <AccountSid>ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</AccountSid>
    <Called>1234567890</Called>
    <Caller>3216540987</Caller>
    <PhoneNumberSid>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</PhoneNumberSid>
    <Status>0</Status>
    <StartTime/>
    <EndTime/>
    <Duration/>
    <Price/>
    <Flags>10</Flags>
    <Annotation/>
  </Call>
</TwilioResponse>

Excellent! This pattern works for all API methods (see note on "Accounts" in the "API resource name" section above under the GET method).

What's Missing? TwiML

The missing magical piece is the TwiML, which is supplied by the Url resource parameter you may have noticed above in the Calls resource examples.

TwiML controls the flow of your call application, including responding to key presses, playing audio files, or "reading" text-to-speech phrases to the person on the other end of the line.

To continue the Calls example, You will need to give the Calls resource a URL that returns TwiML (see http://www.twilio.com/docs/api_reference/TwiML/). This is not hard, but it does require you to have a web server somewhere on the Internet that can reply to GET or POST requests.

A TwiML document looks like this:

<?xml version="1.0" encoding="UTF-8" ?>
<Response>
  <Say>Hello World</Say>
  <Play>http://api.twilio.com/Cowbell.mp3</Play>
</Response>

When the Twilio API's Calls resource is invoked with a URL that returns an XML document like the above, Twilio's servers will first "read" the phrase "Hello World" to the caller using a text-to-speech synthesizer. It will then download Cowbell.mp3 and play it to the caller.

Note that the URL you supply may be a static file, or it may be a script or other handler that can receive a GET or POST from Twilio's API server.

If you don't have your own web server, one location you might consider temporarily is one used in Twilio's own examples, which simply creates a TwiML document based on whatever arguments you send it:

http://twimlets.com/message?Message=$MSG

where $MSG is a URI encoded string of what you want Twilio to say when the person who is called picks up the phone.

For example, you could say:

http://twimlets.com/message?Message=Nice+to+meet+you

and when you did this:

$twilio->POST('Calls',
              Caller => '1112223333',
              Called => '1231231234',
              Url    => 'http://twimlets.com/message?Message=Nice+to+meet+you');

Twilio's API would call '123-123-1234' and when someone answers, they will hear "Nice to meet you" in a somewhat computerized voice.

Go ahead and follow the twimlets.com link above and view the source in your browser window. It's just a plain XML document.

See http://www.twilio.com/docs/api_reference/TwiML/ for full TwiML documentation.

METHODS

This section describes all the available methods in detail.

new

Creates a new Twilio object.

Available parameters:

AccountSid: Your account sid (begins with 'AC')
AuthToken: Your account auth token.
API_VERSION: Defaults to '2008-08-01'. You won't need to set this unless: a) Twilio updates their API, and b) you want to take advantage of it.

Example:

my $twilio = new WWW::Twilio::API( AccountSid => 'AC...',
                                   AuthToken  => '...' );

General API calls

All API calls are of the form:

$twilio_object->METHOD('Resource', %parameters)

where METHOD is one of GET, POST, PUT, or DELETE, and 'Resource' is the resource URI after removing the leading "/2008-08-01/Accounts/{YourAccountSid}/".

Note that you do not need to URI encode the parameters; WWW::Twilio::API handles that for you (this just means that you don't have to do anything special with the parameters you give the WWW::Twilio::API object).

Note: There is one exception to URI encoding: when you are passing a
I<Url> parameter (e.g., to the I<Calls> resource), and that URL
contains a B<GET> query string, that query string needs to be URI
encoded. See the F<examples.pl> file with this distribution for an
example of that.

Each of GET, POST, PUT, and DELETE returns a hashref with the call results, the most important of which is the content element. This is the untouched, raw response of the Twilio API server, suitable for you to do whatever you want with it. For example, you might want to hand it off to an XML parser:

$resp = $twilio->GET('Calls');

use XML::LibXML;
my $parser = new XML::LibXML;
my $doc = $parser->parse_string($resp->{content});
... do some processing on $doc now ...

What you do with the results is up to you.

Here are the (current) elements in the response:

content

Contains the response content (in XML or CSV or HTML if specified).

code

Contains the HTTP status code. You should check this after each call to make sure it's what you'd expect (according to the API). Most successful responses will be '200', but some are '204' or others.

message

A brief HTTP status message, corresponding to the status code. For 200 codes, the message will be "OK". For "400" codes, the message will be "Bad Request" and so forth.

For the curious, a complete list of HTTP status codes, messages and explanations may be found here:

http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

Example:

$response = $twilio->GET('Calls/CA42ed11f93dc08b952027ffbc406d0868');

$response is a hashref that looks like this:

{
  content => '<an xml string>',
  code    => '200',
  message => 'OK',
}

CSV and HTML content

By default, results come back in XML and are stored in the response's content element. You may wish to have results returned in comma-separated value format. To do this, simply append '.csv' to the end of your API resource:

$resp = $twilio->GET('Calls.csv');

The same thing works for HTML: simply append '.html' to the end of your API resource.

GET

Sends a GET request to the Twilio REST API.

Available parameters:

API resource name

The first argument to GET should always be the API resource name you want to invoke. Examples include Accounts, Calls, Recordings and so on. It may be a multi-level resource name, such as Recordings/{RecordingSid}/Transcriptions. It may also have a particular instance you want to see, such as Calls/CA42ed11f93dc08b952027ffbc406d0868.

The one exception is the Accounts resource. For the Accounts resource, you may specify 'Accounts', an empty string, or nothing (for GET requests only), since there is nothing after the common URI base ("/2008-08-01/Accounts/{YourAccountSid}"). Using Accounts is recommended for orthogonality with other resources, and to be clear, especially when you're using a POST method.

You may wish to append '.csv' or '.html' to the API resource to receive results in CSV (comma-separated values) or HTML formats, instead of the default XML. See "CSV and HTML content" above.

API resource parameters

Each API resource takes zero or more key-value pairs as parameters. See the POST method below for examples.

None of the following examples use resource parameters; see the POST section for examples illustrating the use of resource parameters.

GET examples:

## get a list of all calls
$response = $twilio->GET('Calls');

## get a single call instance in CSV format
$response = $twilio->GET('Calls/CA42ed11f93dc08b952027ffbc406d0868.csv');

## get a recording list in XML
$response = $twilio->GET('Recordings');

## get a recording list in HTML
$response = $twilio->GET('Recordings.html');

POST

Sends a POST request to the Twilio REST API.

Available parameters:

Same as GET.

The following examples illustrate the use of an API resource with resource parameters:

## validate a CallerId: 'OutgoingCallerIds' is the API resource and
## everything else are resource parameters
$response = $twilio->POST('OutgoingCallerIds',
                          FriendlyName => "Some Caller Id",
                          PhoneNumber  => '1234567890');

## make a phone call
$response = $twilio->POST('Calls',
                          Caller => '1231231234',
                          Called => '9081231234',
                          Url    => 'http://some.where/handler');

## send an SMS message
$response = $twilio->POST('SMS/Messages',
                          From => '1231231234',
                          To   => '9081231234',
                          Body => "Hey, let's have lunch" );

PUT

Sends a PUT request to the Twilio REST API.

Available parameters:

Same as GET.

DELETE

Sends a DELETE request to the Twilio REST API.

Available parameters:

Same as GET.

Example:

$response = $twilio->DELETE('Recordings/RE41331862605f3d662488fdafda2e175f');

API CHANGES

By default, all API calls are against the 2008-08-01 API. If you need to call against a different API, you may pass it into the constructor:

$t = WWW::Twilio::API->new( AccountSid  => '...',
                            AuthToken   => '...',
                            API_VERSION => 'YYYY-MM-DD' );

where 'YYYY-MM-DD' is the new API version.

EXAMPLES

There are plenty of examples strewn in the documentation above. If you need more, see the examples.pl file with this distribution; also please see Twilio's own REST API documentation and TwiML documentation.

AUTHOR

Scott Wiersdorf, <scott@perlcode.org>

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.1 or, at your option, any later version of Perl 5 you may have available.

To install WWW::Twilio::API, copy and paste the appropriate command in to your terminal.

cpanm

cpanm WWW::Twilio::API

CPAN shell

perl -MCPAN -e shell
install WWW::Twilio::API

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

TWILIO API

Getting started

Twilio requests

Twilio responses

Using WWW::Twilio::API

What's Missing? TwiML

METHODS

new

General API calls

CSV and HTML content

GET

POST

PUT

DELETE

API CHANGES

EXAMPLES

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions