XML Api 1.5.1.05

XML API 1.5.1.
05
User Guide
1
2
Table of Contents
ValueFirst XML API 3
Guidelines for Sending Messages 3
Receiver Phone Number 3
Message Text 3
Sender ID 4
Encoding Procedure 4
Accessing Server Services 6
SMS-MT Service 7
a. SMS-MT Example of Sending Text Messages 7
b. SMS-MT Example of Response 8
c. Additional Parameters 8
d. SMS-MT Example of Sending Picture Messages 9
e. SMS-MT Example of Sending Ring tones 9
f. SMS-MT Example of Sending vCard (Business Card) 10
g. SMS-MT Example for Sending WAP Push 10
h. SMS-MT Example of Sending Unicode Text Messages 11
i. SMS-MT Example of Sending Message on Specified Port 12
SMS-SR Status Request Service 12
DLR URL 13
SMS-CR Service 14
SMS-CR Example of Credit Request 14
SMS-CR Example of Credit Request Response 14
Scheduling Framework 15
Scheduling Support in ValueFirst XML API 15
Setting up Messages for Future Delivery 15
Deleting Scheduled Message 16
Update Scheduled Message 16
List Scheduled Message 17
Standard Error Codes 18
Regulatory Implementation and Impact 20
Sender ID Regulation 20
National Customer Call Preference Registry (NCCPR) 21
www.vfirst.com
3
ValueFirst XML API provides an open HTTP and XML standards based API for integrating SMS
capabilities into any application or an enterprise system. ValueFirst XML API is a store and
forward mechanism for sending and receiving SMS through the API endpoint(s) to the clients.
ValueFirst XML API is specially designed for sending bulk messages through server-to-server
communication. This API is available in XML-based HTTP / HTTPS post format only.
ValueFirst XML API provides single authentication for multiple messages and target numbers.
The endpoint for this API is based on Message Queue architecture that provides high message
throughput.
Guidelines for Sending Messages

The following guidelines must be followed while using XML API for sending the messages.
Receiver Phone Number

• For national and international messaging, the mobile number should be prefixed
with the appropriate country code e.g. 91 in case of an Indian number.
• No special character like "-", "(",")" or anything similar is allowed in the phone
number, e.g., 91-9812345678 is disallowed.
Character Set Support

• ValueFirst XML API support sending messages in GSM Character set, and for 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.
www.vfirst.com
4
Sender ID
As per DOT and TRAI guideline, all alpha sender IDs and short-code sender ID will be prefixed by operator
and circle code. For sending SMS in India, alpha sender IDs of 6 characters only is allowed for transactional
SMS and numeric sender ID of 6 digits is allowed for promotional SMS. This has been done to make NCPR
(National Do Not Call) compliance easier. The details of operator/circle and corresponding prefixes are
mentioned at the end of the document.
For international mobile numbers, alpha numeric sender ID up to 16 characters is allowed.
Encoding Procedure
ValueFirst Server accepts all content in XML. As your message is an XML packet, special characters in
message text needs to be converted XML encoded. As a rule of thumb all string data should be XML
encoded as shown below:
Note: This is only required if you are posting data through a client application. Web browsers can
automatically convert the text to HTML encoded format. The encoding for sending message through
ValueFirst Pace Server requires two steps.
Step 1
The following table displays the codes that have to be replaced.
Code Replace with
#39 (single quote) &apos
#32 (space) &#032
#34 (double quote) &quot
> &gt
< &lt
#13 (Line feed) &#013
#10(form feed) &#010
#9(Tab) &#009
Step 2
ValueFirst Server accepts all data as a form post. Therefore, it is required that all XML content needs to be
URL encoded before hitting ValueFirst Server.
Rules for encoding XML content to URL format:
1. Select for each character in messages.
2. If the ASCII value of the character is greater than 128 or smaller than 32 or the character is „*‟, „#‟,
„%‟, „<‟, „>‟ or „+‟, replace it with its corresponding hexadecimal (hereinafter Hex) value (2 digits with
leading zero) proceeded by a „%‟ character, e.g., space is encoded into %20.
• * is encoded into %2A
• # is encoded into %23
• % is encoded into %25
www.vfirst.com
5
• < is encoded into %3C

