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'
  });

  # 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' });

  

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

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