NIC SMS SERVICE INTEGRATION

NIC SMS SERVICE INTEGRATION

Overview
NIC Messaging Division has set up new SMS Gateway services. In order to integrate your application
and to access different services like reports and statistics please refer to below steps.

To use the SMS service, below are the credentials.

User Login Credentials provided to you

PARAMETERS VALUES
User Name
Password
Sender Id
Allowed Ip

HTTP API Integration

Using the below mentioned URLs you can send SMS. For old accounts, authentication credentials and
sender id have been already provided. Please use the same credentials.

o English (plain text) Message

For sending SMS in English the URL is

http://smsgw.sms.gov.in/failsafe/HttpLink?username=XXXXX&pin=XXXXX&message=<messaget
ext>&mnumber=mobilenumber&signature=<sender id>

Using the above URL you can send English messages to any mobile subscribers. Currently, we
support maximum of 6000 characters for plain text messages.

PARAMETERS DESCRIPTION
Username It is an accountid which will be provided by SMS Platform during account creation.
Pin It is a password which will be provided by the SMS platform during the account creation.
Mnumber It is mobile number with country code.
Message It is a SMS text content.
Signature It is sender id or from address which will be configured by SMS platform during account
creation.

NIC SMS Gateway, confidential & proprietary information Page 2

NIC SMS SERVICE INTEGRATION

o Unicode Message (Non English Messages)

http://smsgw.sms.gov.in/failsafe/HttpLink?username=XXXXXX&pin=XXXX&message=<FEFF092
A093009400915094D09370923002009380902092609470936 >&mnumber=mobilenumber
&signature=<senderid>&msgType=UC

Using the above URL the user can send messages in any language to any mobile subscribers.

Example for Unicode: FEFF092A093009400915094D09370923002009380902092609470936

In the field of message in the above Url the user has to type the message in the format mentioned in
the above example. As a result the mobile subscriber will receive the message in their handset
as( ).Currently, we support maximum of 6000 characters for Unicode messages.

PARAMETERS DESCRIPTION
username It is an accountid which will be provided by SMS Platform during account creation.
pin It is a password which will be provided by the SMS platform during the account creation.
mnumber It is mobile number with country code.
message It is a SMS text content.
signature It is sender id or from address which will be configured by SMS platform during account
creation.
msgType Message type , here it will UC

o Flash Message

http://smsgw.sms.gov.in/failsafe/HttpLink?username=XXXXX&pin=XXXXX&message=
messagetext&mnumber=mobilenumber&signature=<sender id>&msgType=FL

PARAMETERS DESCRIPTION
username It is an accountid which will be provided by SMS Platform during account creation.
Pin It is a password which will be provided by the SMS platform during the account creation.
mnumber It is mobile number with country code.
message It is a SMS text content.
signature It is sender id or from address which will be configured by SMS platform during account
creation.

NIC SMS Gateway, confidential & proprietary information Page 3

NIC SMS SERVICE INTEGRATION

o Port Message

http://smsgw.sms.gov.in/failsafe/HttpLink?username=XXXXX&pin=XXXXX&message=
messagetext&mnumber=mobilenumber&signature=<sender id>&msgType=SP&port=XXXXXX

PARAMETERS DESCRIPTION
username It is an accountid which will be provided by SMS Platform during account creation.
Pin It is a password which will be provided by the SMS platform during the account creation.
mnumber It is mobile number with country code.
message It is a SMS text content.
signature It is sender id or from address which will be configured by SMS platform during account
creation.
msgType Message type , here it will SP
port It is a port number to which port the message should be delivered

HTTP API Parameters: Below are the API parameters which are being used for SMS Services.

S.No Parameter Type Description

