SYNOPSIS

use Net::SMS::TextMagic;

my $sms = Net::SMS::TextMagic->new( USER => $username, API_ID => $api_id );
$sms->message_send(text=>'This is a test!', phone=>'35891911');

DESCRIPTION

TextMagic (http://www.textmagic.com) is a commercial service that allows its users to send SMS messages to anyone in the world.

Net::SMS::TextMagic provides OO methods that allow to send SMS messages through TextMagic service. The TextMagic HTTPS API is documented at http://api.textmagic.com/https-api. This module implements all HTTPS API commands and return values. However, all command parameters and return values are not necessary mentioned or thorougly described in this document. Please consult the original API document for details.

Note that whether this software nor the author are related to TextMagic in any way.

METHODS

new

Creates the TextMagic object.

Usage:

my $sms = Net::SMS::TextMagic->new( USER => $username, API_ID => $api_id );

The complete list of arguments is:

USER Your TextMagic username. Same as your username to TextMagic web service. Required.

API_ID Your TextMagic API ID. The API ID is not your password to TextMagic web service. You can get your API ID from the TextMagic web service. Required.

API_URL TextMagic API URL. Defaults to https://www.textmagic.com/app/api.

UserAgent Name of the user agent you want to display to TextMagic service. Defaults to "Net::SMS::TextMagic"

Timeout UserAgent timeout. Defaults to 10 seconds.

Returns Net::SMS::TextMagic object or false (in case USER or API_ID are missing).

message_send

Sends SMS message. Equals to HTTPS API command "send" but renamed in the module to avoid conflict with built-in send function.

Usage:

my %response = $sms->message_send(text=>'This is a test!', phone=>'35891911');
print "Sent message $response{'sent_text'} chopped in $response{'parts_count'} parts\n";

The complete list of arguments is:

text Message text in Perl internal charset. Required.

phone Phone number(s). The numbers are sent "as is". Currently the API supports up to 100 numbers separated by commas (,). Required.

unicode If set to true the message text is sent as UTF-8. Otherwise the text is sent in GSM 03.38 encoding. Defaults to true (UTF-8).

from, max_length, send_time See TextMagic HTTPS API documentation.

Returns a hash containing following keys:

sent_text The text (in Perl internal charset) that was actually sent.

parts_count The number of parts the message has.

message_id A hash containing pairs of numbers (keys) and message_ids (values) that were sent.

account

Get the current SMS credit balance.

Usage:

my %response = $sms->account();
print "Your balance is $response{'balance'}\n";

Returns a hash containing following key:

balance The amount of available SMS credits on your account.

message_status

This method allows you to retrieve the delivery status of any SMS you have already sent. The message ID is returned by message_send command.

Usage:

my $this_id = 123456;
my %response = $sms->message_status($this_id);
print 'Message text was '.$response{$this_id}{'text'}."\n";
print 'The cost was '.$response{$this_id}{'credits_cost'}." credits\n";

The only parameter is a string containing message ID or several IDs separated by commas and without spaces (e.g. "8624389,8624390,8624391"). Up to 100 IDs can be retrieved with a single command.

Returns a two-level hash containing status of message IDs. Each ID has following fields:

text SMS text sent.

status The current status of the message. The status codes are explained at http://api.textmagic.com/https-api/sms-delivery-notification-codes.

created_time The time TextMagic sent the message. Unix timestamp.

reply_number See API documentation for details.

credits_cost Cost of the message in SMS credits. Set when message is delivered.

completed_time The time your message achieves final status, returned by the mobile operator. Unix timestamp.

receive

This method retrieves the incoming SMS messages from the server. The server is limited to returning a maximum of 100 messages for each request. Please use last_retrieved_id parameter to page through your inbox.

The only optional parameter is last_retrieved_id. The server will only return messages with identifiers greater than last_retrieved_id. The default value is 0 which fetches up to the first 100 replies from your inbox.

Returns a hash containing following keys:

unread The number of messages with identifiers greater than last_retrieved_id remaining unreturned due to the limit on returned messages per request.

messages_count Number of messages in the current messages hash.

messages An array containing all messages. Each object in the array is a hash with following keys:

message_id The identifier of the incoming message.

from The sender's phone number.

timestamp The message's reception time expressed in Unix time format.

text The message text.

delete_reply

This command helps you to delete any incoming SMS messages from the server.

Usage:

my @response = $sms->delete_reply('123456,123457,123458');
print "Following messages were deleted: ".join(', ', @response)."\n";

The only required parameter is a string containing message IDs to be deleted. The IDs should be separated with commas without spaces. Up to 100 messages can be deleted with single command.

Returns an array containing message IDs that were deleted.

check_number

This command helps you to validate a phone number's format and to check a message's price to its destination.

Usage:

my %response = $sms->check_number('35891911,35891912');

foreach my $this_number (keys %response) {
  print "Number $this_number is in ".
    $response{$this_number}{'country'}.
    'and the SMS cost is '.
    $response{$this_number}{'price'}.
    "credits.\n";
  }

The only required parameter is a string containing phone numbers to be checked. The numbers should be separated with commas without spaces. The TextMagic HTTPS API documentation does not specify the maximum number of phone numbers that can be checked with a single command.

Returns a two-level hash containing status of numbers. Each number has following fields:

price The cost in SMS credits of sending a single message to the number.

country The number's country code. A full list of country codes can be found at https://www.textmagic.com/app/wt/messages/new/cmd/get_countries.

contact_api

Contacts TextMagic API. This in mainly for internal use, but can be used to contact TextMagic API directly.

Usage:

my $r_json = $sms->contact_api('some_api_command', %parameters);

Parameters: - a string containing TextMagic HTTPS API command - a hash containing command parameters

Returns a JSON object containing the result.

set_error

Sets Net::SMS::TextMagic error code. Mainly for internal use.

If there is already an unprocessed error message, this message is appended to the unprocessed error array. The array can be read and emptied with get_unprocessed_errors().

Usage:

$sms->set_error('Out of credit');

get_error

Gets and clears Net::SMS::TextMagic error code. This does not affect the array of unprocessed error messages (see get_unprocessed_errors()).

Usage:

my %response = $sms->message_send('phone' => '123456', 'text' => 'Howdy!');
if ($sms->if_error()) {
  my $errormsg = $sms->get_error();
  if ($errormsg) {
    print "Dough! $errormsg\n"; 
	  }
	}

No parameters. Returns a error string if error flag is up. If no error message is present returns undef.

if_error

Returns true if there is a pending error code (see get_error()). Returns false if no error flag is set.

Usage:

if ($sms->if_error()) {
  print STDERR "SMS error: ".$sms->get_error()."\n";
  }
  

get_unprocessed_errors

Returns and flushes the array of unprocessed errors. See set_error().

if_unprocessed_errors

Returns a number of items in the array of unprocessed errors. If there are no errors returns undef (false).

BUGS

Since the author uses this module mostly for sending SMSs not all features related to receiving a great number of messages has been tested. Do not hesitate to contact if you suspect bugs.

AUTHOR

Matti Lattu, <matti@lattu.biz>

ACKNOWLEDGEMENTS

The documentation has a great number of verbatim quotations of TextMagic HTTPS API documentation.

Greatly inspired by "official" TextMagic Perl API implementation (http://code.google.com/p/textmagic-sms-api-perl/) by Marco-Paul Breijer and Net::SMS::Clickatell by Robert Moreno.

LICENSE AND COPYRIGHT

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.1 or, at your option, any later version of Perl 5 you may have available.

Copyright (C) 2011 Matti Lattu