The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
SMS-Send-IN-Textlocal-1.00
River stage zero No dependents
/ SMS::Send::IN::Textlocal

NAME

SMS::Send::IN::Textlocal - Regional context SMS::Send driver to send messages via Textlocal's India service ( https://api.textlocal.in/send/ )

VERSION

version 1.00

SYNOPSIS

  use SMS::Send;
 
  # Create a sender
  my $sender = SMS::Send->new(
    'IN::Textlocal',
    _login           => 'senderid',          # use actual DLT registered header / sender id 
    _password        => 'apikey',            # use actual Textlocal API key
  );
  # Send a message
  my $sent = $sender->send_sms(
      text => 'This is an example message',  # use actual DLT approved content template
      to   => '91XXXXXXXXX',                 # use actual 10 digit mobile number in place of 'XXXXXXXXXX'
  );
  if ($sent) {
  print "Message send OK\n";
  }
  else {
  print "Failed to send message\n";

DESCRIPTION

An Indian regional context driver for SMS::Send to send SMS text messages via Textlocal's SMS Gateway in India - https://api.textlocal.in/send/ with 100% compliance to Telecom Regulatory Authority of India's (TRAI) TCCCPR 2018 norms which are accessible at https://trai.gov.in/sites/default/files/RegulationUcc19072018.pdf

This is not intended to be used directly, but instead called by SMS::Send (see synopsis above for a basic illustration, and see SMS::Send's documentation for further information).

The driver uses the Textlocal's HTTPS API mechanism for SMS. This is documented at https://api.textlocal.in/docs/.

METHODS

new

Constructor, takes argument pairs passed by SMS::Send, returns an SMS::Send::IN::Textlocal object. See usage synopsis for example, and see SMS::Send documentation for further info on using SMS::Send drivers.

Mandatory arguments include:-

_login

The DLT approved sender id / header allotted to the user institution

_password

The Textlocal API key for the Textlocal user account

Additional arguments that may be passed include:-

_endpoint

The HTTPS API endpoint. Defaults to https://api.textlocal.in/send/

_debug

Whether debugging information is output or not.

send_sms

Send the message - see SMS::Send for details. It requires two additional parameters to function with the Textlocal SMS gateway in India:

"text"

The DLT approved service implicit content template. The driver restricts it to 160 characters which forms the message body.

"to"

Destination mobile phone number in India. Numbered as per NNP 2003 i.e. 91XXYYYZZZZZ.

MISCELLANEOUS

Recipient phone number checks

Additional checks have been placed into the code for ensuring compliance with Indian National Numbering Plan 2003 (and its subsequent amendments). This measure is expected to prevent user generated errors due to improperly formatted or invalid mobile numbers, as noted below:

Example 1 : "819XXXXYYYYY"

81 is an invalid country code. As an India specific driver, the country code must be 91.

Example 2 : "9XXXXYYYYY"
Example 3 : "8XXXXYYYYY"
Example 4 : "7XXXXYYYYY"
Example 5 : "6XXXXYYYYY"

As per National Numbering Plan 2003, cell phone numbers (GSM, CDMA, 4G, LTE) have to start with 9XXXX / 8XXXX / 7XXXX / 6XXXX series (access code + operator identifier). A phone number that does not fit this template will be rejected by the driver.

Example 6 : "12345678"
Example 7 : "12345678901234"

A phone number that is less than 10-digits long or over 12-digits long (including country code prefix) will be rejected as invalid input as per NNP 2003.

Example 8 : "+91 9XXXX YYYYY"
Example 9 : "+91-9XXXX-YYYYY"
Example 10 : "+919XXXXYYYYY"
Example 11 : "09XXXXYYYYY"

Phone numbers formatted as above, when input to the driver will be handled as "919XXXXYYYYY" by the driver.

Error Codes

The following error code are returned by the NIC HTTPS API:

- 3 : Invalid number. =item - 4 : No recipients specified. =item - 5 : No message content. =item - 6 : Message too long. =item - 7 : Insufficient credits. =item - 8 : Invalid schedule date. =item - 9 : Schedule date is in the past. =item - 10 : Invalid group ID. =item - 11 : Selected group is empty. =item - 32 : Invalid number format. =item - 33 : You have supplied too many numbers. =item - 34 : You have supplied both a group ID and a set of numbers. =item - 43 : Invalid sender name. =item - 44 : No sender name specified. =item - 51 : No valid numbers specified. =item - 80 : Invalid Template. The message given didn't match any approved templates on your account. =item - 191 : Schedule time is outside that allowed. =item - 192 : You cannot send message at this time.

In the driver we only check if the status code is success or not in the response sent back by the SMS Gateway. In case of failure we send the output to STDERR.

INSTALLATION

See https://perldoc.perl.org/perlmodinstall for information and options on installing Perl modules.

BUGS AND LIMITATIONS

You can make new bug reports, and view existing ones, through the web interface at http://rt.cpan.org/Public/Dist/Display.html?Name=SMS-Send-IN-Textlocal.

AVAILABILITY

The project homepage is https://metacpan.org/release/SMS-Send-IN-Textlocal.

The latest version of this module is available from the Comprehensive Perl Archive Network (CPAN). Visit http://www.perl.com/CPAN/ to find a CPAN site near you, or see https://metacpan.org/module/SMS::Send::IN::Textlocal/.

Alternatively, you can also visit the GitHub repository for this driver at https://github.com/l2c2technologies/sms-send-in-Textlocal

ACKNOWLEDGEMENT

A big thanks to authors of pre-existing regional send driver authors, my K-C colleagues whose work on the drivers were a big inspiration. Also, a big shoutout to my ex-colleague Teertha Chatterjee who assisted in testing the code in production when it was being developed.

AUTHOR

Indranil Das Gupta <indradg@l2c2.co.in> (on behalf of L2C2 Technologies).

COPYRIGHT AND LICENSE

Copyright (C) 2023 L2C2 Technologies

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

This software comes with no warranty of any kind, including but not limited to the implied warranty of merchantability.

Your use of this software may result in charges against / use of available credits on your NIC SMS Service account. Please use this software carefully keeping a close eye on your usage and/or billing, The author takes no responsibility for any such charges accrued.

Document published by L2C2 Technologies [ https://www.l2c2.co.in ]