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

AUTHOR

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

All bug reports, feature requests, patches etc welcome.

COPYRIGHT AND LICENSE

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

2022-06-17

perl v5.34.0