On Apache
Under GNU General Public License
2012-05-25 08:53 @38.107.179.240 Crawled by CCBot/1.0 (+http://www.commoncrawl.org/bot.html)
WWW::Twilio::API(3pm) User Contributed Perl Documentation WWW::Twilio::API(3pm)
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:
1. 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"
2. 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"
3. 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'.
4. 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
5. 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');
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.
SEE ALSO
LWP(1), <http://www.twilio.com/>
AUTHOR
Scott Wiersdorf, <scott AT perlcode.org>
COPYRIGHT AND LICENSE
Copyright (C) 2009 by Scott Wiersdorf
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.
perl v5.10.0 2009-09-19 WWW::Twilio::API(3pm)
Generated by $Id: phpMan.php,v 4.49 2006/02/26 13:18:18 chedong Exp $ Author: Che Dong
On Apache
Under GNU General Public License
2012-05-25 08:53 @38.107.179.240 Crawled by CCBot/1.0 (+http://www.commoncrawl.org/bot.html)