/ 
Twilio-2.000000
/ Twilio

NAME

Twilio - Community Perl library for the Twilio API

VERSION

Version 2.000000

SYNOPSIS

use Twilio;

# Credentials from TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN, or given
my $client = Twilio->new;
my $client = Twilio->new($account_sid, $auth_token);
my $client = Twilio->new($api_key_sid, $api_key_secret, { account_sid => $account_sid });

# Send an SMS
my $message = $client->messages->create('+15558675310', {
  from => '+15017122661',
  body => 'Hello from Perl',
});
print $message->sid, "\n";

# Make a call
my $call = $client->calls->create('+15558675310', '+15017122661', {
  url => 'http://demo.twilio.com/docs/voice.xml',
});

# Read a list, 20 at most
for my $message ($client->messages->read({ to => '+15558675310' }, 20)) {
  print $message->body, "\n";
}

# Any other product, by its name and version
$client->verify->v2->services($service_sid)->verifications->create('+15558675310', 'sms');

# Errors are exceptions, which read as their message
my $sent = eval { $client->messages->create($to, { from => $from, body => 'Hi' }) };
warn "Not sent: $@\n" if !$sent;

# Reply to an incoming SMS, in the webhook of your number
use Twilio::TwiML::MessagingResponse;

my $response = Twilio::TwiML::MessagingResponse->new;
$response->message('Thanks for your message!');
print "Content-Type: text/xml\n\n", $response;

DESCRIPTION

A library for the Twilio API. It follows Twilio's official libraries for PHP, Python and Node.js closely, so Twilio's documentation and its examples apply to it.

For a guide, read Twilio::Manual. It follows Twilio's messaging and voice quickstarts: it sends an SMS, receives and replies to one, makes a call and answers one, and then covers credentials, webhook validation, lists, errors, other products, and how to translate any example from Twilio's documentation.

This module only makes the client. Twilio->new returns a Twilio::Rest::Client, where every product starts.

METHODS

new

my $client = Twilio->new($username, $password, \%options);

The same as Twilio::Rest::Client->new, with the same arguments, and it returns a Twilio::Rest::Client. $username and $password are an Account SID and Auth Token, or an API key and its secret, which then needs account_sid in the options. With no arguments, the credentials come from the TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN environment variables. See Twilio::Base::BaseClient for the options.

Version 1.x took named arguments (sid => ..., token => ...). Those are refused with a Twilio::Exceptions::ConfigurationException, so that old code fails at once instead of at its first request.

WHAT IT COVERS

HOW IT FOLLOWS THE OFFICIAL LIBRARIES

It has the structure of Twilio's official libraries, which are generated from the same specifications: the client, then a product and its version, then the list of a resource, the context of one record, and the record. Where the official libraries differ, it follows twilio-php: method names, the order of required values, paging, and how errors and TwiML are written.

A documentation example becomes Perl with a few rules: names in snake_case, required values first as plain arguments, optional values in a hash reference, and eval for errors. "TRANSLATING TWILIO'S EXAMPLES" in Twilio::Manual lists them, with a PHP and a Python example side by side.

HOW IT IS BUILT

The modules under Twilio::Rest are generated, as the official libraries' are, from Twilio's OpenAPI specifications, by a generator that applies the rules of Twilio's own and decides unclear cases the way twilio-php does. Their documentation comes from the descriptions in the specifications. The TwiML modules are generated from the names in twilio-php.

The rest is written by hand: HTTP, authentication, paging, errors, TwiML, tokens and validation. It is ported from twilio-php, with choices from twilio-python and twilio-node where those are better. Only requests that Twilio refused with HTTP 429 are ever sent again, so a message is never sent twice.

HOW IT IS TESTED

  • Unit tests for every hand-written module, with a fake HTTP client, so they need no account and no network.

  • Access tokens, capability tokens, webhook signatures and TwiML are compared with what twilio-php itself produces.

  • Each of the 1,563 operations is checked against its specification: its URL, method, values and their formats, and the reading of every documented answer.

  • The hand-written tests of twilio-php, twilio-python and twilio-node were compared case by case with these, and the missing cases added.

  • Optional live tests call the real API.

  • Every example in Twilio::Manual is run by the tests.

  • Continuous integration on Linux, macOS and Windows, with Perl 5.16 and the latest Perl.

SEE ALSO

Twilio::Manual, Twilio::Rest::Client, Twilio::Base::BaseClient, and Twilio's documentation at https://www.twilio.com/docs.

COMMUNITY LIBRARY

This is an independent, community-maintained library. It is not written, endorsed or supported by Twilio Inc. "Twilio" is a trademark of Twilio Inc.

BUGS

Please report bugs at https://github.com/Zarabozo/Twilio/issues.

AUTHOR

Francisco Zarabozo <zarabozo@cpan.org>

LICENSE

Copyright (c) 2026 Francisco Zarabozo.

This library is free software, released under the MIT License. See the LICENSE file in this distribution.

Parts of it are based on Twilio's own MIT-licensed work, twilio-php and the twilio-oai specifications. As that license requires, LICENSE also includes Twilio's copyright notice for them, as credit.