ValueFirst HTTP API Version 1.3.

User Guide Version <1.3.2>

1
 Table of Contents

Introduction 3
 Overview Of Service 3
 Sender ID Consideration 3
 Character set support 3
 Message Length 3
Using Service 4
 End Point 4
 Service Response 4
 Extended Parameters 5-6
 Using UDH for Wake-up Messaging 7
Sending Binary Messages 9
Sending Ringtones 10
Sending Bulk Messages 10
DLR URL 11
Message Status Error Code 12
Application Constraints (For bulk messages only) 12
HTTP Status Pull API 13
Regulatory Implementation and Impact 14
Sender ID Regulation 14
National Customer Call Preference Registry (NCCPR) 15

2
 Introduction
Overview of Service
ValueFirst HTTP SMS service is designed to let end user send across SMS messages using HTTP interface.
The API supports custom UDH, flash messages, message scheduling (if supported by operator) and various
other advance features.
The API is specially designed to let user send custom UDH while sending messages.

Character set support

GSM network supports GSM character set. Other than this ValueFirst HTTP API support sending messages in
Unicode using Unicode-16 Big-Ending and UTF-8 format.

Message Length
If a message is sent whose length is longer than permitted characters limit, it shall be counted as multiple
messages, however will be delivered on handset as a single message.

 For standard Latin character set 160 characters per SMS is supported. If SMS text is longer than 160
characters, messages shall be calculated in multiples of 153 characters.
 For Unicode messaging (non-English) only 70 characters per SMS is supported. If Unicode SMS text is
longer than 70 characters, messages shall be calculated in multiples of 67 characters.
 For Binary messaging 140 characters including UDH is supported. If Binary SMS is longer than 140
characters, messages shall be calculated in multiples of 134 characters.

3
 Using Service

End Point
The end point of the service is https://http.myvfirst.com/smpp/sendsms. The complete URL is as follows:
https://http.myvfirst.com/smpp/sendsms?username=[xxxxxxxx]&password=[
xxxxxxxx]&to=[xxxxxxxxxx]&udh=[xxxxxxxxx]&from=[xxxxxxxx]&text=[xxxxxxx
xxxxxxxx]&dlr-url=[xxxxxxxxxxxxx]....
The following are the required parameters:
Parameter Description
Username Specify the account name. Kindly contact ValueFirst to get one
Password Password attached to username
To Recipient number. Only single recipient is supported
From Sender Number or ID. Sender ID can be a 9-13 digits number
or 11 digit alpa-numeric sender ID.
Text Text that needs to be sent on mobile handset. In case of
binary content or Unicode messages the Text should be hex-
encoded value.
dlr-url Specify the path on which Delivery report need to be returned.
This is a path on your server, which shall be called in when a
delivery report is received by ValueFirst against an outgoing
message.
Udh User-defined data header. The data header is used for long
messages as well as sending binary content. If you need to
send message to specific port (for j2me application to
receive), you may specify the information in udh parameters.

Service Response
When data is posted on HTTP API, the following responses are generated.
Response Description
Sent. Message sent Successfully
Sent. Split into N Message was sent, however it was found to be longer
than permitted limit and hence was spitted into multiple
messages
Number(s) has/have been denied by white- and/or black- Invalid Recipient numbers.
lists.
Empty receiver number not allowed, rejected Recipient number is empty.

Sender missing and no global set, rejected Sender number is missing.

Empty text not allowed, rejected. Message Text is empty.

unknown request Kannel is down or SMSC connectivity problem.
Authorization failed for sendsms Invalid Username and Password.

4
Extended Parameters
The followings are the extended parameter supported by ValueFirst HTTP API. Please note that all variables
are in small case.

Variable Name Type Description

username String Username or account name. Please contact ValueFirst to get an
account for sending SMS.
password String Password associated with given username.
From String Phone number of the sender.
to String Phone number of the receiver.
Text String Contents of Message, URL encoded as necessary. The
Content can be more than 160 characters.

charset String Charset of text message. Used to convert to a format suitable for
7 bits or to UCS-2. Defaults to WINDOWS-
1252 if coding is 7bits and UTF-16BE if coding is UCS-2.
Udh String Optional User Data Header (UDH) part of the message. Must be
URL encoded. For detail on how to use UDH
for wake-up messaging, kindly see the next section
Mclass Number Optional. Sets the Message Class in DCS field. Accepts
Values between 0 and 3, for Message Class 0 to 3, A value of 0
sends the message directly to display, 1 sends to mobile, 2 to SIM
and 3 to SIM toolkit.
mwi number Number Optional. Sets Message Waiting Indicator bits in DCS field. If
given, the message will be encoded as a Message Waiting
Indicator. The accepted values are 0, 1, 2 and 3 for activating the
voice, fax, email and other indicator or 4, 5, 6, 7 for deactivating,
respectively. This option excludes the flash Option.
compress Number Optional. Sets the Compression bit in DCS Field.

