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',
                           From => '1234567890',
                           To   => '8905671234',
                           Url  => 'http://domain.tld/send_twiml' );

print $response->{content};

COMPATIBILITY NOTICE

This section is for existing WWW::Twilio::API users considering an upgrade from WWW::Twilio::API versions prior to 0.15. If you're new to WWW::Twilio::API you may safely unconcern yourself with this section and move on to "DESCRIPTION" below.

WWW::Twilio::API since version 0.15 defaults to Twilio's 2010-04-01 API. That is the only substantive change from version 0.14. If you are one of those types of people who must have the latest version of everything, you have two options:

Before you upgrade to 0.15, change all of your new() method calls to explicitly use API_VERSION as '2008-08-01', like this:
```
my $twilio = WWW::Twilio::API->new
  ( AccountSid  => 'AC12345...',
    AuthToken   => '1234567...',
    API_VERSION => '2008-08-01' );  ## <-- add this line here
```
Now you may safely upgrade WWW::Twilio::API and stay current. You can then update your individual Twilio API calls piecemeal at your leisure.
Go through all of your existing GET, PUT, POST, and DELETE calls and make sure that they're up-to-date with Twilio's new '2010-04-01' API (the new API is a little simpler in some ways than the 2008 version) and set the API_VERSION to '2010-04-01'. Test that your code all works with the new API.

Now you can safely upgrade WWW::Twilio::API.

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 already familiar with the API may skip the following section labeled "TWILIO API" and move to the "METHODS" section. Beginners 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/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 web account at twilio.com.

Once you've signed up, be sure to add at least one phone number to your account by clicking "Numbers" and then "Verify a number". 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/2010-04-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/2010-04-01/Accounts/{YourAccountSid}/Calls

and the set of properties for this resource might be:

To   = 5558675309
From = 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/rest/making_calls

Further down in "METHODS" we'll cover how this works using WWW::Twilio::API, but here's a teaser to help you see how easy your job as a budding Twilio developer will be:

## call Jenny
$twilio->POST('Calls',
              To => '5558675309',
              From => '4158675309',
              Url => 'http://www.myapp.com/myhandler');

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:

<?xml version="1.0"?>
<TwilioResponse>
  <Call>
    <Sid>CAxxxxxxxxxx</Sid>
    <DateCreated>Wed, 10 Aug 2011 04:38:16 +0000</DateCreated>
    <DateUpdated>Wed, 10 Aug 2011 04:38:16 +0000</DateUpdated>
    <ParentCallSid/>
    <AccountSid>ACxxxxxxxx</AccountSid>
    <To>+15558675309</To>
    <ToFormatted>(555) 867-5309</ToFormatted>
    <From>+14158675309</From>
    <FromFormatted>(415) 867-5309</FromFormatted>
    <PhoneNumberSid>PNxxxxxxxxxxx</PhoneNumberSid>
    <Status>queued</Status>
    <StartTime/>
    <EndTime/>
    <Duration/>
    <Price/>
    <Direction>outbound-api</Direction>
    <AnsweredBy/>
    <ApiVersion>2010-04-01</ApiVersion>
    <Annotation/>
    <ForwardedFrom/>
    <GroupSid/>
    <CallerName/>
    <Uri>/2010-04-01/Accounts/ACxxxxxxxxx/Calls/CAxxxxxx</Uri>
    <SubresourceUris>
      <Notifications>/2010-04-01/Accounts/ACxxxxxxxxxxx/Calls/CAxxxxxxx/Notifications</Notifications>
      <Recordings>/2010-04-01/Accounts/ACxxxxxxxxxx/Calls/CAxxxxxx/Recordings</Recordings>
    </SubresourceUris>
  </Call>
</TwilioResponse>

Don't let all this HTTP request/response (or XML) business worry you: WWW::Twilio::API makes requests and handles responses for you, so you don't have to get involved with all the details. Besides, you can also opt to have Twilio send its responses to you in CSV, JSON, or HTML.

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 "/2010-04-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, consult the Twilio documentation for making calls and you should see a table under POST Parameters describing the required and optional parameters you may send in your API call.

These are your resource parameters for the Calls API: From = '1234567890', To = '5558675309', Url = 'http://perlcode.org/cgi-bin/twilio'.