1 username * String User name will be the same as provided by the NIC SMS gateway
team.
2 pin * String Secret password; will be provided by SMS Platform
3 mnumber * String Mobile number with country code
4 message * String SMS Text content
5 scheTime String Scheduled time to deliver this message in the
format of yyyy/MM/dd/HH/mm; default is null
6 signature* String Sender id / from address; This will be configured
by SMS Platform during account creation.
7 expiry Number In minutes; example: 20 represents the message should expire if
not delivered to SMSC within 20 minutes from the message
accepted time of SMS Platform. Value 0 represents no expiry;
default value is 0.
8 splitAlgm String split message will be splits based on operator restriction
(140/160 for English) and delivered; trunc message will be
truncated after the split based on operator restriction; concat
message will be concatenated while delivery but billing will
happen based on number of split messages.
9 custref String Client generated unique id for clients reference; It
should be numeric and less than 30 digits.

NIC SMS Gateway, confidential & proprietary information Page 4

NIC SMS SERVICE INTEGRATION

10 msgType String PM Plain text message; UC Unicode Message;

BM Binary text message(ringtone, logo, picture, wap link); FL
Flash message; SP messages to special port; default is PM
11 udh String User data header info for binary messages;
12 port Number Port to deliver the message.
Max Length 6
13 Dlrtype Number 0 No need for dlr;
1 end delivery notification success or failure
2 end delivery notification failure only
4 SMS Platform failures / reject status only;
5 - SMS Platform failures / reject status + end delivery notification
success or failure;
6 - SMS Platform failures/reject status + end delivery notification
failure;
default is 0
*: mandatory

HTTP API Error Codes

Below are the error codes of HTTP API.

S. No. Error Code Description

1 -2 Invalid credentials
2 -3 Empty mobile number
3 -4 Empty message
4 -5 HTTPS disabled
5 -6 HTTP disabled
6 -410 Invalid Destination Address
7 -201 Email Delivery Disabled
8 -404 Invalid MsgType
9 -406 Invalid Port
10 -407 Invalid Expiry minutes
11 -408 Invalid Customer Reference Id
12 - 433 Invalid Customer Reference Id Length

NIC SMS Gateway, confidential & proprietary information Page 5

NIC SMS SERVICE INTEGRATION

13 -13 Internal Error

14 -401 Invalid Scheduled Time
15 000 SMS Platform Accepted

Sample Responses:

Sample Success response,

Message Accepted for Request ID=1111914721121631782146~code=API000&info=Velti accepted & Time
=2007/10/04/09/58
Sample Error response,
Message Rejected for Request ID= ~code=API-2 & info=REJECTED: Invalid credentials & Time =
2007/10/04/10/31

NIC SMS Gateway, confidential & proprietary information Page 6

NIC SMS SERVICE INTEGRATION

Real Time Delivery Reports: In order to receive delivery reports to the client URL directly, below are
the steps:
1. The clients should share the HTTP Query string interface URL to NIC SMS gateway to handover the
operator ACK and DNs.
2. Following is the expected query string URL format,
http://IP:PORT/app-context?a2wackid=<a2wi-cknowledgement-id>&a2wstatus=<a2wi-
status>&carrierstatus=<carrier-status>&lastutime=<yymmddHHmm>&custref=<customer-referece-
id>&submitdt=<yymmddHHmm>&mnumber=<mobileno>
3. Clients should share the URL response OK to validate the successful handover
4. Below are the parameters:
S No. Parameter Description
1 a2wackid Acknowledgement id got from NIC SMS GATEWAY while submitting the
message to NIC SMS GATEWAY platform
2 a2wstatus NIC SMS GATEWAY ACK/DN status
3 carrierstatus Operator ACK/DN status
4 lastutime Operator Last Attempt time (in the format of yyMMddHHmm; here yy years
in two digit format, MM months in two digit format, dd days in two digit
format, HH Hours in 24 hour format, mm minutes in two digit format)
5 custref Customer reference id at time message submit
6 submitdt Message submitted date (in the format of yyMMddHHmm; here yy years in
two digit format, MM months in two digit format, dd days in two digit
format, HH Hours in 24 hour format, mm minutes in two digit format)
7 mnumber Mobile number
8 Sts Operator submitted Timestamp date (in the format of yyMMddHHmm; here yy
years in two digit format, MM months in two digit format, dd days in two
digit format, HH Hours in 24 hour format, mm minutes in two digit format)
9 Msg Message, first 20 characters
10 Acode Account code (User Name)
11 Senderid Senderid