• > is encoded into %3E
• + is encoded into %2B
• enter key (#13#10) is encoded into %0D%0A
Encoding example
Before Encoding
http://api.myvfirst.com/psms/servlet/psms.Eservice2?data=<?xml version="1.0" encoding="ISO-8859-

1"?><!DOCTYPE MESSAGE SYSTEM
“http://127.0.0.1:80/psms/dtd/messagev12.dtd”><MESSAGE><USER USERNAME="test"
PASSWORD="XXXXXX"/><SMS UDH="0" CODING="1" TEXT="The flight # <101> "DEL" to "BLR" is
delayed and it's revised time will be informed later. Have a nice day!" PROPERTY="0" ID="1"><ADDRESS
FROM=“VFIRST” TO="91XXXXXXXXXX" SEQ="1" TAG="some customer end random data"
/></SMS></MESSAGE>&action=send
After Encoding
http://api.myvfirst.com/psms/servlet/psms.Eservice2?data=%3C?xml%20version=%221.0%22%20encoding=
%22ISO-8859-%22?%3E%3C!DOCTYPE%20 MESSAGE
%20SYSTEM%20%22http://127.0.0.1:80/psms/dtd/messagev12.dtd%22%20%3E%3CMESSAGE%3E%3C
USER%20USERNAME=%22test%22%20PASWORD=%22XXXXXX%22/%3E%3CSMS%20%20UDH=%22
0%22%20CODING=%221%22%20TEXT=%22The%20flight%20%23&btnG;%20<101>%20"DEL
"%20to%20"BLR"%20is%20delayed%20and%20it's%20%20revised%20time%20will
%20be%20informed%20later.%20Have%20a%20nice%20day!%22%20PROPERTY=%220%22%20ID=%22
1%22%3E%3CADDRESS%20FROM=%22ValueFirst%22%20TO=%2291XXXXXXXXXX%22%20SEQ=%22
1%22%20TAG=%22some%20clientside%20random%20data%22%20/%3E%3C/SMS%3E%3C/MESSAGE
%3E&action=send
Reference Links
For XML encoding
http://coderstoolbox.net/string/#!encoding=xml&action=encode&charset=iso_8859_1
For URL encoding

http://meyerweb.com/eric/tools/dencoder/
www.vfirst.com
6
Accessing Server Services

The username and password shall be provided by your account manager from ValueFirst. This
authentication information will be required for availing any of the services of ValueFirst Pace.
The end point for accessing ValueFirst XML API is
http://api.myvfirst.com/psms/servlet/psms.Eservice2
The above URL accepts data through two parameters namely “data” and “action”. The data
parameter specifies XML content that needs to be posted. The action parameter is different for
each XML (Table 2).
XML Data Parameter Action Psarameter

Sending SMS-MT Version XML (URN and send
message HTML encoded)
Checking SMS-SR Version XML (URN and status
status HTML encoded)
Checking SMS-CR Version XML (URN and credits
credits HTML encoded)
Table 2 Values for „data‟ and „action‟ parameter.
The complete example for a valid SMS-MT and SMS-SR is given in Figure 1.
www.vfirst.com
7
Figure 1 Page for testing various API functions - http://api.myvfirst.com/psms/
SMS-MT Service
ValueFirst XML API encompasses advance features specifically designed for sending bulk
messages. With this API, you do not have to send each message separately; multiple
messages can be sent together in a single transaction. The API also supports multiple target
numbers for a common message to the recipients.
a. SMS-MT Example of Sending Text Messages

Here is a complete example for a valid SMS-MT request using ValueFirst XML API.
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE MESSAGE SYSTEM "http://127.0.0.1:80/psms/dtd/messagev12.dtd" >
<MESSAGE>
<USER USERNAME="mycompany" PASSWORD="mycompany"/>
<SMS UDH="0" CODING="1" TEXT="hey this is a real test" PROPERTY="" ID="1">
<ADDRESS FROM=" VFIRST " TO="919812345678" SEQ="1" TAG=" " />
<ADDRESS FROM=" VFIRST " TO="mycompany" SEQ="2" />
<ADDRESS FROM=" VFIRST " TO="919812345678" SEQ="3" />
</SMS>
<SMS UDH="0" CODING="1" TEXT="hey this is a real test" PROPERTY="" ID="2"
SEND_ON="2007-10-15 20:10:10 +0530">
<ADDRESS FROM="VFIRST" TO="919812345678" SEQ="1" />
www.vfirst.com
8
<ADDRESS FROM="ALERTS" TO="919812345678" SEQ="2" />

</SMS>
</MESSAGE>
The following table describes the different elements of a SMS-MT request:
Tag Name Description

Users
USERNAME User name of the sender of the message.
PASSWORD User password.
SMS
UDH UDH is used for sending binary messages. For text message the value should be 0.
CODING Extended type of messages. For text message the value should be 1.
PROPERTY Unique property of message. Default value is 0. For sending Flash SMS the value should be
1.
ID Unique ID of message. The client sends this value. In future communication, server sends
this value back to the client. This value is used in future to check status of the message.
TEXT This field describes the message text to be sent to receiver. SMS can contain up to 160
characters in Message Text. API allows user to send message text of more than 160
characters. Credits will be deducted in the multiple of 160 characters according to the length
of SMS.
SEND_ON It is now possible to schedule a message. To schedule message to go at a later time, user
can specify “SEND_ON” date as attribute of SMS tag. Only absolute date is supported. The
value should be given in “YYYY-MM-DD HH:MM:SS TIMEZONE” format. Time zone is
difference w.r.t. to GMT. Please refer Scheduling Support for more information on this
feature.
ADDRESS Describe the Sender as well as Receiver address
FROM The Sender of the message. This field should conform to Sender Phone Number guidelines.
TO Person receiving the SMS, should confirm to Receiver Phone Number guidelines.
SEQ Unique Sequence ID. Must be an integer and must be unique to each SMS. While checking
message status you must send this value.
TAG A text that identify message. This is an optional parameter.
b. SMS-MT Example of Response
The following example shows sample response of ValueFirst XML API.
<MESSAGEACK>
<GUID GUID="kb4jc4243489a5f461209eo742--TESTUSER" SUBMITDATE="2017-05-
10 09:59:49" ID="1">
<ERROR SEQ="2" CODE="28682"/>
</GUID>
<GUID GUID="kb4jc4334130a5f461209l7t17--TESTUSER" SUBMITDATE="2017-05-10
09:59:49" ID="2"/>
</GUID>
</MESSAGEACK>
Alternatively, the following response may also come:

<MESSAGEACK>
<Err Code="52992" Desc="UserName Password Incorrect"/>
</MESSAGEACK>
The second one is usually received in case of critical error like authentication error, credit
expiry or service not available.
www.vfirst.com
9
The following table describes different elements of SMS-MT Response:

GUID A globally unique message ID that is generated for each <SMS> tag. Note that, in future to
check the status of the message you must save this code.
SUBMITDATE The date and time when the transaction was completed.
ID Unique SMS ID sent by the customer. For each message a unique GUID is generated.
Server sends SMS ID so that the client application can map the GUID to the SMS ID
ERROR provided
(In by any
case of them.
error)
To conserve bandwidth utilization ValueFirst XML API only sends sequence information of
messages that has either some error or was rejected because of some error.
If there are no errors in a particular message, you shall not receive any confirmation of each
address SEQ. For instance, in the above example in message ID 1 (of client) the TO
number „My company‟ was rejected as non-numeric. The second message does not have
any error, and hence there was no error information for the second part.
SEQ: The Sequence ID (provided by client) that has error.
CODE: Reason why the message wasn’t accepted. The table shown next describes these
error conditions.
c. Additional Parameters
Users can also pass additional parameters in XML as mentioned in below format. These
parameters will be stored at our end along with every message.
Here is an example for a valid SMS-MT request using ValueFirst XML API, with additional
parameters.

<MESSAGE>
<SMS UDH="0" CODING="1" TEXT="hey this is a test" PROPERTY="" ID="1" DLR="0"
VALIDITY="0">
<ADDRESS Msg_ID="ID1" DeptID="INBG" FROM=" VFIRST " TO="919812345678" SEQ="1"
TAG=" " />
<ADDRESS Msg_ID="ID1" FROM=" VFIRST " TO="mycompany" SEQ="2" />
<ADDRESS AppID="ALERT" FROM=" VFIRST " TO="919812345678" SEQ="3" />
</SMS>
<SMS UDH="0" CODING="1" TEXT="hey this is a test" PROPERTY="" ID="2"
SEND_ON="2007-10-15 20:10:10 +0530">
<ADDRESS Msg_ID="ID1" DeptID="INBG" AppID="ALERT" FROM="VFIRST"
TO="919812345678" SEQ="1" />
<ADDRESS Msg_ID="ID1" DeptID="INBG" AppID="ALERT" FROM="ALERTS"
TO="919812345678" SEQ="2" />
</SMS>
</MESSAGE>
These parameters shall be added in the address tag between “Address” and “From”. Up to 5
additional parameters can be added.
Note - Additional parameter names will have to be configured at

ValueFirst end before users can start sending these parameters.
d. SMS-MT Example of Sending Picture Messages
Here is a complete example for a valid SMS-MT request using ValueFirst XML API

www.vfirst.com
10
<MESSAGE>
<SMS UDH="1" CODING="3"
TEXT=";00481C01ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30
cc
f0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30c
c
f0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3c
cf
30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf
0f
30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf
0f
3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30
ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3" PROPERTY="" ID="2">
<ADDRESS FROM=“VFIRST” TO="919812345678" SEQ="3" />
</SMS>
</MESSAGE>
The following table describes the different elements of a SMS-MT request.

UDH UDH is used for sending binary messages. For picture message the value should be 1.
Coding Extended type of messages. For text message the value should be 3.
Text Message text must be in Hex characters for picture messages and it can contain
message text along with picture.
It must follow format „<Hex-converted message text>;<Hex-converted Nokia picture
format>‟ . If there is no message text with the picture then it must be „;<Hex-converted
WBmp>‟. It will cost you approx. 1 to 5 credits according to the length of SMS.
e. SMS-MT Example of Sending Ringtones
Here is a complete example for a valid SMS-MT request using ValueFirst XML API

<MESSAGE>
TEXT="024A3A594D8549951D84040018D9049161361561661861A61C6288B000"
PROPERTY="" ID="1">
<ADDRESS FROM="VFIRST" TO="919812345678" SEQ="1" TAG="some client side
random data" />
</SMS>
</MESSAGE>

UDH UDH is used for sending binary messages. For ringtone message the value should be 2.
Text It must contain Hex-converted PDU for ringtones.
www.vfirst.com
11
f. SMS-MT Example of Sending vCard (Business Card)
Here is a complete example of a valid SMS-MT request using ValueFirst XML API.

<MESSAGE>
<SMS UDH="4" CODING="3" TEXT="
424547494E3A56434152440D0A56455253494F4E3A322E310D0A4E3A536D6974
683B
4D696B650D0A54454C3B505245463A2B35353531323334350D0A454E443A5643
4152
440D0A" PROPERTY="" ID="1">
<ADDRESS FROM=" VFIRST " TO="919812345678" SEQ="1" TAG="some
data" />
</SMS>
<SMS UDH="4" CODING="3" TEXT=”
424547494E3A56434152440D0A56455253494F4E3A322E310D0A4E3A536D6974
683B
4D696B650D0A54454C3B505245463A2B35353531323334350D0A454E443A5643
4152
440D0A" PROPERTY="" ID="2">
</SMS>
</MESSAGE>

UDH UDH is used for sending binary messages. For business card message the value should be 4.
Text It must contain Hex-converted PDU for vCard. It will cost you approx. 1 to 5 credits according to
the length of SMS.
g. SMS-MT Example for Sending WAP Push
Here is a complete example for a valid SMS-MT request using ValueFirst XML API.

<MESSAGE>
TEXT="546869732069732073616D706C652056616C75654669727374205741
50204D65737361676520536572766963652E;7777772E7666697273742E636F
6D" PROPERTY="" ID="1">
<ADDRESS FROM="VFIRST" TO="919812345678" SEQ="1" TAG="some
data" />
</SMS>
</MESSAGE>
Ta Description
g
U UDH is used for sending binary messages. For WAP Push message the value
D
N should be 5.
H
a
C Extended type of messages. For text message the value should be 3.
od
m
in
e
g www.vfirst.com
12
Te Message Text must be in Hex characters for WAP Push and it can contain
xt message text along with URL.
it must follow format

<Hex-converted text>;<Hex-converted URL without „http://‟>
if there is no message text with WAP Push URL then it must be
;<Hex-converted URL>
Each WAP Push message processing consumes 1 credit. If Hex-encoded Title

and URL are containing less than 210 characters, the credits multiplier changes
according to Hex-encoded Title and URL containing characters in multiplication
of 210.
For Example:
<MESSAGE>
<USER USERNAME="test" PASSWORD="test"/>
TEXT="56616c75656669727374;7777772e7666697273742e636f"
PROPERTY="" ID="1">
<ADDRESS FROM=“VFIRST” TO="9198XXXXXXXXXX"
SEQ="3" TAG="some client side random data" />
</SMS>
</MESSAGE>
Shall sent a WAP Push with text “ValueFirst” and URL www.vfirst.com to
specified mobile number.
h. SMS-MT Example of Sending Unicode Text Messages

Here are examples for a valid SMS-MT request using ValueFirst XML API.
a. <?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE MESSAGE SYSTEM "http://127.0.0.1/psms/dtd/messagev12.dtd" >
<MESSAGE VER="1.2">
<USER USERNAME="mycompany" PASSWORD="somepassword"/>
<SMS UDH="0" CODING="2" TEXT=" 093809020938094D091509430924 "
PROPERTY="0" ID="1">
<ADDRESS FROM=“VFIRST” TO="919812345678" SEQ="1" TAG="" />
<ADDRESS FROM=“VFIRST” TO="wrong_addr" SEQ="2" />
</SMS>
</MESSAGE>
Tag Description
Name
UDH For text message the value should be 0.
Coding Extended type of messages. For Unicode text message the value should be
Text Message
2. text must be in Hex of Unicode characters. Message text can be up
70 characters for Unicode messages. API allows user to send Message Text
of more than 70 characters.
www.vfirst.com
13
i. SMS-MT Example of Sending Message on Specified Port

This feature facilitates to send messages to specified port number of mobile phone device of
recipients. The under mentioned code consists of UDH parameter that stores port number in
typical Hexadecimal format.

<!DOCTYPE MESSAGE SYSTEM "http://127.0.0.1/psms/dtd/messagev12.dtd" >
<MESSAGE VER="1.2">
<USER USERNAME="mycompany" PASSWORD="somepassword"/>
<SMS UDH="0605040B840B84" CODING="3" TEXT="
080603CBAF88030E6A00C505850686078701464703312E30000101494A4648
036369643A3035305F6161634074616D696C2E6D757369632E697466696E69
74792E6E65740001014B4CC31070DF131A9948B12A0C22883377AC7CF40101
014D0E010101" PROPERTY="0" ID="1">
<ADDRESS FROM=“VFIRST” TO="919812345678" SEQ="1" TAG="" />
</SMS>
</MESSAGE>
Following table describes the usage of attributes and their values used in the above code:
Tag Description
UDH
Nam The UDH attribute must contain hexadecimal string as value. The length of hexadecimal
e string must be 14 or 24 alphanumeric characters long that also store the port number of
mobile phone device and where message is to be delivered.
Codin For port based messaging, “coding” attribute must store the value 3.
g
Text This attribute contains message content in the Hex or simple textual format.
SMS-SR Status Request Service

Status request API supports multiple message status per transaction. A simple example of
SMS-SR
is shown below:

<!DOCTYPE STATUSREQUEST SYSTEM
"http://127.0.0.1:80/psms/dtd/requeststatusv12.dtd">
<STATUSREQUEST>
<GUID GUID="kb4jc5342283a5f461209c6m6h--TESTUSER">
<STATUS SEQ="1" />
<STATUS SEQ="2" />
</GUID>
<GUID GUID="kb4jc5407304a5f461209c1x89--TESTUSER" />
</STATUSREQUEST>
The elements of the above XML example are explained in the following table.
Ta Description
g
GU A globally unique message ID that is generated for each <SMS> tag. This
Na
ID GUID is generated when ValueFirst Pace receives a new session.
me
Se The address (Mobile No.) SEQ ID whose status needs to be extracted. If no
q Status tag is sent the API shall return status of all Sequences in the specified
Transaction
Us User name of the sender of the message
er
Na
me
www.vfirst.com
14
Pa User password
ss
When the server receives SMS-SR query, it will respond with following XML:
wo
rd
<STATUSACK>
<GUID GUID="kb4jc5441583a5f461209hmvdf--TESTUSER">
<STATUS SEQ="1" ERR="8448" DONEDATE="2017-05-10 10:06:31"
REASONCODE="000">
REASONCODE="000" >
</GUID>
<GUID GUID="kb4jc5540144a5f461209het83--TESTUSER">
REASONCODE="000"/>
REASONCODE="009"/>
</GUID>
</STATUSACK>
The elements of the above XML are explained in the following table.
GUID A globally unique Message ID that is generated for each <SMS> tag. This
GUID is generated when ValueFirst Pace receives a new session.
SEQ The address (Mobile No.) SEQ ID (Client side value) whose status was
queried
DONEDATE The time when the new status was received. The new status could be
either success or failure, the field is in Standard ANSI format, i.e. YYYY- MM-DD HH:MM:SS
ERR Error / Message Status Code, if no standard error occurred, the ERR shall
be either one of the following value.
8448: Message was successfully delivered on DONEDATE
8449: Message reportedly failed on DONEDATE
REASONCODE In case of failure (8449) service returns reason code for message failure.
This is a value provided by SMSC and differs for each SMSC route. Customers are required
to contact ValueFirst to discuss various reason code and corresponding meaning for different
country.
Reason-code is an optional variable.
Note: If a promotional message delivery is tried on a user handset whose number exists in
NCPR database, the messages will fail immediately with error-code 009. ValueFirst will not
charge any credits for such events.
DLR URL
Users can pass DLR URL along with the SMS packet on which ValueFirst API will send the
DLR as soon as it is received at ValueFirst’s end. Below is the sample XML format for passing
DLR URL
Below is a sample XML with DLR URL tag:

<MESSAGE>
< DLR URL="http://myurl.domain/recvdlr?dlrparamerters"
<SMS UDH="0" CODING="1" TEXT="hey this is a real test" PROPERTY="" ID="1">
<ADDRESS FROM="ALERTS" TO="919812345678" SEQ="2" />
</SMS>
</MESSAGE>
Optionally this URL can be configured against a username from backend and this tag will not
be required to be sent along with every packet.
Below table depicts the parameter values to be passed to get corresponding values
www.vfirst.com
15
Sample Parameter names Values Sample Response

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
kh5ng551155213b161011bme3vTESTUS
CLIENT_GUID %5 ER
CLIENT_SEQ_NUMBE
R %6 Value as Submitted
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 Delivered
Additional Parameter 1 %21 Value as Submitted
Note:
In the requested DLR URL, the attributes used in the URL can be named accordingly but
values used corresponding to used attributes or variables are case sensitive.
SMS-CR Service
SMS-CR Example of Credit Request

Credit request API is used to check credit status. A simple example of SMS-CR is shown
below:
<!DOCTYPE REQUESTCREDIT SYSTEM "http://127.0.0.1:80/psms/dtd/requestcredit.dtd">
<REQUESTCREDIT USERNAME="" PASSWORD="">
</REQUESTCREDIT>
The elements of the above XML are explained in the following table:
Tag Description
Nam
Use User name of the sender of
e
rNa
Pas the message
User password
me
sw
ord
SMS-CR Example of Credit Request Response

When the server receives SMS-CR query, the server shall respond with following XML:
<SMS-Credit User="test">
<Credit Limit="100000000" Used="1522932.00"/>
</SMS-Credit>
The elements of the above XML are explained in the following table:
www.vfirst.com
16
Cre Total
dit
Use credits
Credits
Limi
d assigned.
used.
t
Scheduling Framework
Scheduling Support in ValueFirst XML API

The ValueFirst API now supports scheduling messages for delivering them in future. The
scheduling framework following features:
- Scheduling a group of message for future delivery
- Checking status of schedule messages
- Modify the schedule of messages not sent
- Delete unprocessed messages
- Listing entire scheduled message messages on a precondition
Setting Up Messages for Future Delivery

Message can be scheduled by specifying a send-on time while making a MT Request:
<MESSAGE>
<SMS UDH="0" CODING="1" TEXT="This message will be delivered in future!"
SEND_ON="2007-10-15 20:10:10 +0530">
</SMS>
</MESSAGE>
The SEND_ON attribute is used to specify a delivery in future

SMS
SEND_ON Specify the time when the message(s) needs to be
delivered.
The API behaves methodically to the query and responds with GUID for the above SMS
group. The
GUID can later be used to perform additional actions on scheduled messages.
The future scheduling can only be done up to the contract expiry date or 1 year whichever
comes first.
Deleting Scheduled Message

A previously scheduled message can be deleted using following XML Post

<!DOCTYPE SCHEDULE SYSTEM "http://127.0.0.1:80/psms/dtd/schedule_q.dtd">
<SCHEDULE ACTION="DELETE">
<GUID GUID="kb4jc2347068a5f46120924uqy--TESTUSER" MODIFIER=""/>
</ SCHEDULE >
Tag Description
Name
www.vfirst.com
17
SCHEDULE
ACTION Specify the type of action, for deleting the schedule use DELETE
USER action
USERNA Username for authentication
ME
PASSWO Password for authentication
RD
GUID
GUID Specify the SMS GUID against which the message was
MODIFIE scheduled
Specify additional parameter that applies to particular GUID. For
R Delete Schedule the Value of this field should be zero
For above query the system will respond with following XML
<SCHEDULE_RESPONSEERROR="0">
<GUID GUID="kb4jc3805296a5f461209jjt6l--TESTUSER" ERROR=""/>
</SCHEDULE_RESPONSE>

SCHEDULE_RESPONSE
ERROR Specify a critical error. If the value is nonzero the system is
not able to process the XML
GUID
ERROR scheduled
Specify the error which was encountered while performing
action for the specified GUID.
Kindly see Error Codes for more information
Update Scheduled Message
A previously scheduled message can be updated using following XML Post. Please note only
new date time can be specified. Other option like change of receiver’s numbers is not
supported.
<!DOCTYPE SCHEDULE SYSTEM "http://127.0.0.1:80/psms/dtd/schedule_q.dtd">
<SCHEDULEACTION="UPDATE">
<GUID GUID="kb4jc3847730a5f461209zfosl--TESTUSER" MODIFIER="2009-10-24
20:10:00 GMT+5:30"/>
</SCHEDULE>

SCHEDULE
ACTION Specify the type of action, for changing date time UPDATE action
should be used
USER
USERNAME Username for authentication
PASSWORD Password for authentication
GUID
scheduled
www.vfirst.com
18
MODIFIER Specify additional parameter that applies to GUID. The field must
contain the new date time that need to be setup.
<SCHEDULE_RESPONSEERROR="0">
<GUID GUID="kb4jc3922236a5f461209p7vmd--TESTUSER" ERROR=""/>
</SCHEDULE_RESPONSE>

SCHEDULE_RESPONSE
ERROR Specify a critical error. If the Value is nonzero the system is not
able to process the XML
GUID
scheduled
ERROR Specify the error which was encountered while performing action
for the specified GUID. Kindly see Error Codes for more
information
List Scheduled Message

A search query can be executed to determine message-groups (SMS) status. To make such
search the following query should be executed:

<!DOCTYPE SCHEDULE_LIST SYSTEM "http://127.0.0.1:80/psms/dtd/schedule_sq.dtd">
<SCHEDULE_LIST>
<CONDITION STATUS_TYPE="[PROCESSED|PENDING|ERROR]|SCHEDULED|GUID"
START_DATE="2009-10-24 20:10:00 GMT+5:30" END_DATE="2009-10-25 20:10:00
GMT+5:30" GUID="" />
</SCHEDULE_LIST>

SCHEDULE
ACTION Specify the type of action, for listing messages the LIST action should be used
USER
USERNAME Username for authentication
PASSWORD Password for authentication
CONDITION
STATUS_TYPE Specify the type of messages that need to be list: PROCESSED: List the SMS objects
(message-groups) that have been successfully processed. PENDING: List the SMS
objects (message-groups) that will be processed in future. ERROR: List the SMS
objects (message-groups) that could not be processed due to some error intermediately.
While receiving such messages there was no error, however when the system tried to
send the SMS group, it failed with critical error. SCHEDULED: This STATUS_TYPE
gets SMS that were scheduled between start date and end date. GUID: Use this
condition type to get information about specific GUID only.
START_DATE Specify the start date of execution for scheduled messages for
PROCESSED/PENDING/ERROR while start date of setup of schedule for
SCHEDULED messages
www.vfirst.com
19
END_DATE Specify the end date of execution for scheduled messages for
PROCESSED/PENDING/ERROR while end date of setup of schedule for SCHEDULED
messages
GUID Specify a GUID for which details are requested. When GUID take is used
START_DATE, END_DATE become irrelevant.
<SCHEDULE_LIST_RESPONSEERROR=”0”>
<GUID GUID=”kb4jc3956390a5f461209iokjw—TESTUSER” ERROR=””
CREDIT_USED=”” ADDRESS=”” SCHEDULED_ON=”” EXECUTED_ON=””/>
</SCHEDULE_LIST_RESPONSE>

SCHEDULE_RESPONSE
ERROR Specify a critical error. If the GUID status is ERROR, which means system tried to
execute the schedule SMS group but failed to do so.
GUID
GUID Specify the SMS GUID against which the message was scheduled.
ERROR Specify the error which was encountered while performing action for the specified
GUID. Kindly see Error Codes for more information.
CREDIT_USED The number of credits that are allocated this message group.
ADDRESS The number of addresses in this SMS Group.
SCHEDULED_ON Specify the date-time when the SMS group was scheduled.
EXECUTE_ON Specify the date-time when the SMS group is scheduled to execute.
Standard Error Codes
All errors that may come across in ValueFirst XML API are listed below.
Error Code Description

General
52992 Username / Password incorrect
57089 Contract expired
57090 User credit expired
57091 User disabled
65280 Service is temporarily unavailable
65535 The specified message does not conform to DTD
0 SMS submitted success NO Error (Not returned in ValueFirst
XML API )
Message Post
28673 Destination number not numeric
28674 Destination number empty
28675 Sender address empty
28676 Template mismatch
28677 UDH is invalid / SPAM message
28678 Coding is invalid
28679 SMS text is empty
28680 Invalid sender ID
28681 Invalid message, Duplicate message, Submit failed
28682 Invalid Receiver ID (Will validate Indian mobile numbers only.)
www.vfirst.com
20
28683 Invalid Date time for message Schedule (If the date specified in
message post for schedule delivery is less than current date or more
than expiry date or more than 1 year)
Status Request
8448 Message delivered successfully
8449 Message failed
8450 Message ID is invalid
Scheduler Related
13568 Command completed successfully
13569 Cannot update/delete schedule since it has already been processed
13570 Cannot update schedule since the new date-time parameter is incorrect
13571 Invalid SMS ID/GUID

13572 Invalid Status type for schedule search query. The status
strings can be “PROCESSED”, “PENDING” and “ERROR”
13573 Invalid date time parameter for schedule search query
13574 Invalid GUID for GUID search query
13575 Invalid command action
Note: There isn’t any status returned in case message is in waiting status. Therefore, there
would not be any status tag in XML in case of waiting status.
“Reason for failure” codes are SMSC specific and hence are not covered here.
Regulatory Implementation and Impact

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:
http://www.trai.gov.in/WriteReadData/trai/upload/Directives/131/direction10dec08.pdf
www.vfirst.com
21
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.
The details of operator codes are as below:
The details of circle codes are as below:
www.vfirst.com
22
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 they have not given explicit
permission to receive so.
www.vfirst.com

XML Api 1.5.1.05

Uploaded by

Copyright:

Available Formats

XML Api 1.5.1.05

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

XML Api 1.5.1.05

Uploaded by

Copyright:

Available Formats

XML API 1.5.1.

Guidelines for Sending Messages

Receiver Phone Number

Character Set Support

• < is encoded into %3C

http://api.myvfirst.com/psms/servlet/psms.Eservice2?data=<?xml version="1.0" encoding="ISO-8859-

For URL encoding

Accessing Server Services

XML Data Parameter Action Psarameter

Figure 1 Page for testing various API functions - http://api.myvfirst.com/psms/

a. SMS-MT Example of Sending Text Messages

<ADDRESS FROM="ALERTS" TO="919812345678" SEQ="2" />

The following table describes the different elements of a SMS-MT request:

Tag Name Description

b. SMS-MT Example of Response

The following example shows sample response of ValueFirst XML API.

Alternatively, the following response may also come:

The following table describes different elements of SMS-MT Response:

Tag Name Description

<?xml version="1.0" encoding="ISO-8859-1"?>

Note - Additional parameter names will have to be configured at

d. SMS-MT Example of Sending Picture Messages

<?xml version="1.0" encoding="ISO-8859-1"?>

The following table describes the different elements of a SMS-MT request.

e. SMS-MT Example of Sending Ringtones

<?xml version="1.0" encoding="ISO-8859-1"?>

The following table describes the different elements of a SMS-MT request.

f. SMS-MT Example of Sending vCard (Business Card)

<?xml version="1.0" encoding="ISO-8859-1"?>

The following table describes the different elements of a SMS-MT request.

g. SMS-MT Example for Sending WAP Push

<?xml version="1.0" encoding="ISO-8859-1"?>

it must follow format

Each WAP Push message processing consumes 1 credit. If Hex-encoded Title

h. SMS-MT Example of Sending Unicode Text Messages

The following table describes the different elements of a SMS-MT request:

i. SMS-MT Example of Sending Message on Specified Port

<?xml version="1.0" encoding="ISO-8859-1"?>

SMS-SR Status Request Service

<?xml version="1.0" encoding="ISO-8859-1"?>

Below is a sample XML with DLR URL tag:

Sample Parameter names Values Sample Response

SMS-CR Example of Credit Request

SMS-CR Example of Credit Request Response

Scheduling Support in ValueFirst XML API

Setting Up Messages for Future Delivery

The SEND_ON attribute is used to specify a delivery in future

Deleting Scheduled Message

<?xml version="1.0" encoding="ISO-8859-1"?>

The following table describes the different elements of a SMS-MT request.

Tag Name Description

Update Scheduled Message

The following table describes the different elements of a SMS-MT request.

Tag Name Description

The following table describes the different elements of a SMS-MT request.

Tag Name Description

List Scheduled Message

<?xml version="1.0" encoding="ISO-8859-1"?>

The following table describes the different elements of a SMS-MT request.