/ 
SMS-Send-UK-Kapow-0.06
River stage zero No dependents
/ SMS::Send::UK::Kapow

NAME

SMS::Send::UK::Kapow - SMS::Send driver for the Kapow.co.uk website

SYNOPSIS

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);

DESCRIPTION

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

Preparing to Use This Driver

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.

METHODS

new

# 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.

_login

The _login param should be your kapow.co.uk username. The _user parameter can be used instead.

_password

The _password param should be your kapow.co.uk password.

_send_via

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'.

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.

_http_method

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.

_email_via

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'.

_url

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.

_from

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_id

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.

_route

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.

_wait

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.

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.

send_sms

# 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
);
_to

The required _to param should contain the phone number for the recipient. See the SMS::Send documentation for acceptable formats.

_text

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.

Any newlines or carriage returns present are converted to spaces.

_url

The _url param is optional and can be used to provide a callback URL specific to this message. See above for a complete description.

_from

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.

_from_id

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.

_route

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.

_wait

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.

delivery_status

# 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.

send_status

The send_status method is an alias for delivery_status, provided for backward-compatibility.

AUTHOR

Jeremy Jones, <jjones at cpan.org>

BUGS

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.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc SMS::Send::UK::Kapow

ACKNOWLEDGEMENTS

Adam Kennedy's SMS::Send module and Andrew Moore's SMS::Send::US::Ipipi module were useful for writing this one.

COPYRIGHT & LICENSE

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.