WWW::Twilio::API - Accessing Twilio's REST API with Perl
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};
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.
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.
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.
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 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:
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');
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.
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).
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.
This section describes all the available methods in detail.
Creates a new Twilio object.
Available parameters:
Your account sid (begins with 'AC')
Your account auth token.
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.
No default. This is a code reference you may pass in. The code reference will receive the internal LWP::UserAgent object immediately after it is created so you can set up proxies, timeouts, etc.
If set to a true value, will use URI::Escape's uri_escape_utf8 instead of uri_escape.
uri_escape_utf8
uri_escape
Example:
my $twilio = new WWW::Twilio::API ( AccountSid => 'AC...', AuthToken => '...', API_VERSION => '2008-08-01', LWP_Callback => sub { shift->timeout(30) } );
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:
Contains the response content (in XML, CSV, JSON, or HTML if specified).
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.
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
$response = $twilio->GET('Calls/CA42ed11f93dc08b952027ffbc406d0868');
$response is a hashref that looks like this:
{ content => '<an xml string>', code => '200', message => 'OK', }
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.
Sends a GET request to the Twilio REST API.
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.
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');
Sends a POST request to the Twilio REST API.
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" );
Sends a PUT request to the Twilio REST API.
Sends a DELETE request to the Twilio REST API.
$response = $twilio->DELETE('Recordings/RE41331862605f3d662488fdafda2e175f');
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.
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.
LWP(1), http://www.twilio.com/
Scott Wiersdorf, <scott@perlcode.org>
Copyright (C) 2009–2012 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.
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.