Net::SMS::BulkSMS - send SMS messages via provider bulksms.co.uk
use Net::SMS::BulkSMS; my ($sms,$msg,$code,$result_hp,$msg_id,$credits); $sms = Net::SMS::BulkSMS->new (username=>"aaaaaaaaaaaa", password=>"bbbbbbbbbbbb", sender => "SomeCoUk"); or $sms = Net::SMS::BulkSMS->new (test => 1, test_form_url => "mycompany.co.uk/cgi-bin/form.pl/"); ($credits,$code) = $sms->get_credits; ($credits,$code) = $sms->quote_sms (message=>"Testing", msisdn=>"44123123456"); ($credits,$code) = $sms->quote_sms (message=>"Testing", msisdn=>"44123123456", msg_class=>"0"); ($msg_id,$code) = $sms->send_sms (message=>"Testing 1", msisdn=>"44123123456"); ($msg_id,$code) = $sms->send_sms (message=>"Testing 2", msisdn=>"44123123456,44567567890"); ($msg,$code,$result_hp) = $sms->get_report (msg_id=>$msg_id); ($msg,$code,$result_hp) = $sms->get_report (msg_id=>$msg_id, msisdn=>"44123123456");
This module provides an SMS transport mechanism for the gateway bulksms.co.uk. You will need to create an account at www.bulksms.co.uk and obtain a username and password, then you can use this module to send and query the status of SMS messages. The transport mechanism is via the HTTP API published at http://www.bulksms.co.uk/docs/eapi/current/.
Net::SMS::BulkSMS provides a calling interface and transport to send SMS text messages via the gateway bulksms.co.uk.
Create a new BulkSMS object:
This class method constructs an BulkSMS object. You must either supply a valid username and password for an account at bulksms.co.uk, or set test => 1 and provide test_form_url pointing to a script that will print posted form arguments so you can debug your SMS interface without sending real messages.
The remaining parameters are optional and override built-in defaults.
Valid details for an account at bulksms.co.uk, encoded in base64 MIME::Base64.
True/False(default). When true turns on test mode, no messages will be sent, and HTTP requests will be sent to test_form_url instead of bulksms.co.uk's eapi.
Up to 11 alphanumeric characters, either the mobile number to reply to or a company name.
Text to append to each sent message, e.g. "\nAcmeCoUk".
True(default)/False. Whether to append a date time stamp after signature.
Number, default 200. Maximum number of phone numbers allowed when sending the same message to multiple recipients. Set to 0 for unlimited.
Number, default 3. Number of times the transport retries posting HTTP requests before failing.
The following methods work with a created BulkSMS object.
Fetches the available credit balance on the bulksms account.
Returns
success: (credits,1) credits is a string representation of credit balance to two floating points
failure: ("errorcode: errormessage",0)
Parameters
Takes exactly the same parameters as the send_sms method, and quotes how many credits it would take to fulfil the request via send_sms.
Returns
success: (credits,1) credit is a string representation of number of credits required to send a
message with the specified parameters
failure: ("errorcode: errormessage",0)
Send an SMS message to one or more recipients.
Required parameters message: max 160 chars, 280 for 8bit msisdn: comma separated list of recipient phone numbers
Optional parameters sender: sender id (if alphanumeric, max 11 characters). This facility has to be specifically enabled for your account on request. Alphanumeric sender id is a route-specific feature. msg_class: currently 0 (flash SMS) or 2 (normal SMS), default 2 dca: Data Coding Alphabet: 7bit,8bit or 16bit, default 7bit (normal text message). For 8bit (ringtones,logos) or 16bit (Unicode), a message containing only hexadecimal octets, to a maximum of 280 characters (140 octet pairs), must be submitted. Currently, concatenation is not supported for Unicode messages. 16-bit is a route-specific feature. want_report: 0 or 1, default 1 cost_route: 1 or 2, default 1 (future functionality - always use 1 for now, if used) msg_id: a unique id generated by yourself, to reduce risk of duplicate submissions - future functionality, currently unused.
Returns success: ($msg_id, 1) failure: ("errorcode: errormessage", 0)
error codes
0: In progress (a normal message submission, with no error encountered so far).
22: Internal fatal error
23: Authentication failure
24: Data validation failed
25: You do not have sufficient credits
26: Upstream credits not available
27: You have exceeded your daily quota
28: Upstream quota exceeded
40: Temporarily unavailable
Get a status report on a sent message batch by msg_id.
Required parameters msg_id: message id returned from send_sms
Optional parameter msisdn: comma separated list of phone no.s by which to restrict report
Returns failure: ("errorcode: errormessage",1,undef) success: ($msg,0,$result_hash_ptr) $msg is eapi message, $result_hash_ptr is eapi message broken down to a hash of entries by phone no. containing { code, desc } from this table
0: In progress (a normal message submission, with no error encountered so far).
10: Delivered upstream
11: Delivered to mobile
22: Internal fatal error
23: Authentication failure
24: Data validation failed
25: You do not have sufficient credits
26: Upstream credits not available
27: You have exceeded your daily quota
28: Upstream quota exceeded
29: Message sending cancelled
30: Test complete (you should never see this)
40: Temporarily unavailable
50: Delivery failed - generic failure
51: Delivery to phone failed
52: Delivery to network failed
60: Transient upstream failure (transient)
61: Upstream status update (transient)
62: Upstream cancel failed (transient)
70: Unknown upstream status
Net::SMS::BulkSMS was developed by Peter Edwards <peter@dragonstaff.co.uk>.
Copyright 2007 Peter Edwards <peter@dragonstaff.co.uk>.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
