NAME

       SMS::AQL - Perl extension to send SMS text messages via AQL's SMS service

SYNOPSIS

         # create an instance of SMS::AQL, passing it your AQL username
         # and password (if you do not have a username and password,
         # register at www.aql.com first).

         $sms = new SMS::AQL({
           username => 'username',
           password => 'password'
         });

         # other parameters can be passed like so:
         $sms = new SMS::AQL({
           username => 'username',
           password => 'password',
           options => { sender => '+4471234567' }
         });

         # send an SMS:

         $sms->send_sms($to, $msg) || die;

         # called in list context, we can see what went wrong:
         my ($ok, $why) = $sms->send_sms($to, $msg);
         if (!$ok) {
             print "Failed, error was: $why\n";
         }

         # params for this send operation only can be supplied:
         $sms->send_sms($to, $msg, { sender => 'bob the builder' });

         # make a phone call and read out a message:
         my ($ok, $why) = $sms->voice_push($to, $msg);

DESCRIPTION

       SMS::AQL provides a nice object-oriented interface to send SMS text messages using the
       HTTP gateway provided by AQ Ltd (www.aql.com) in the UK.

       It supports concatenated text messages (over the 160-character limit of normal text
       messages, achieved by sending multiple messages with a header to indicate that they are
       part of one message (this is handset-dependent, but supported by all reasonably new
       mobiles).

METHODS

       new (constructor)
           You must create an instance of SMS::AQL, passing it the username and password of your
           AQL account:

             $sms = new SMS::AQL({ username => 'fred', password => 'bloggs' });

           You can pass extra parameters (such as the default sender number to use, or a proxy
           server) like so:

             $sms = new SMS::AQL({
               username => 'fred',
               password => 'bloggs',
               options  => {
                   sender => '+44123456789012',
                   proxy  => 'http://user:pass@host:port/',
               },
             });

       send_sms($to, $message [, \%params])
           Sends the message $message to the number $to, optionally using the parameters supplied
           as a hashref.

           If called in scalar context, returns 1 if the message was sent, 0 if it wasn't.

           If called in list context, returns a two-element list, the first element being 1 for
           success or 0 for fail, and the second being a message indicating why the message send
           operation failed.

           You must set a sender, either at new or for each send_sms call.

           Examples:

             if ($sms->send_sms('+44123456789012', $message)) {
                 print "Sent message successfully";
             }

             my ($ok, $msg) = $sms->send_sms($to, $msg);
             if (!$ok) {
                 print "Failed to send the message, error: $msg\n";
             }

       voice_push($to, $message [, \%params])
           Make a telephone call to the given phone number, using speech synthesis to read out
           the message supplied.

           $to and $message are the destination telephone number and the message to read out.
           The third optional parameter is a hashref of options to modify the behaviour of this
           method - currently, the only option is:

           skipintro
               Skips the introductory message that AQL's system normally reads out. (If you use
               this, it's recommended to add your own introduction to your message, for example
               "This is an automated call from ACME Inc...")

           If called in scalar context, returns 1 if the message was sent, 0 if it wasn't.

           If called in list context, returns a two-element list, the first element being 1 for
           success or 0 for fail, and the second being a message indicating why the operation
           failed.

           Note that, at the current time, this feature supports only UK telephone numbers.

       credit()
           Returns the current account credit. Returns undef if any errors occurred

       last_status()
           Returns the status of the last command: 1 = OK, 0 = ERROR.

       last_error()
           Returns the error message of the last failed command.

       last_response()
           Returns the raw response from the AQL gateway.

       last_response_text()
           Returns the last result code received from the AQL gateway in a readable format.

           Possible codes are:

           AQSMS-AUTHERROR
               The username and password supplied were incorrect

           AQSMS-NOCREDIT
               Out of credits (The account specified did not have sufficient credit)

           AQSMS-OK
               OK (The message was queued on our system successfully)

           AQSMS-NOMSG
               No message or no destination number were supplied

SEE ALSO

       http://www.aql.com/

AUTHOR

       David Precious, <davidp@preshweb.co.uk>

       All bug reports, feature requests, patches etc welcome.

COPYRIGHT AND LICENSE

       Copyright (C) 2006-2008 by David Precious

       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.7 or, at your option, any later version of
       Perl 5 you may have available.

THANKS

        - to Adam Beaumount and the AQL team for their assistance
        - to Ton Voon at Altinity (http://www.altinity.com/) for contributing
          several improvements