Peter Farr
and 1 contributors

NAME

Net::SMS::Clickatell::SOAP - SOAP interface to the Clickatell SMS service

DESCRIPTION

Pure Perl module to access the Clickatell Bulk SMS gateway using the SOAP protocol.

 use SMS::Clickatell::SOAP;

 my $sms = new SMS::Clickatell::SOAP(
        connection => (
                proxy => $PROXY_URL,
                service => $SERVICE_URL,
                verbose => $VERBOSE,
                user    => $WS_USER,
                password => $WS_PASSWD,
                api_id => 123456
        )
 );

METHODS

$sms = new( api_id => $api_id, user => $user, password => $password );

Class constructor method instantiates a class object and initiates a connection to the Clickatell service through the auth call.

 my $hSMS = new SMS::Clickatell::SOAP(
        proxy   => $endpoint,
        service => "${endpoint}?wsdl",
        verbose => 0
 );

where:

proxy (optional)

SOAP connection parameter. See SOAP::Lite for further information. Defaults to http://api.clickatell.com/soap/webservice.php.

service (optional)

SOAP connection parameter. See SOAP::Lite for further information. Defaults to http://api.clickatell.com/soap/webservice.php?wsdl.

verbose

Verbosity level for debugging. Default is verbose=>0 (only error output).

$msg = $sms->errorCode( $code );

Convert a numeric error code to a text error message

where:

$code

numeric error code returned by the Clickatell API

$msg

associated text error message

$id = $sms->sessionId();

Return the current session id

$resp = $sms->auth( user=>$user, password=>$password, api_id=>$api_id);

Send credentials to Clickatell to authenticate the session.

user

Clickatell user id

password

Clickatell password

api_id

Regisered API ID as assigned by Clickatell

The response will be:

OK:
ERR: xxx

Error returned by the Clickatell API

$resp = $sms->ping();

Send a ping to the service to keep the session alive.

The response will be:

OK:
ERR: xxx

where xxx is a numeric error code

$resp = $sms->getbalance();

Query the number of credits available in the account.

Credit: nn.nnn

Amount of outstanding credit balance for the account.

ERR: xxx

where xxx is a numeric error code

$resp = $sms->routeCoverage( msisdn => $msisdn );

Chck the coverage of a network or number without sending a message.

where:

msisdn

The network or number to be checked for coverage.

The response will be:

OK: followed by coverage information

Eg. OK: This prefix is currently supported. Messages sent to this prefix will be routed. Charge: 0.33

ERR: xxx

where xxx is a numeric error code

$resp = $hSMS->querymsg( apiMsgId => $apiMsgId );
$resp = $hSMS->querymsg( cliMsgId => $cliMsgId );
apiMsgId

API message id (apiMsgId) returned by the gateway after a message was sent.

cliMsgId

client message ID (cliMsgId) you used on submission of the message.

the response will be:

ID: followed by message status

eg. ID: 18e8221e5aa50cfad72376e08f40388a Status: 001;

Status codes are defined by the Clickatell API.

ERR:

where xxx is a numeric error code

$resp = $sms->querymsg( apiMsgId => $apiMsgId );

Query the status of a message.

apiMsgId

API message id (apiMsgId) returned by the gateway after a message was sent.

the respones will be:

apiMsgId: followed by message status

eg. apiMsgId: 18e8221e5aa50cfad72376e08f40388a charge: 0.33 status: 004;

Status codes are defined by the Clickatell API.

ERR:

where xxx is a numeric error code

$resp = $hSMS->delmsg( apiMsgId => $apiMsgId );
$resp = $hSMS->delmsg( cliMsgId => $cliMsgId );

Delete a previously sent message.

apiMsgId

API message id (apiMsgId) returned by the gateway after a message was sent.

cliMsgId

client message ID (cliMsgId) you used on submission of the message.

the response will be:

ID: followed by message status

eg. ID: 18e8221e5aa50cfad72376e08f40388a Status: 001;

Status codes are defined by the Clickatell API.

ERR:

where xxx is a numeric error code

$resp = $hSMS->sendmsg(to => '19991234567', text => 'Hello there...');
$resp = $hSMS->sendmsg(to => @phoneNumbers, text => 'Hello there...');

Chck the coverage of a network or number without sending a message. If item_user is supplied, then preexisting session authentication (if any) will be ignored and the item_user, item_pasword and api_id values will be used to authenticate this call. This allows you to send a message even if the existing session has dropped for any reason.

to (required)

A phone number or list of phone numbers to recieve the messsage

text (required)

The text of the message to be sent

api_id (not implemented yet)
user (not implemented yet)
password (not implemented yet)
from (not implemented yet)
concat (not implemented yet)
deliv_ack (not implemented yet)
callback (not implemented yet)
deliv_time (not implemented yet)
max_credits (not implemented yet)
req_feat (not implemented yet)
queue (not implemented yet)
escalate (not implemented yet)
mo (not implemented yet)
cliMsgId (not implemented yet)
unicode (not implemented yet)
msg_type (not implemented yet)
udh (not implemented yet)
data (not implemented yet)
validity (not implemented yet)

The response will be:

ID: followed by message id

eg. ID: 18e8221e5aa50cfad72376e08f40388a;

Status codes are defined by the Clickatell API.

ERR: xxx

where xxx is a numeric error code

e.g. ERR: 105, Invalid Destination Address;

$resp = $hSMS->si_push(to => '19991234567', si_text => 'Check this out', si_url = 'http://www.perl.org');

WAP Push Service Indication (SI) is a WAP address embedded within the header of a specially formatted SMS. This is displayed as an alert message to the user, and gives the user the option of connecting directly to a particular URL via the handsets WAP browser (if supported). This command enables you to send a WAP Push Service Indication.

to (required)

A phone number or list of phone numbers to recieve the messsage

si_id (required)

Unique ID for each message

si_url (required)

The URL used to access the service

si_text (required)

The text of the message to be sent

si_created (not implemented yet)
si_expires (not implemented yet)
si_action (not implemented yet)
from (not implemented yet)
concat (not implemented yet)
deliv_ack (not implemented yet)
callback (not implemented yet)
deliv_time (not implemented yet)
max_credits (not implemented yet)
req_feat (not implemented yet)
queue (not implemented yet)
escalate (not implemented yet)
mo (not implemented yet)
cliMsgId (not implemented yet)
validity (not implemented yet)

The response will be:

ID: xxx TO: xxx

eg. ID: ID: 18e8221e5aa50cfad72376e08f40388a TO: 99991234567;

Status codes are defined by the Clickatell API.

ERR: xxx

where xxx is a numeric error code

e.g. ERR: 105, Invalid Destination Address;

SEE ALSO

SOAP::Lite, Clickatell SOAP API Specification V 1.1.8

AUTHOR

Peter Farr <peter.farr@lpi-solutions.com>

COPYRIGHT AND LICENSE

Copyright (C) 2010 by Peter Farr

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