Net::SMS::2Way - BulkSMS API
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!', '27821234567'); $sms->send_sms('Hello World!', ['27821234567','27831234567','27841234567']); $sms->send_sms('Hello World!', @recipients);
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) but can be configured to work with all the BulkSMS sites. You can find a list of them at http://www.bulksms.com/selectwebsite.htm
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
1.) You need to register at one of the BulkSMS sites (http://www.bulksms.com/selectwebsite.htm) and have some credits available. 2.) You will need the LWP modules installed. This module was tested with version 5.75 3.) An internet connection.
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 (or one of the other sites). password: The password you registered. 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. country: Which base url to use, derived from which regional BulkSMS site you want to use. Can be one of ZA, UK, ES, DE, US, INT. default is ZA. ZA => South Africa (API Base URL: http://bulksms.2way.co.za:5567) UK => United Kingdom (API Base URL: http://www.bulksms.co.uk:5567) ES => Spain (API Base URL: http://bulksms.com.es:5567) DE => Germany (API Base URL: http://bulksms.de:5567) US => United States (API Base URL: http://usa.bulksms.com:5567) INT => International (API Base URL http://bulksms.vsms.net:5567) 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 country = UK 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
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(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() - 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_report(INTEGER) - Takes 1 argument which is batch_id i.e. the id returned by a successful submission to send_sms(). It's fully explained at http://bulksms.2way.co.za/docs/eapi/status_reports/get_report/. Return Values: 0 on failure with the error message in $sms->{error} Returns an array on success. Each element has a string which has the format of: msisdn|status_code|body|completed_time|created_time|credits|origin_address|source_id
TODO: Finish documentation ASAP!!!
Bugs: You can email the author directly at lee@kode.co.za Commercial support is available.
Many thanks to the guys at BulkSMS for their helpful feedback and comments.
Lee Engel, lee@kode.co.za
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.
To install Net::SMS::2Way, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::SMS::2Way
CPAN shell
perl -MCPAN -e shell install Net::SMS::2Way
For more information on module installation, please visit the detailed CPAN module installation guide.