Coding Number Optional. Sets the coding scheme bits in DCS field. Accepts values
0 to 2, for 7bit, 8bit or UCS-2. If unset, defaults to 7 bits unless a
UDH is defined, which sets
coding to 8bits.

5
dlr-mask Number (bit- Optional. Request for delivery reports with the state of
mask) the sent message. The value is a bit mask composed
of:
1: Delivered to phone,
2: Non-Delivered to Phone,
4: Queued on SMSC,
8: Delivered to SMSC,
16: Non-Delivered to SMSC.
Must set dlr-url on sendsms-user group or use the dlr-
url CGI variable.
dlr-url String URL Optional. If dlr-mask is given, this is the url to be
fetched.
(Must be url-encoded)
alt-dcs Number Optional. If unset, Kannel uses the alt-dcs defined on
SMSC configuration or 0X per default. If equals to 1,
uses FX.
If equals to 0, force 0X.
Rpi Number Optional. Sets the Return Path Indicator (RPI) value.
(See ETSI Documentation).
priority number Number Optional. Sets the Priority value (Range 0-3 is allowed).
category String Optional parameter to send bulk messages. It can
consists of value: bulk

6
Using UDH for Wake-up Messaging

UDH is used for sending long messages that are assembled at Mobile device level into one SMS. UDH is also
used for sending specialized messages like Ringtone, logo, picture messages, vCard, vCAL and messages to
custom mobile applications.
The most common use of UDH is to send message to a specific port (called destination port). Since each port
has a different meaning on mobile phone, mobile phone understands message content according to port of
the message.
The following are the standard ports:

7
The UDH parameter which is usually 12 bytes hex content need to be setup in following manner:

In above example you need to send &udh=%0B%05%04%23%F5%00%00%00%03%02%02%01

The Underlined part indicates destination and source ports. Other fields like SMS reference number, total
number of messages in block and current sequence number shall change according to number of messages
used for transferring current information.

However if the message can be accommodated in 1 SMS only then you may change the UDH length as well
as remove elements related to message concatenation information. The new UDH may look like following:

For single message case your UDH has now become &udh=%06%05%04%15%82%00%00

8
Sending Binary Messages
ValueFirst HTTP SMS service can be used to send binary messages. To send binary messages to CDMA
numbers, client need to send well formed user data header failing on which service will return an error.
Binary message text must be prefixed with well formed user data header.

User data header for CDMA numbers contains following parameters:

<Keyword><port-information><delimiter> Where,
 Keyword: It must be “//SCKL”

 Port-Information: it contains following parameters:

<destination-port-address> or <destination-port-address><source-port-address> or
<destination-port-address><source-port-address><SAR-info>

 Delimiter: <space>

Message Text would be:

Bytes Number Value Description

1-6 //SCKL WDP datagram addressing scheme to the receiving
device.
7-10 158A Information Element Data (bytes 7 to 10  158A –
destination port).
11-14 0000 Information Element Data (bytes 11 to 14  0000 –
source port). It is optional.
15-16 00 Information Element Identifier i.e. 8-bit reference
number.
17-18 02 Information Element Data (total number of
concatenated messages(0-255))
19-20 01 Sequence number of current short message.
21 <space>
22 byte onwards 1-n 8-bit Hexadecimal value of message text.
characters
of user
data

However, if message text can be sent in one SMS only then, we may change the user data header as i.e.

Bytes Number Value Description

