NAME

Net::SMS::2Way - BulkSMS API

SYNOPSIS

use Net::SMS::2Way;

my $sms = Net::SMS::2Way->new({username => 'JBloggs', password => 's3kR3t'});

my $sms = Net::SMS::2Way->new('config' => '/etc/SMS_Options.cfg');

$sms->send_sms('Hello World!', '0821234567');

$sms->send_sms('Hello World!', ['0821234567','0831234567','0841234567']);

$sms->send_sms('Hello World!', @recipients);

DESCRIPTION

This module allows you to send SMS text messages using the HTTP API that is available from BulkSMS 
in South Africa (http://bulksms.2way.co.za)

The BulkSMS API

This module implements only the HTTP API. You can read the HTTP API documentation at http://bulksms.2way.co.za/docs/eapi/

Here is a list of the methods that have been implemented:

send_sms
get_inbox
get_report
get_credits

Methods yet to be implemented:

send_batch
quote_sms
public_add_member 
public_remove_member  

I will incorporate the FTP API as soon as the HTTP implementation is considered to be stable.

REQUIREMENTS

• You need to register at http://bulksms.2way.co.za and have some credits available.

• You will need the LWP modules installed. This module was tested with version 5.75

• An internet connection.

METHODS

Constructor

new() - The new() method is the constructor method.

my $object = SMS->new($options)

$options is a reference to a hash where the following keys can be used:

config_file: The path to config file
verbose: Write debug information to logfile
logfile: The path to the logfile. Default is $0.log (To turn off logging (override verbose) set this option to -1)
username: The username you registered with at http://bulksms.2way.co.za
password: The password you registered with at http://bulksms.2way.co.za
http_proxy: Which web-proxy to use e.g. http://10.0.0.1:8080
sa_numbers_only: Set this to 1 if you only want to send to South African mobile numbers

See the bulkSMS API for the meaning of the options below (http://bulksms.2way.co.za/docs/eapi/submission/send_sms/):

sender 
msg_class 
dca 
want_report 
routing_group 
source_id 
repliable 
strip_dup_recipients 
stop_dup_id 
send_time 
send_time_unixtime 
scheduling_description 
test_always_succeed 
test_always_fail 
allow_concat_text_sms 
oncat_text_sms_max_parts

You can also put any of these (except for config_file) into a file with the format of:

option = value

The can make comments by using the # character.

Once you've created the file you can create your object like this:

my $object = SMS->new({config => '/etc/sms.cfg'});

Example of the config file:

 # My config
 verbose = 1
 logfile = /usr/local/sms/sms.log
 sender = 27841234567
 username = johnny
 password = S3kR3t
 want_report = 1

• By default a log file will be created and failures or serious errors will be logged, no matter what the verbose option is set to. 
  If you do not want any logs at all, you must set logfile to -1

PROXY SUPPORT

This module does support proxies. You can enable it 2 ways:

1.) Populate the http_proxy enviroment variable e.g. 

 [user@server01 ~] $ export http_proxy=http://10.0.0.1:8080

2.) Use the http_proxt attribute when creating the object e.g.

 $sms = SMS->new({http_proxy => 'http://10.0.0.1:8080'});

send_sms()

send_sms(STRING, LIST) - The send_sms() method will connect and send a text message to the list of mobile numbers in the LIST.

The second parametre can also be a single scalar i.e. a single number as a string.

Return Values: 

 Returns a pipe-seperated string on success (or apparent success). The format of the string is:
 
 status_code|status_description|batch_id
 
 For a full explanation of what this string means, etc, please visit http://bulksms.2way.co.za/docs/eapi/submission/send_sms/

 Returns 0 on failure with the reason for the failure in the error attribute. Eg.

 $retval = $sms->send_sms("This is a test", '0821234567');
 
 if (!$retval) {
 	print "There was an error!!!\n";
 	print "Error Message: " . $sms->{error} . "\n";
 }
 

get_credits()

get_credits() - Takes no arguments and will return the amounts of credits available.

Return Values: A positive decimal number can be expected. This number is the number of credits available with the provider.

On failure, a return value of -1 can be expected with the reason in $sms->{error}

get_reports()

TODO: Finish documentation ASAP!!!

get_inbox()

TODO: Finish documentation ASAP!!!

AUTHOR

Lee Engel, lee@kode.co.za, http://www.easitext.net

COPYRIGHT AND LICENSE

Copyright (C) 2007 by Lee S. Engel

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