NAME

SMS::CPAGateway - Send an SMS through a gateway using the CPA Gateway protocol

SYNOPSIS

        use SMS::CPAGateway;
        use Data::Dumper qw(Dumper);

        my $sms = SMS::CPAGateway->new(
                # Parameters shown with their defaults
                price => 0,                     # Can also be overriden on a per-message basis
                fromNo => undef,        # Value required at construction time
                key => undef,           # Value required at construction time
                servers => undef,       # Value required at construction time
                );
        if (! $sms->send($PHONENO,$MESSAGE))
        {
                # Some error occurred. All servers failed, it gave up sending.
                your_email_sending_sub(youremail,'Sending message to '.$PHONENO.' failed:'."\n\n".Dumper($sms->errors));
        }
        elsif ($sms->hadError)
        {
                # Some error occurred, but SMS::CPAGateway recovered from it. You can
                # log the errors if you wish, but there is no need to as the SMS
                # was successfully sent.
                #
                # This can happen ie. when the phone number supplied is strange (ie.
                # missing country prefix) or when either of the servers failed. If all
                # servers fail, send() will return false and trigger the above check
                # instead.
                log_errors(Dumper($sms->errors));
        } 

DESCRIPTION

This module offers a convenient way of sending an SMS from a Perl program using any server(s) that understand the CPA Gateway protocol version 2, which is the current release of the protocol.

This module and the author are not affiliated with Teletopia interactive in any way.

METHODS

new

Constructs a new instance of the class. You can supply any of the attributes listed below in the Attributes section to this method during construction time to initialize them.

The following attributes MUST be supplied at construction time: fromNo, key

send($number,$message,$price = $object->price);

Sends a message. It takes either two or three parameters. $number is the recipient phone number and $message is the text message to send. $price is the price of the message, this parameter is optional and defaults to the value of the price attribute if it is undef.

The recipient phone number must include the direction code.

Usage: $sms->send('+0000000000','Message',0);

This returns true on success and false on failure. See also hadError and errors.

hadError

Returns true if an error has occured when sending since this object was instantiated. This does NOT indicate that sending a message, or even the last message, failed. The return value of send() indicates that. An error could for instance be that a single server failed, and that we thus fell back to either of the fallback servers.

errors

Returns an array of error messages.

id

This is used to set and get the id used for a message. Note than an ID can only be used to send a single message, and if the same ID is attempted to be used for multiple messages, the module will automatically generate a random one instead.

If supplied with a string, sets the id for the next SMS to be sent to the string supplied.

If called without any parameters, returns either of the following:

        - The id that is going to be used to send the first SMS (if you
                have not yet sent any SMS through the instance).
        - The id that was used to send the last SMS sent (as long as you have
                not already set an ID that will be used for the next one
                by calling this method with a string value).

Attributes

fromNo

The from number. Must be a number that you are authorized by the server to use.

price

The price of an SMS. This defaults to 0. This can also be supplied as a parameter to send()

key

Your authorization key.

id

The ID that is sent along with the message. If this is not supplied then it will be automatically generated. See the id method.

servers

An arrayref of servers to attempt. The list of servers are provided by the service provider.

Example: [ 'http://gateway1.example.com:12345', 'http://gateway2.example.com:12345', 'http://gateway3.example.com:12345' ]

BUGS AND LIMITATIONS

The module has only been tested with UTF-8-compatible messages.

It doesn't provide any means of recieving SMS messages, as that is simply done by HTTP POST requests to a web server, and there is very little a module can add to that as there are a load of different ways to read parameters, and there is little that has to be done with that data without entering site-specific logic.

Please report any bugs or feature requests to http://github.com/portu/SMS-CPAGateway/issues.

SEE ALSO

http://cpa.teletopiainteractive.no/

AUTHOR

Eskild Hustvedt, <zerodogg@cpan.org>

LICENSE AND COPYRIGHT

Copyright (C) 2010 by Eskild Hustvedt

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.0 or, at your option, any later version of Perl 5 you may have available.