SMS::Send::UK::Kapow - SMS::Send driver for the Kapow.co.uk website
use SMS::Send; my $sender = SMS::Send->new('UK::Kapow', _login => 'my-kapow-username', # normally required, see below (synonymous with _user) _password => 'my-kapow-password', # normally required, see below _send_via => 'http', # optional, can be http, https or email, default is http _http_method => 'get', # optional, the http method to use for http & https. # get or post, default post. _email_via => 'sendmail', # optional, for use when 'email' is used. can be # 'sendmail' or 'smtp' _url => 'http://foo.com/done' # optional url to call after sending, for http and https _from => 'me@mydomain.com', # optional, for use when 'email' is used in send_via _from_id => 'my-kapow-id', # optional message originator, if enabled for your account _route => '840101', # optional shortcode for premium sms reverse billing _wait => 0, # optional, supply a defined but false value to stop the # module from trying to confirm delivery. default true. ); my $sent = $sender->send_sms( to => '447712345678', # the recipient phone number text => "Hello, world!", # the text of the message to send _url => 'http://foo.com/done123', # optional url per message to call after sending # (for http and https) _from => 'me@mydomain.com', # optional from address per message (for email) _from_id => 'my-kapow-id', # optional message originator per message _route => '840101', # optional shortcode per message for reverse billing _wait => 0, # optional per message control of delivery checks. ); # Did it send to Kapow ok? if ( $sent ) { print "Sent test message\n"; } else { print "Test message failed\n"; } # What's the delivery status of the last message we sent? (available for http & https methods) my $status = $sender->delivery_status; # What's the delivery status for an arbitrary message we sent in the past? my $status = $sender->delivery_status($sent);
SMS::Send::UK::Kapow is a SMS::Send driver that delivers messages via the http://www.kapow.co.uk website.
Messages for any country can be sent through this interface, although Kapow is generally aimed at users in the UK.
This driver is based on the Kapow implementation document available at http://www.kapow.co.uk/docs/Kapow%20SMS%20Gateway%20Interfaces.pdf
You need to create an account at http://www.kapow.co.uk to be able to use this driver. You will also need to purchase some SMS credits for your account. Other optional services such getting a custom 'from-id' or setting trusted sender email addresses can be configured in your Kapow account and used through this module.
# Create a new sender using this driver my $sender = SMS::Send->new('UK::Kapow', _login => 'username', # normally required but see below _password => 'password', # normally required but see below );
In most cases you should provide your Kapow username and password.
If, however, you have set your Kapow account to allow any SMS requests received via email from a certain trusted email address then you do not need to set your username and password. In that case you may need to provide a '_from' parameter here or in the send_sms method unless your user account's email address on your system is the same as the trusted one registered with your Kapow account.
The _login param should be your kapow.co.uk username. The _user parameter can be used instead.
_login
_user
The _password param should be your kapow.co.uk password.
_password
The _send_via param controls how your SMS messages are sent to Kapow. The default method is http, which issues an http request from your server to Kapow's. Other options are 'https' and 'email'.
_send_via
The preferred methods are 'http' or 'https' because they allow the system to track the delivery statuses of individual messages. If your server cannot issue http/s requests then you can set this to 'email' and it will instead send an email message to Kapow to issue the SMS message. Note that using email means you lose the delivery tracking features of the http/s methods.
The _http_method param is relevant when using http or https to send your messages and specifies whether to use 'get' or 'post' methods when issuing the request to Kapow. This defaults to 'post' but can be changed to 'get' if desired.
_http_method
The _email_via param is relevant when using email to send the messages. Valid values for this param are 'sendmail' and 'smtp'. The default is 'sendmail' except on Windows, where the default is 'smtp'.
_email_via
The _url param is relevant when using http or https to send your messages. It provides an arbitrary callback URL which the Kapow server should call once the message has been successfully delivered. You can override this per-message in order to use unique URLs which relate to specific messages.
_url
The _from param is relevant when using email to send your messages and it should contain the email address to us as the 'from' address on the emails sent to Kapow. The default (if using email) is to use your user account's default email address.
_from
The _from_id param is relevant for users who use Kapow's 'from-id' feature to control the sender information that the recipient sees. If you have purchased this feature from Kapow for your account then you can control it using this parameter.
_from_id
The _route param is for users who have purchased Kapow's Premium SMS service to reverse-bill recipients for sending an SMS message. If you have purchased this feature from Kapow for your account then you can control it using this parameter.
_route
The _wait param is relevant when using http or https to send your messages. The SMS::Send specification dictates that if a message can have its delivery checked & confirmed then the driver module should do that automatically at the time the message is sent. This means that if you use http/s to send your messages then the system will wait for up to 10 seconds trying to validate that the message has gone. If you want to override this behaviour then supply a defined-but-false value for this param, such as 0 or the empty string.
_wait
Note that if you do suppress the automatic checking as described above then you can still check the state of delivery of each message using the delivery_status() method.
Returns a new SMS::Send::UK::Kapow object, or dies on error.
SMS::Send::UK::Kapow
# Send an SMS message my $sent = $sender->send_sms( to => '447712345678', # phone number to which to send the message text => "Hello, world!", # content of the message );
The required _to param should contain the phone number for the recipient. See the SMS::Send documentation for acceptable formats.
_to
The required _text param should contain the text content that you wish to send. Normally this is limited to 160 characters though that restriction is NOT enforced by this module in order to take advantage of multiple-part messages ability available on some phones.
_text
Any newlines or carriage returns present are converted to spaces.
The _url param is optional and can be used to provide a callback URL specific to this message. See above for a complete description.
The _from param is optional and can be used to provide an email from address specific to this message. See above for a complete description.
The _from_id param is optional and can be used to provide a mesage originator specific to this message. See above for a complete description.
The _route param is optional and can be used to provide a reverse billing shortcode specific to this message. See above for a complete description.
The _wait param is optional and can be used to suppress the automatic delivery confirmation stage on a per-message basis. See above for a complete description.
# What's the delivery status of the last message we sent? (available for http & https methods) my $status = $sender->delivery_status; # What's the delivery status for an arbitrary message we sent in the past? (pass it the return value of the send_sms method) my $status = $sender->delivery_status($sent);
For messages sent via http/s you can check the delivery status of the message by calling this method. If called with no parameters then the most recent message sent out is checked. You can also provide the return value of the send_sms method as a parameter to check the delivery status for other messages.
The module will use the same http or https setting that the sender object used to send the message (i.e. the _send_via param) as well as the same get/post setting.
Messages sent by email cannot be checked for their delivery status.
The send_status method is an alias for delivery_status, provided for backward-compatibility.
Jeremy Jones, <jjones at cpan.org>
<jjones at cpan.org>
Please report any bugs or feature requests to bug-sms-send-uk-kapow at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=SMS-Send-Kapow.
bug-sms-send-uk-kapow at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc SMS::Send::UK::Kapow
Adam Kennedy's SMS::Send module and Andrew Moore's SMS::Send::US::Ipipi module were useful for writing this one.
Copyright 2009 Jeremy Jones, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install SMS::Send::UK::Kapow, copy and paste the appropriate command in to your terminal.
cpanm
cpanm SMS::Send::UK::Kapow
CPAN shell
perl -MCPAN -e shell install SMS::Send::UK::Kapow
For more information on module installation, please visit the detailed CPAN module installation guide.