NAME

Net::SMS::SMSPilot - Send SMS to mobile phones, using smspilot.ru

SYNOPSIS

    use Net::SMS::SMSPilot;

    my $sms = Net::SMS::SMSPilot->new(
        apikey      => 'GJ67....KI5R',
        charset     => 'cp1251',
        sender      => 'internet',
        on_error    => sub { die shift }
    );

    # send one sms
    $sms->send('79876543210', 'SMS text messages');

    # change the sender
    $sms->set_sender('example.com');

    # mass sending of sms
    $sms->send( [
                 79876543210,
                 70123456789,
                ], 'SMS text messages');

DESCRIPTION

The Net::SMS::SMSPilot module allows you to use SMSPilot geteway (http://smspilot.ru) via simple interface.

APIKEY

For using service, you need an apikey. You can purchase a key on the page http://smspilot.ru/apikey.php.

USAGE

Interaction with SMSPilot.ru API executes by methods of the Net::SMS::SMSPilot object.

The object provides methods for:

• Retrieving information about the API key

• Retrieving information about the status of sent SMS

• Sending a single SMS and mass

• Change of Sender ID

• Check balance

Constructor

Net::SMS::SMSPilot->new(%options)

This method constructs a new Net::SMS::SMSPilot object and returns it. Key/value pair arguments may be provided to set up the initial state.

    apikey            The authorization key to access the API. (required)
    sender            Sender ID. Default value: 'SMSPilot.Ru'. (optional)
    charset           The encoding of characters. Default value: 'utf8'. (optional)
    secure            SSL connection: 1 - on; 0 - off. Default value: 1. (optional)
    ua                Your own LWP::UserAgent object. (optional)
    on_error          The callback to invoke error processing. (optional)

If apikey absent, an object will not be created and undef returned. If ua is not defined, it will be created internally. Example:

    my $sms = Net::SMS::SMSPilot->new(
        apikey      => 'GJ67....KI5R'
    );

Errors processing

All methods returns undef when an error is detected. Afterwards, method error returns a message describing last ocurred error.

error

Returns last error.

    my $stat = $sms->send('internet', 'My message');
    if (! defined($stat)) {
        warn($sms->error);
    }

Callback function

Additionally, you can define a callback function in the constructor's option on_error. This function will be fired when an error will be occurred.

    my $sms = Net::SMS::SMSPilot->new(
        apikey      => 'GJ67....KI5R',
        on_error    => sub {
            my ($err) = @_;
            log(time, $err) and die $err;
        }
    );

APIKEY Info Fileds

Data, returned by apikey_info method, consist of following fields:

    apikey                    Key value
    email                     E-mail key owner
    date                      Date/time of creation of a key
    history                   History key in the form of arrayref
    status                    Key status: 0 = new, 1 = waiting for activation,
                              2 = active, 3 = ran out of SMS, 4 = spam.

    sms_total                 Paid sms
    sms_sent                  Sent sms

    amount                    Amount of last payment
    currency                  Currency of the last payment
    date_paid                 Date/time of payment
    balance                   Current balance (in credit)

    date_access               Date/time of last request
    last_ip                   IP address of the last query
    allow_ip                  List of allowed IP addresses

Status of sent SMS Fileds

Data, returned by send() and check() methods, data represents a reference to an array of hashes. Hash consist of the following fields:

    id                        SMS ID (used to check the status of SMS)
    phone                     Phone number to sent SMS
    zone                      Zone for price (Example: 1 = Russia)
    status                    SMS status:
                               -2 = server did not receive this message (ID
                               not found);
                               -1 = message is not delivered (the subscriber's
                               phone is turned off, the operator is not
                               supported);
                               0 = new message;
                               1 = in the queue at the mobile operator;
                               2 = message is successfully delivered.

SMS sending

send($to_one, $message)

send(\@to_many,$message)

Returns a reference to an array of hashes, with status of sent SMS ( See ""Status of sent SMS Fileds"" ). For sending SMS to one recipient using a scalar variable ($to_one). For the mass sending of SMS using an arrayref (\@to_many). Example:

    $sms->send(79876543210, 'Hello world!'); # One recipient
    $sms->send([
                79876543210,
                70123456789,
               ], 'Hello world!'); # Mass sending

After executing this method will be available the additional fields of the object:

    $sms->{cost};    # the cost of sending (in credits)
    $sms->{balance}; # balance (in credit)

Change SMS sender

set_sender($sender)

The $sender can contain text in Latin script, numerals, symbols "-" and "." length of 3-11 characters long or the number length of 10-16 numbers in international format, "+" sign is not considered. If you can not change the sender, it returns an undef. Example:

    $sms->set_sender('example.com');
    # or
    $sms->set_sender(89876543210);

Check SMS

check($id)

check(\@ids)

Returns a reference to an array of hashes, with status of sent SMS ( See ""Status of sent SMS Fileds"" ). For check SMS to one recipient using a scalar variable ($id). For the mass check of SMS using an arrayref (\@ids). Example:

    $status1=$sms->check(12345); # Check of one SMS
    $status2=$sms->send([
                12345,
                54321,
               ]); # Check of mass SMS

Information about the APIKEY

apikey_info

Returns a hash or a hashref (depending on how you invoke), with info about the APIKEY. See ""APIKEY Info Fileds"". Example:

    %hash=$sms->apikey_info;
    print $hash{email}; # print e-mail the owner
    # or
    $hashref=$sms->apikey_info;
    print $hashref->{email}; # print e-mail the owner

Check the current balance

balance

balance($currency)

Returns the current balance in the currency, where $currency could be the following:

   'sms' - in credit (default)
   'wmr' - in RUB webmoney [http://webmoney.ru]
   'rur' - in RUB Yandex.Money [http://money.yandex.ru]

SEE ALSO

SMSPilot API Reference in Russian, looking at http://www.smspilot.ru/apikey.php

This documentation in Russian, looking at http://www.smspilot.ru/software.php

COPYRIGHT

Copyright (c) 2011 Daniil Putilin. All rights reserved.

This module is free software. You can redistribute it and/or modify it under the terms of the Artistic License 2.0.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

AUTHOR

Daniil Putilin <dadis@cpan.org>

cpanm Net::SMS::SMSPilot

perl -MCPAN -e shell
install Net::SMS::SMSPilot