/ 
SMS-AQL-0.03
River stage one • 1 direct dependent • 1 total dependent
/ SMS::AQL

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.

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

last_error()

Returns the last result code received from the AQL gateway.

Possible codes are:

AQSMS-NOAUTHDETAILS

The username and password were not supplied

AQSMS-AUTHERROR

The username and password supplied were incorrect

AQSMS-NOCREDIT

The account specified did not have sufficient credit

AQSMS-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 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.