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 andundef
returned. Ifua
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>
1 POD Error
The following errors were encountered while parsing the POD:
- Around line 433:
'=item' outside of any '=over'