/ 
SMS-Send-Wadja-1.01
River stage zero No dependents
/ SMS::Send::Wadja

NAME

SMS::Send::Wadja - Non-regional SMS::Send driver for the http://wadja.com free global SMS service, using their API.

VERSION

Version 1.0

SYNOPSIS

use SMS::Send;

my $sender = SMS::Send->new('Wadja',
    _key      => 'my-wadja-API-key'
);

my $sent = $sender->send_sms(
    to        => '+40-722-123456',    # recipient
    text      => "Hello, world!",     # the text of the message to send
    _from     => 'me@mydomain.com',   # optional "from" address
);

# Did it send to Wadja OK?
if ( $sent ) {
    print "Sent test message\n";
} else {
    print "Test message failed\n";
}

DESCRIPTION

SMS::Send::Wadja is an SMS::Send driver for the http://wadja.com free global SMS service, using their API. To apply for an API key, sign up for an account (it requires e-mail confirmation, but no phone number confirmation), then request an API key from http://www.wadja.com/api/get-started.aspx. In theory, Wadja could also be screen scraped so that you could send text messages via the web interface, without having to apply for an API key. However, applying is free, and the Wadja site is JavaScript-heavy and slow, which is why I didn't spend time implementing the screen scraping method.

I've seen Wadja deliver text messages successfully to the UK (Vodaphone), Germany (T-Mobile (D1) and Vodafone), Philippines (Global Telecom), Poland (Orange, Polkomtel), Romania (Orange), and Russia (BeeLine), but not to the US (AT&T Wireless), despite the official coverage claim at http://us.wadja.com/applications/compose/coverage.aspx. However, Wadja provides a delivery status function (which happens to be currently broken via their API (see http://us.wadja.com/applications/forum/replies.aspx?id=643) but works via the web UI).

Wadja offers two types of APIs:

  • Free SMS API - free, limited to 3 messages per day and 90 characters per message (the remaining characters will be used for ad delivery or Wadja branding)

  • SMS Plus API - requires topping up credit (in EUR), and doesn't deliver ads (thus you get the full 160 characters).

This module has only been tested with the Free SMS API but will probably work with the SMS Plus API as well.

METHODS

new

# Create a new sender using this driver
my $sender = SMS::Send->new('Wadja',
    _key    => 'your_wadja_API_key'            # required
    _ua     => $your_own_LWP_UserAgent_object  # useful if you want to pass proxy parameters
);

send_sms

This method is actually called by SMS::Send when you call send_sms on it.

my $sent = $sender->send_sms(
    text => 'Messages have a limit of 90 chars',
    to   => '+44-1234567890',
    _from => 'custom From string'  # works only in the SMS Plus API
);

Unicode messages appear to be handled correctly and are still limited to 90 characters.

Returns a hashref with the following keys:

price
batchID - used for tracking the delivery status

delivery_status

# Get the delivery status of the last message we sent
my $status = $sender->delivery_status;

# Get the delivery status for an arbitrary message we sent in the past,
# based on an anonymous hashref with a 'batchID' key
my $sent = $sender->send_sms(...);
my $status = $sender->delivery_status($sent);

# Or just pass a {batchID => nnn}
my $batchID = 2180419;
my $status = $sender->delivery_status({batchID => $batchID});

if ($status->{error}) {
    print "Can't check delivery: ", $status->{error}, "\n";
} else {
    print "Delivery status of " . $batchID . ": ", $status->{status}, ' at ', $status->{completed};
}

If called with no parameters then the most recent message sent out is checked. You can also provide an anoynmous hash with a batchID key set to the value of the batchID returned by a previous "send_sms" call.

Returns a hashref, of which the 'status' key indicates:

DELIVRD Delivered to destination
ACCEPTD Accepted by network operator
EXPIRED Validity period has expired
UNDELIV Message is undeliverable
UNKNOWN Message is in unknown state
REJECTD Message is in rejected state

BUGS AND LIMITATIONS

Wadja's API lets you send a text message to multiple recipients at once, by delimiting the phone numbers with commas. However, SMS::Send strips commas from the "to" parameter, which will obviously break things. I filed a bug against SMS::Send at http://rt.cpan.org/Ticket/Display.html?id=45868.

The official coverage claim is at http://us.wadja.com/applications/compose/coverage.aspx but beware that I could not send text messages successfully to AT&T Wireless in the US despite what the coverage claims.

Please report any bugs or feature requests for this module to bug-sms-send-wadja at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=SMS-Send-Wadja. For patches, please send whole files, not diffs.

AUTHOR

Dan Dascalescu, http://dandascalescu.com

ACKNOWLEDGEMENTS

Thanks to Adam Kennedy <adamk@cpan.org>, http://ali.as/ for writing SMS::Send. The Wadja API is described at http://www.wadja.com/api/docs/SMS_HTTP_API.pdf (as of 2010-01-25, the base URLs are wrong. s/sms/www/g.

Many thanks to my friends worldwide for assisting with QA.

LICENSE AND COPYRIGHT

Copyright (C) 2009-2010 Dan Dascalescu, http://dandascalescu.com. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.