SMS::AQL(3pm)

💖 SMS::AQL 💖

okay so first things first: this is the SMS::AQL page from the User Contributed Perl Documentation (that's the 3pm part, iykyk ✨). It's literally your backstage pass to texting people from Perl. no cap. 🦋

---

✨ NAME ✨

SMS::AQL — a Perl extension for sending SMS text messages via AQL's SMS service. 💌

---

🎀 SYNOPSIS 🎀

bestie here's the whole vibe in one block, look:

# 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 hands you a nice object-oriented interface for sending SMS text messages through the HTTP gateway that AQ Ltd runs over in the UK (www.aql.com, in case you were wondering 🫶).

It also does concatenated text messages — yes, the ones that go over the 160-character limit of a normal text. It pulls that off by sending multiple messages with a header that says "hey, these are all part of ONE message". Heads up though: that's handset-dependent, but it's supported by all reasonably new mobiles, so you're chilling. 💅

---

👑 METHODS 👑

💫 new (constructor)

You must create an instance of SMS::AQL, and you pass it the username and password of your AQL account:

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

You can also pass extra parameters (like 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.

• Called in scalar context, it returns 1 if the message was sent, 0 if it wasn't.
• Called in list context, it returns a two-element list: the first element is 1 for success or 0 for fail, and the second is a message telling you why the send operation failed.

bestie, you must set a sender — either at new or for each send_sms call. no sender, no send. 😭

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])

Makes an actual telephone call to the given phone number and uses speech synthesis to read out the message you supplied. iconic fr fr.

$to and $message are the destination telephone number and the message to read out. The third optional parameter is a hashref of options that change how this method behaves — and right now, 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...")
• Called in scalar context, it returns 1 if the message was sent, 0 if it wasn't.
• Called in list context, it returns a two-element list: the first element is 1 for success or 0 for fail, and the second is a message explaining 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

---

and that's the whole page bestie 💅 this version was living its life as perl v5.40.1, dated 2025-04-12, under the name SMS::AQL(3pm). go send some texts, you've got this 🎀💖✨