NIC SMS Gateway, confidential & proprietary information Page 7

NIC SMS SERVICE INTEGRATION

Operator Status Parameter Values

Sl No Value / Message state Description
1 DELIVRD Message is delivered to Destination.
2 EXPIRED Message validity period has expired.
3 DELETED Message has been deleted.
4 UNDELIV Message is undeliverable
5 ACCEPTD Message is in accepted state
6 UNKNOWN Message is in invalid state
7 REJECTD Message is in a rejected state

NOTE

User Name is the account Id which will be provided by the SMS platform during the period of
account creation.
Pin will also be provided by the SMS platform. It is a secret password which will be authenticated
through LDAP.
Sender ID will be provided by the SMS platform. This will be used across the entire messaging. No
other sender id can be used to push messages.

URL for Web Interface (Console)

http://sms.gov.in/
Using the above URL user can login using login credentials provided by the SMS platform during the
account creation and send SMS to any mobile subscribers. It enables users to create groups and upload file of
mobile numbers and send message in bulk. The GUI login credentials and LDAP credentials are same.

INFOCENTER Reporting Console

http://reports.sms.gov.in
Using the above URL the user can view the summary and detailed account transaction reports. The GUI
login credentials and LDAP credentials are same.

NIC SMS Gateway, confidential & proprietary information Page 8

NIC SMS SERVICE INTEGRATION

TROUBLE SHOOTING

NOTE: To use any services, please share the IP of the server/client which you wish to use for SMS
services.

The below mentioned steps are for users trouble shooting if any problem occurs in the connectivity:

If user is not able to connect to NIC SMS server:

1. Ping Command:
a. Click on Start Button
b. Go to Run menu option
c. Type CMD and press enter
d. Command prompt will open
e. Type Ping smsgw.sms.gov.in or Ping 164.100.14.211
f. If output comes like

Ping is working fine.

g. If output comes like

Connectivity is not working properly. Please contact your system administrator.

2. Telnet Command (For Windows):

a. Click on Start Button.
b. Go to Run menu option
c. Type CMD and press enter
d. Command prompt will open

NIC SMS Gateway, confidential & proprietary information Page 9

NIC SMS SERVICE INTEGRATION

e. Type telnet smsgw.sms.gov.in or telnet 164.100.14.211 on port 80 and port 443.

f. If output comes like

telnet is working fine and connectivity is fine.

g. If output comes like

Connectivity is not working properly. Please contact your system administrator.

3. Outgoing IP
In case, user is receiving error like below:

This error means that user machines outgoing IP is not whitelisted at the NIC SMS gateway. To know
the outgoing IP, below is the test to be performed:

URL: http://smsgw.sms.gov.in/findip.jsp

Copy the above URL and paste the same in any web browser and press enter key. In return, user will
gets the outgoing IP on the web browser itself. Both IPs (shared with NIC to be whitelisted and IP on
the browser) should match. In case IPs are different, please contact your system administrator.

In case user is not having a Web Browser on the server and Operating System is Linux, use the
following command:

elinks dump http://smsgw.sms.gov.in/findip.jsp

NIC SMS Gateway, confidential & proprietary information Page 10

NIC SMS SERVICE INTEGRATION

4. Encoding Values

Some users application does not accept any special characters in password so, that particular special
character must be encoded with their respective values. The below mentioned are the encoding values
of special character.

Special Character Encoding Values

# %23
& %26
$ %24

NIC SMS Gateway, confidential & proprietary information Page 11