.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "SMS::AQL 3pm"
.TH SMS::AQL 3pm "2021-01-09" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
SMS::AQL \- Perl extension to send SMS text messages via AQL's SMS service
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&  # 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 => \*(Aqusername\*(Aq,
\&    password => \*(Aqpassword\*(Aq
\&  });
\&
\&  # other parameters can be passed like so:
\&  $sms = new SMS::AQL({
\&    username => \*(Aqusername\*(Aq,
\&    password => \*(Aqpassword\*(Aq,
\&    options => { sender => \*(Aq+4471234567\*(Aq }
\&  });
\&  
\&  # 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\en";
\&  }
\&  
\&  # params for this send operation only can be supplied:
\&  $sms\->send_sms($to, $msg, { sender => \*(Aqbob the builder\*(Aq });
\&  
\&  # make a phone call and read out a message:
\&  my ($ok, $why) = $sms\->voice_push($to, $msg);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\s-1SMS::AQL\s0 provides a nice object-oriented interface to send \s-1SMS\s0 text
messages using the \s-1HTTP\s0 gateway provided by \s-1AQ\s0 Ltd (www.aql.com) in 
the \s-1UK.\s0
.PP
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).
.SH "METHODS"
.IX Header "METHODS"
.IP "new (constructor)" 4
.IX Item "new (constructor)"
You must create an instance of \s-1SMS::AQL,\s0 passing it the username and
password of your \s-1AQL\s0 account:
.Sp
.Vb 1
\&  $sms = new SMS::AQL({ username => \*(Aqfred\*(Aq, password => \*(Aqbloggs\*(Aq });
.Ve
.Sp
You can pass extra parameters (such as the default sender number to use,
or a proxy server) like so:
.Sp
.Vb 8
\&  $sms = new SMS::AQL({
\&    username => \*(Aqfred\*(Aq, 
\&    password => \*(Aqbloggs\*(Aq,
\&    options  => {
\&        sender => \*(Aq+44123456789012\*(Aq,
\&        proxy  => \*(Aqhttp://user:pass@host:port/\*(Aq,
\&    },
\&  });
.Ve
.ie n .IP "send_sms($to, $message [, \e%params])" 4
.el .IP "send_sms($to, \f(CW$message\fR [, \e%params])" 4
.IX Item "send_sms($to, $message [, %params])"
Sends the message \f(CW$message\fR to the number \f(CW$to\fR, optionally
using the parameters supplied as a hashref.
.Sp
If called in scalar context, returns 1 if the message was
sent, 0 if it wasn't.
.Sp
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.
.Sp
You must set a sender, either at new or for each send_sms call.
.Sp
Examples:
.Sp
.Vb 3
\&  if ($sms\->send_sms(\*(Aq+44123456789012\*(Aq, $message)) {
\&      print "Sent message successfully";
\&  }
\&  
\&  my ($ok, $msg) = $sms\->send_sms($to, $msg);
\&  if (!$ok) {
\&      print "Failed to send the message, error: $msg\en";
\&  }
.Ve
.ie n .IP "voice_push($to, $message [, \e%params])" 4
.el .IP "voice_push($to, \f(CW$message\fR [, \e%params])" 4
.IX Item "voice_push($to, $message [, %params])"
Make a telephone call to the given phone number, using speech synthesis to
read out the message supplied.
.Sp
\&\f(CW$to\fR and \f(CW$message\fR 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:
.RS 4
.IP "skipintro" 4
.IX Item "skipintro"
Skips the introductory message that \s-1AQL\s0's system normally reads out. (If you
use this, it's recommended to add your own introduction to your message, for
example \*(L"This is an automated call from \s-1ACME\s0 Inc...\*(R")
.RE
.RS 4
.Sp
If called in scalar context, returns 1 if the message was sent, 0 if it wasn't.
.Sp
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.
.Sp
Note that, at the current time, this feature supports only \s-1UK\s0 telephone numbers.
.RE
.IP "\fBcredit()\fR" 4
.IX Item "credit()"
Returns the current account credit. Returns undef if any errors occurred
.IP "\fBlast_status()\fR" 4
.IX Item "last_status()"
Returns the status of the last command: 1 = \s-1OK, 0\s0 = \s-1ERROR.\s0
.IP "\fBlast_error()\fR" 4
.IX Item "last_error()"
Returns the error message of the last failed command.
.IP "\fBlast_response()\fR" 4
.IX Item "last_response()"
Returns the raw response from the \s-1AQL\s0 gateway.
.IP "\fBlast_response_text()\fR" 4
.IX Item "last_response_text()"
Returns the last result code received from the \s-1AQL\s0
gateway in a readable format.
.Sp
Possible codes are:
.RS 4
.IP "AQSMS-AUTHERROR" 4
.IX Item "AQSMS-AUTHERROR"
The username and password supplied were incorrect
.IP "AQSMS-NOCREDIT" 4
.IX Item "AQSMS-NOCREDIT"
Out of credits (The account specified did not have sufficient credit)
.IP "AQSMS-OK" 4
.IX Item "AQSMS-OK"
\&\s-1OK\s0 (The message was queued on our system successfully)
.IP "AQSMS-NOMSG" 4
.IX Item "AQSMS-NOMSG"
No message or no destination number were supplied
.RE
.RS 4
.RE
.SH "SEE ALSO"
.IX Header "SEE ALSO"
http://www.aql.com/
.SH "AUTHOR"
.IX Header "AUTHOR"
David Precious, <davidp@preshweb.co.uk>
.PP
All bug reports, feature requests, patches etc welcome.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2006\-2008 by David Precious
.PP
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.
.SH "THANKS"
.IX Header "THANKS"
.Vb 3
\& \- to Adam Beaumount and the AQL team for their assistance
\& \- to Ton Voon at Altinity (http://www.altinity.com/) for contributing
\&   several improvements
.Ve