1-6 //SCKL WDP datagram addressing scheme to the receiving
device.
7-10 158A Information Element Data ((bytes 7 to 10  158A –
destination port).
11 <space>
12 byte onwards 1-n 8-bit Hexadecimal value of message text.
characters
of user data

9
 Ringtone on CDMA Numbers
Following is an example of ringtone message, which can be sent by single SMS. Ringtone reader listens on
port 1581 of the mobile terminal.

Ex: 024A3A650995D1D195C93D999804144288F511610611624D30831445

Bytes Value Description

Number
1-6 //SCKL WDP datagram addressing scheme to the receiving
device.
7-10 1581 Information Element Data ((bytes 7 to 10  158A –
destination port).
11 <space> It is a delimiter between user data header and binary
message text.
12 byte 1-n 8-bit characters 024A3A650995D1D195C93D999804144288F511610611
onwards of user data 624D30831445

Udh part for given ring tone would be //SCKL1581+ so the URL encoded text
parameter would be as:

%2F%2FSCKL158A000000+024A3A594D8549951D84040018D9049161361561661861A61C
6288B000

Sending Bulk Message

HTTP API incorporates function to send bulk messages to multiple users throughout single HTTP session. It
can send bulk messages to maximum 100 recipients (mobile number) in single sessions.

Customer can use following sample URL in the http request to send bulk message:

Sample URL:
https://xxx.xxx.x.xxx/sendsms?username=vf&password=vf123&to=9198xxxxxxxx,9199xxxxxxxx&f
rom=Senderid&text=this%20is%20a%20test%20message&category=bulk

Parameters in Requested URL Description

Username Stores valid user name to access HTTP API service
Password Stores valid password to access HTTP API service
To Stores mobile number of recipients prefixed by “91” digit and
separated by comma
From Stores send id of message sender
Text Stores the actual message text to be delivered on the mobile
phone of user
Category Stores the value as “bulk” that specifies bulk messages are
to be sent to multiple recipients. By default, this parameter
stores value: blank that specifies bulk messages will not be
sent in currently established HTTP session.
entityid DLT Principal entity id. This is an optional parameter.
dlt_templateid DLT Template id. This is an optional parameter.
headerid DLT header id. This is an optional parameter.
dltcontenttype DLT Content Type. This is an optional parameter. Only
numeric value is accepted. (1: Service Implicit, 2: Service
Explicit, 3:Transactional, 4:Promotional)

1
 DLR URL
Customer can use following sample URL for receiving the DLR:

Sample DLR URL:

https://ip/app/status?unique_id=%7&reason=%2&to=%p&from=%P&time=%t&status=%d

Encoded dlr-url parameter will be:

https%3A%2F%2Ffanyv88.com%3A443%2Fhttps%2Fip%2Fapp%2Fstatus%3Funique_id%3D%EF%BB%BF%257%26reason%3D%
EF%BB%BF%252%26to%3D%EF%BB%BF%25p%26from%3D%25P%26time%3D%25t%26sta
tus%3D%25d

Below table depicts the parameter values to be passed to get corresponding values

Sample Parameter Values Sample Response

names
TO %p 919812345678
FROM %P VFIRST
TIME %t 2017-05-23 16:55:18
MESSAGE_STATUS %d 1
REASON_CODE %2 000
DELIVERED_DATE %3 2017-05-23 16:55:18
STATUS_ERROR %4 8448
CLIENT_GUID %5 kh5ng551155213b161011bme3vTEST
USER
CLIENT_SEQ_NUMBE %6 Value as Submitted
R
MESSAGE_ID %7 h5ng551155313946013uw3
CIRCLE %8 Delhi
OPERATOR %9 AIRCEL
TEXT_STATUS %13 Success
SUBMIT_DATE %14 2017-05-23 16:55:11
MSG_STATUS %16 Delivere
d
Note:
In the requested HTTP URL to send bulk messages, the attributes used in the URL can be named accordingly
but values used corresponding to used attributes or variables are case sensitive.

1
Message Status Error Code
HTTP API processed messages‟ status can be tracked via the following list of error code.
Error Code Error Type Description
„1‟ Invalid Receiver This error code generates if message(s) receiver’s mobile
number:
 Is invalid
 Greater than 16 digits
„2‟ Invalid Sender This error code generates if message sender:
 Uses wrong alphanumeric/numeric sender ID
 Uses sender ID of greater than 16 digits
„3‟ Invalid Message This error code generates if:
 Blank message is sent
 UDH header section does not encapsulate binary content
 Message template does not match (In case of
transactional messages)
„4‟ Service not available This error code generates if:
 Operator’s service is down
 Server side services are down
„5‟ Authorization failed This error code generates if server side authentication fails owing to:
 Wrong user name
 Wrong password
 Wrong user name and password
„6‟ Contract Expired This error code generates if service usage contract expires.
„7‟ Credit Expired This error code generates if message(s) sender’s credit account
balance is zero.
„8‟ Empty Receiver This error code generates if message recipient’s number is not
mentioned in the HTTP API‟s parameters.
„14‟ Non-compliant This error code generates if the message is sent violating
message TRAI guidelines and set of rules.
28702 Invalid DLT This error codes comes in case of any invalid or blank values
Parameters received in DLT parameters.
28703 Invalid DLT Content This error codes comes in case of any invalid or blank DLT content
Type type value.

Application Constraints (For bulk messages only)

HTTP API v1.1 specifies following constraints:
 Doesn’t send messages on duplicate number.
 Doesn’t send binary messages.
 Can send bulk messages to maximum 100 recipients throughout single HTTP session.
 Employs only “Get” method to send requested HTTP URL.
 Requires “91” digit as prefix to the mobile number of recipient separated by comma.

1
 HTTP Status Pull API
An API has been developed to check the status of GUID submitted on HTTP API where
category=Bulk.
Category Bulk- Stores the value as “bulk” that specifies bulk messages are to be sent to
multiple recipients in a single HTTP hit.

Once user sends SMS using HTTP service:-

https://http.myvfirst.com/smpp/sendsms?username=XXXXX&password=XXXXXX&to=91
XXXXXXXXXX&udh=&from=VFIRST&text=This%20is%20a%20test%20SMS%20flash%
20SMS&category=bulk
A GUID is returned to the user acknowledging successful submission (with errorcode=0)
guid=XXXXXXXXXXXXXXXXXXXXXHTTP&errorcode=0&seqno=91XXXXXXXXXX

GUID STATUS CHECK

• Using the GUID user can check the delivery status using following URL by providing their
username, password along with the GUID..
https://http.myvfirst.com/smpp/status?username=XXXXXXX&password=XXXXXXXX&guid=k
h4rc500404XXXXXXXXXXXXXXX

• Sample response returned to the user

guid=kh4rc500404XXXXXXXXXXXXXXX&mobile=91XXXXXXXXXX&errorcode=8449&seqn
o=1&reasoncode=009&statusdate=2017-04-27 12:50:04

• If multiple mobile numbers is submitted it will return comma separated mobile number wise
response.

OR

Mobile Number Wise Response

• User can pass mobile number along with GUID to get status of a particular mobile number.
Mobile number is an optional field.

• Sample API call:-

https://http.myvfirst.com/smpp/status?username=XXXXXXX&password=XXXXXX&guid=kh4
5c272733113b110014q57kqDABSOLUTET&mobile=91XXXXXXXXXX

• Sample response for DLR status:-

guid=kh45c27XXXXXXXXXXXXXXXXXX&mobile=91XXXXXXXXXX&errorcode=8448&seqn
o=1&reasoncode=000&statusdate=2017-01-06 14:08:48

1
Error Codes
All the DLT and operator related DLR errors codes that may come across in ValueFirst are listed below:

Error Codes Description Remark

001 Invalid_number Existing error code of delivery failure
002 Absent_subscriber Existing error code of delivery failure
003 Emory_capacity_exceeded Existing error code of delivery failure
004 Mobile_equipment_error Existing error code of delivery failure
005 Network_error Existing error code of delivery failure
006 Barring Existing error code of delivery failure
007 Invalid_senderid Existing error code of delivery failure
008 Dropped Existing error code of delivery failure
009 Ndnc_failed Existing error code of delivery failure
100 Misc. Error Existing error code of delivery failure
110 Entity not found DLT related error, Only applicable towards India
111 Entity not registered DLT related error, Only applicable towards India
112 Entity inactive DLT related error, Only applicable towards India
113 Entity blacklisted DLT related error, Only applicable towards India
114 Invalid telemarketer DLT related error, Only applicable towards India
115 Header not found DLT related error, Only applicable towards India
116 Header inactive DLT related error, Only applicable towards India
117 Header blacklisted DLT related error, Only applicable towards India
118 Template not found DLT related error, Only applicable towards India
119 Template inactive DLT related error, Only applicable towards India
120 Template not matched DLT related error, Only applicable towards India
121 Template blacklisted DLT related error, Only applicable towards India
122 Invalid consent DLT related error, Only applicable towards India
123 General consent error DLT related error, Only applicable towards India
124 DLT miscellaneous error DLT related error, Only applicable towards India
122 Invalid consent DLT related error, Only applicable towards India
123 General consent error DLT related error, Only applicable towards India
124 DLT miscellaneous error DLT related error, Only applicable towards India

Sender ID Regulation
Telecom Regulatory Authority of India (TRAI) has given a direction to all telecom service provider of India to prefix
an Identification Code before SenderID for every message sent using alpha and numeric sender id. The Direction can
be downloaded directly from TRAI website or simply by clicking following link:
https://www.trai.gov.in/WriteReadData/trai/upload/Directives/131/direction10dec08.pdf
1
The Identification Code will be of three characters, consisting, Service Provider Code and Service Area Code,
followed by a Hyphen character. Hence, the maximum length of a sender ID has been fixed to 6 characters for
alpha and numeric both.

1
The details of operator codes are as below:

The Details of Circle codes are as below:

1
National Customer Call Preference Registry (NCCPR)
NCCPR (previously known as NDNC) is a database of all users who do not wish to receive unsolicited
commercial communication. The list is managed by TRAI. ValueFirst has a strict No-SPAM policy and hence a
person whose mobile number exists in this list must not be sent any commercial communication using voice
or SMS, unless s/he has not given explicit permission to receive so.