NAME

SMS::AQL - Perl extension to send SMS text messages via AQ'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'
});
# default 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' });
            
          

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) like so:

            

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

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";
}
            
          

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-2007 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