Also, if you want your response in something other than XML, you may add any of 'csv', 'json', or 'html' (any representation found at http://www.twilio.com/docs/api/rest/tips) to the Twilio API call:
```
## return JSON in $response->{content}
$response = $twilio->POST('Calls.json',
                          To   => '5558675309',
                          From => '1234567890',
                          Url  => 'http://twimlets.com/callme');

## CSV list of recordings
$response = $twilio->POST('Recordings.csv');
```
See "Alternative resource representations" below.

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/rest/call
http://www.twilio.com/docs/api/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.json');
print $response->{content};  ## this is a JSON document

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

## make a new call
$response = $twilio->POST('Calls',
                          From => '1234567890',
                          To   => '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:

## call Jenny
$response = $twilio->POST('Calls',
                          To   => '5558675309',
                          From => '3126540987',
                          Url  => 'http://perlcode.org/cgi-bin/twilio');

print $response->{content};

which now prints:

<?xml version="1.0"?>
<TwilioResponse>
  <Call>
    <Sid>CAxxxxxxxxxx</Sid>
    <DateCreated>Wed, 10 Aug 2011 04:38:16 +0000</DateCreated>
    <DateUpdated>Wed, 10 Aug 2011 04:38:16 +0000</DateUpdated>
    <ParentCallSid/>
    <AccountSid>ACxxxxxxxx</AccountSid>
    <To>+15558675309</To>
    <ToFormatted>(555) 867-5309</ToFormatted>
    <From>+13126540987</From>
    <FromFormatted>(312) 654-0987</FromFormatted>
    <PhoneNumberSid>PNxxxxxxxxxxx</PhoneNumberSid>
    <Status>queued</Status>
    <StartTime/>
    <EndTime/>
    <Duration/>
    <Price/>
    <Direction>outbound-api</Direction>
    <AnsweredBy/>
    <ApiVersion>2010-04-01</ApiVersion>
    <Annotation/>
    <ForwardedFrom/>
    <GroupSid/>
    <CallerName/>
    <Uri>/2010-04-01/Accounts/ACxxxxxxxxx/Calls/CAxxxxxx</Uri>
    <SubresourceUris>
      <Notifications>/2010-04-01/Accounts/ACxxxxxxxxxxx/Calls/CAxxxxxxx/Notifications</Notifications>
      <Recordings>/2010-04-01/Accounts/ACxxxxxxxxxx/Calls/CAxxxxxx/Recordings</Recordings>
    </SubresourceUris>
  </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/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.

Twilio provides a set of canned TwiML applications for you to use for free on their server, or you may download them and modify them as you wish. Twilio's "Twimlets" may be found here:

http://labs.twilio.com/twimlets/

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',
              From => '1112223333',
              To   => '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 '2010-04-01'. You won't need to set this unless: a) Twilio updates their API, and b) you want to take advantage of it or c) you've coded against an older API version and need to set this for backward compatibility.

NOTE: WWW::Twilio::API prior to version 0.15 defaulted to '2008-08-01'; if you're upgrading WWW::Twilio::API, see "COMPATIBILITY" section at the top of this documentation.

Example:

my $twilio = new WWW::Twilio::API( AccountSid => 'AC...',
                                   AuthToken  => '...',
                                   API_VERSION => '2008-08-01' );

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 "/2010-04-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, CSV, JSON, 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',
}

Alternative resource representations

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 JSON and HTML: simply append '.json' or '.html' respectively to the end of your API resource. See http://www.twilio.com/docs/api/rest/tips for other possible representations.

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 ("/2010-04-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', '.json' or '.html' to the API resource to receive results in CSV (comma-separated values), JSON, or HTML formats, instead of the default XML. See "Alternative resource representations" 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. Be sure to check Twilio's API for correct arguments for the current Twilio API version.

## 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 (note: this is for Twilio's 2008-08-01 API)
$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

Versions of WWW::Twilio::API prior to 0.15 defaulted to 2008-08-01. API calls since WWW::Twilio::API version 0.15 and later are against Twilio's 2010-04-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 (or old) 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.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 824:: Non-ASCII character seen before =encoding in '2009–2011'. Assuming UTF-8

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

COMPATIBILITY NOTICE

DESCRIPTION

TWILIO API

Getting started

Twilio requests

Twilio responses

Using WWW::Twilio::API

What's Missing? TwiML

METHODS

new

General API calls

Alternative resource representations

GET

POST

PUT

DELETE

API CHANGES

EXAMPLES

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions