Post on 27-Dec-2015
description
ValueFirst Pace
XML API Developers Guide
Version 1.5
©ValueFirst Messaging, 2007-2009 The information provided in this document is classified, and cannot be shared with any third
party without prior permission from ValueFirst
Document Version 1.5.1.02 Date: 2010-JUL-14
ValueFirst Messaging Private Limited B-17, Institutional Area Sector 32
Gurgaon 122 001 Haryana India
Version History
Date Version Description Author
2004-11-01 .1.0 Document was created Shantanu S. Chauhan
2005-01-04 .2.0 API MO Added Shantanu S. Chauhan
2005-02-20 .3.0 New Example Added Gurmukh Singh Sidhu
2005-04-10 .4.0 Ring tone, Picture messages and VCard
support added
Namita Agnihotri
2006-05-30 .5.0 Support for WAP Push, Flash Message Added Namita Agnihotri
2006-06-12 .5.1 General Bug fix Shantanu S. Chauhan
2006-11-22 .5.2 Change of Server Address Shantanu S. Chauhan
2007-01-22 .6.0 Document was edited Gayathri E.
2007-02-19 .7.0 Document was edited Namita Agnihotri
2008-01-08 1.5 Major Change in API, related to DLR, Validity and Reason code
Shantanu S Chauhan
2009-03-25 1.5.0.1 Update of document based on new
Regulatory compliance Implementation
Shantanu S Chauhan
2009-03-25 1.5.1 Added Specification of Scheduler Framework Shantanu S Chauhan
2009-04-22 1.5.1.01 Bug fixes in Scheduler Framework Shantanu S Chauhan
2010-07-14 1.5.1.02 Added feature to send message on specified
port of mobile phone device
Valuefirst Technical Team
Table of Contents Version 1.5 ....................................................................................................................... 1
Table of Contents ........................................................................................................... 3
ValueFirst Pace ............................................................................................................... 7
ValueFirst Pace Client API Version 1.5 .............................................................................. 7
Guidelines for Sending Messages ................................................................................. 10
Receiver Phone Number ................................................................................................ 10 Identifying Number Series ............................................................................................. 10 Sender Phone Number .................................................................................................. 11 Using Mobile Number as Sender ..................................................................................... 12
ENCODING PROCEDURE .............................................................................................................................12
Accessing Server Services ............................................................................................ 14
SMS-MT Service ............................................................................................................ 17
a. SMS-MT Example of Sending Text Messages ............................................................... 17 b. SMS-MT Example of Response ................................................................................... 18 c. SMS-MT Example of Sending Picture Messages ........................................................... 19 d. SMS-MT Example of Sending Ring tones ..................................................................... 20 e. SMS-MT Example of Sending vCard (Business Card) .................................................... 22 f. SMS-MT Example for Sending WAP Push ..................................................................... 22 g.SMS-MT Example of Sending Unicode Text Messages ................................................... 23 h. SMS-MT Example of Sending Message on Specified Port .............................................. 24
SMS-SR Status Request Service ................................................................................... 25
SMS-CR Service ............................................................................................................ 27
SMS-CR Example of Credit Request ............................................................................. 27
SMS-CR Example of Credit Request Response ............................................................. 27
Mobile Originated (MO) Messages (Ver.1.0) ................................................................ 28
Data Format ................................................................................................................. 28 MO-SMS response ......................................................................................................... 29
Scheduling Framework ................................................................................................. 30
Scheduling Support in ValueFirst XML API ....................................................................... 30 Setting up Messages for Future Delivery ......................................................................... 30 Deleting Scheduled Message .......................................................................................... 30 Update Scheduled Message ........................................................................................... 31 List Scheduled Message ................................................................................................. 32
Standard Error Code ..................................................................................................... 34
Data Type Definitions ................................................................................................... 37
SMS-MT Data Type Definition ........................................................................................ 37
DESC CDATA #IMPLIED>............................................................................................ 38 SMS-SR Status Request Data Type Definition .................................................................. 38 SMS-CR Data Type Definition ......................................................................................... 38 SMS-MO Data Type Definition ........................................................................................ 39 SMS-SCHEDULE Data Type Definition ............................................................................. 39 SMS-SCHEDULE-LIST Data Type Definition ..................................................................... 40
Regulatory Implementation and Impact ..................................................................... 41
Sender ID Regulation .................................................................................................... 41 National Do Not Call Registry (N DNC) ............................................................................ 43
This page has been left intentionally blank
7
ValueFirst Pace
ValueFirst Messaging Server (hereinafter referred to as ValueFirst Pace) provides an open HTTP and XML standards based API for integrating SMS capabilities into any application or an
enterprise system.
ValueFirst Pace is a store and forward mechanism using a middleware deployed on Internet for
sending and receiving SMS through the API endpoint(s) to the clients.
ValueFirst Pace provides different endpoints for bulk messaging (server to server) and for client application based systems.
ValueFirst Pace Client API Version 1.5
ValueFirst Pace Client API version is specially designed for sending bulk messages through server-to-server communication. This API is designed to send up to 5000 messages in a single
transaction. This API is available in XML-based HTTP / HTTPS post format only.
ValueFirst Pace Client API version provides single authentication for multiple messages and
multiple target numbers for a single message. The endpoint for this API is based on Message Queue architecture that provides high message throughput.
This page has been left intentionally blank
Guidelines for Sending Messages The following guidelines must be followed while using XMLAPI for sending the messages.
Receiver Phone Number
For GSM, CDMA and international messaging, the Receiver Phone Number must start with
country code—e.g. 91 in case of an Indian number. No leading „0‟ or „+‟ are allowed—e.g., the number, 9812345678, should be specified as 919812345678. This means the number should
always be prefixed by 91 with no leading „+‟ or „0s‟.
Note: For sending message internationally the mobile number should be prefixed with the
appropriate country code. For all Indian numbers, the mobile number width must be 12 numbers. No special character like "-", "(",")" or anything similar is allowed in the phone number, e.g., 91-
9812345678 is disallowed.
Identifying Number Series
CDMA series worldwide do not support Alpha-numeric Sender. In India Reliance CDMA that starts
with 93, does not support Alpha-numeric Sender id. For Reliance a valid GSM mobile number
must be used. Various rules apply for identifying CDMA and GSM series worldwide. Kindly contact your operator
to know what series needs to be considered GSM and which one as CDMA. If it is a CDMA series you may have to use a valid numeric sender id for delivering messages.
In India mobile number series is starts with 91, 92, 93, 94, 96, 97, 98 and 99. TRAI has also
mandated to open 95 (previously used for local STD dialing) for mobile numbers.
The level 8 (number starting with 8x) will also be opened for mobile numbers. The possibility of having 11 digit mobile number has also been mandated.
11
Message Text Valuefirst XML API efficiently processes long messages consisting more than 160 characters,
treating them as a single message unit. Following table lists the set of multiple characters that can be used in the content of message.
@ Δ space 0 ¡ P ¿ p
£ _ ! 1 A Q A q
$ Φ “(double Quote) 2 B R B r
¥ Γ # 3 C S C s
è Λ ¤ 4 D T D t
é Ω % 5 E U e u
ù Π & 6 F V f v
ì Ψ „(Single Quote) 7 G W g w
ò Σ ( 8 H X h x
Ç Θ ) 9 I Y i y
Ξ * : J Z j Z
Ø + ; K Ä k ä
ø Æ < L Ö l ö
CR æ - = M Ñ m Ñ
Å ß , > N Ü n Ü
å É / ? O o §
Table 1 Characters that can be used in the message text.
Note: The characters marked red may not be supported on all mobile phones. Messages containing characters other than the ones listed above shall be rejected by the Operator SMSC.
Sender Phone Number
The Sender can be an alphanumeric text of maximum 8 characters in one or more words. However if it is a number only, then up to 16 characters are possible. The special characters like
", <, >, @, %, etc. cannot be used as Sender.
—Typical examples of wrong Sender‟s ID are
db@sky (invalid character in Sender) SomeInvalidSender (more than 11 characters)
—Typical examples of correct Sender‟s ID are
Mark Smith (space in name is allowed) Google (alphanumeric less than 8)
9198100123456 (less than 16 numeric characters)
As per DOT and TRAI guideline, all alphanumeric sender ids and short-code sender id will be
prefixed by Operator and circle code. This has been done to make NDNC Registry (National Do Not Call) compliance easier. The details of operator/circle and corresponding prefixes are at the
end of the document.
In case of Reliance CDMA network in India, a valid GSM number should be used as Sender Phone
Number.
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.
Using Mobile Number as Sender
To use a mobile number as Sender id, the user must submit documents related to ownership of the mobile number to ValueFirst. After verification ValueFirst will allow the sender ID to be used.
Please note in case a mobile number is not verified by ValueFirst the default sender id
91921559197 will replace the user‟s numeric sender id.
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 has to be replaced.
Code Replace with
#39 (single quote) &apos
#32 (space)  
#34 (double quote) "
> >
< <
#13 (Line feed) 
#10(form feed) 

#9(Tab) 	
Note: There are few characters like '[',']', “,” (MS word double quotes) etc that are not recognized as
standard GSM character set and hence should be dropped from message text. Refer Table 1 for information on characters supported by ValueFirst Server.
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) preceded by a „%‟ character, e.g., space is encoded into %20. * is encoded into %2A
# is encoded into %23
% is encoded into %25
13
< 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.myvaluefirst.com/psms/servlet/psms.Eservice2?data=<?xml version="1.0" encoding="ISO-8859-1"?><!DOCTYPE MESSAGE SYSTEM
"http://127.0.0.1/psms/dtd/message.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="ValueFirst" TO="91XXXXXXXXXX" SEQ="1" TAG="some clientside random data" /></SMS></MESSAGE>&action=send
After encoding
http://api.myvaluefirst.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/psms/dtd/message.dtd%22%20%3E%3CMESSAGE%3E%3CUSER%20USERNAME=%22test%22%20PASWORD=%22XXXXXX%22/%3E%3CSMS%20%20
UDH=%220%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%20d
ay!%22%20PROPERTY=%220%22%20ID=%221%22%3E%3CADDRESS%20FROM=%22ValueFirst%22%20TO=%2291XXXXXXXXXX%22%20SEQ=%221%22%20TAG=%22some%20clientside
%20random%20data%22%20/%3E%3C/SMS%3E%3C/MESSAGE%3E&action=send
Accessing Server Services
To access ValueFirst Pace, you need to register for a regular business account. For getting an account, contact ValueFirst at sales@vfirst.com
When you are registered, you will be provided a username and password. This authentication
information will be required for availing any of the services of ValueFirst Pace.
The end point for accessing ValueFirst Pace Client API version is
http://api.myvaluefirst.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 parameter
Sending message SMS-MT Version XML (URN
and HTML encoded)
send
Checking status SMS-SR Version XML (URN and HTML encoded)
status
Checking credits SMS-CR Version XML (URN and HTML encoded)
credits
Table 2 Values for „data‟ and „action‟ parameter.
The complete example for a valid SMS-MT and SMS-SR is given in Figure 1.
Figure 1 Page for testing various API functions - http://api.myvaluefirst.com/psms/.
15
This page has been left intentionally blank
17
SMS-MT Service ValueFirst Pace Client API version encompasses advance features specifically designed for sending bulk messages. With this version you do not have to send each message separately, up
to 5000 messages can be sent together in a single transaction. The API also supports multiple target numbers, therefore, if you need to send the same message to many people the message
will be sent in seconds in stead of minutes.
a. SMS-MT Example of Sending Text Messages
Here is a complete example for a valid SMS-MT request using ValueFirst Pace Client API version . <?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE MESSAGE SYSTEM "http://127.0.0.1/psms/dtd/message.dtd" > <MESSAGE>
<USER USERNAME="mycompany" PASSWORD="mycompany"/>
<SMS UDH="0" CODING="1" TEXT="hey this is a real test" PROPERTY="" ID="1" DLR="0" VALIDITY="0">
<ADDRESS FROM="9812345678" TO="919812345678" SEQ="1" TAG="some client side random data" />
<ADDRESS FROM="9812345678" TO="mycompany" SEQ="2" />
<ADDRESS FROM="VALUEFIRST" 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="9812345678" TO="919812345678" SEQ="1" /> <ADDRESS FROM="9812345678" TO="919812345678" SEQ="2" />
<ADDRESS FROM="VALUEFIRST" TO="919812345678" SEQ="3" />
<ADDRESS FROM="9812345678" TO="919812345678" SEQ="4" /> <ADDRESS FROM="VALUEFIRST" TO="919812345678" SEQ="5" />
<ADDRESS FROM="VALUEFIRST" TO="919812345678" SEQ="6" /> </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 describe 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 1 60 characters according to the length of SMS.
18
DLR Accepted Values are 0 and 1. When set to 0, the service shall not ask operator for delivery report. Default is 1. This parameter is optional
VALIDITY Set this validity of a message to current SMSC time plus minutes specified in Validity field. SMSC will not try to send the message after the validity have expired.
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. Timzone is difference wrt 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 conform 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 Pace Client API version . <?xml version="1.0" encoding="ISO-8859-1"?>
<MESSAGEACK>
<GUID GUID="3de2ec71-1c37-4999-a758-e354dd6fdb1d" SUBMITDATE="" ID="1">
<ERROR SEQ="2" CODE="28680" <!-- Receiver Address not numeric --> </GUID>
<GUID GUID="3de2ec71-1c37-4999-a758-s354dd6fdb1d" SUBMITDATE=""
ID="1"> </GUID> </MESSAGEACK>
Alternatively the following response may also come:
<?xml version="1.0" encoding="ISO-8859-1"?>
<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.
The following table describes the different elements of SMS-MT Response.
Tag Name Description
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.
19
ID Unique SMS ID sent by the customer. For each message a unique GUID is
generated. The Server sends the SMS ID so that the client application can map the GUID to the SMS ID provided by them.
ERROR Why error? To conserve bandwidth utilization ValueFirst Pace Client API version only
sends Sequence information of messages that has either some error or
were 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 „Mycompany‟ 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. SMS-MT Example of Sending Picture Messages
Here is a complete example for a valid SMS-MT request using ValueFirst Pace Client API version
<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE MESSAGE SYSTEM "http://127.0.0.1/psms/dtd/message.dtd" >
<MESSAGE> <USER USERNAME="mycompany" PASSWORD="mycompany"/>
<SMS UDH="1" CODING="3" TEXT="48656C6C6F;00481C01ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30
ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3
ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30
ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30c
cf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3"
PROPERTY="" ID="1"> <ADDRESS FROM="9812345678" TO="919812345678" SEQ="1" TAG="some
client side random data" /> <ADDRESS FROM="VALUEFIRST" TO="919812345678" SEQ="3" />
</SMS>
<SMS UDH="1" CODING="3" TEXT=";00481C01ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30c
cf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3
ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30
20
ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3
ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3ccf30ccf0f30ccf0f3" PROPERTY="" ID="2"> <ADDRESS FROM="VALUEFIRST" TO="919812345678" SEQ="3" />
<ADDRESS FROM="VALUEFIRST" TO="919812345678" SEQ="6" /> </SMS>
</MESSAGE>
The following table describes the different elements of a SMS-MT request.
Tag Name Description
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.
d. SMS-MT Example of Sending Ring tones
Here is a complete example for a valid SMS-MT request using ValueFirst Pace Client API version
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE MESSAGE SYSTEM "http://127.0.0.1/psms/dtd/message.dtd" >
<MESSAGE> <USER USERNAME="mycompany" PASSWORD="mycompany"/>
<SMS UDH="2" CODING="3" TEXT="024A3A594D8549951D84040018D9049161361561661861A61C6288B000
" PROPERTY="" ID="1"> <ADDRESS FROM="919812345678" TO="919812345678" SEQ="1" TAG="some
client side random data" />
<ADDRESS FROM="VALUEFIRST" TO="919812345678" SEQ="3" /> </SMS>
<SMS UDH="2" CODING="3" TEXT="024A3A594D8549951D84040018D9049161361561661861A61C6288B000
" PROPERTY="" ID="2">
<ADDRESS FROM="VALUEFIRST" TO="919812345678" SEQ="3" /> <ADDRESS FROM="VALUEFIRST" TO="919812345678" SEQ="6" />
</SMS> </MESSAGE>
The following table describes the different elements of a SMS-MT request.
Tag Name Description
21
UDH UDH is used for sending binary messages. For ring tone message the
value should be 2. Coding Extended type of messages. For text message the value should be 3.
Text It must contain Hex-converted PDU for ring tones.
22
e. SMS-MT Example of Sending vCard (Business Card)
Here is a complete example of a valid SMS-MT request using ValueFirst Pace Client API
version .
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE MESSAGE SYSTEM "http://127.0.0.1/psms/dtd/message.dtd" > <MESSAGE>
<USER USERNAME="mycompany" PASSWORD="mycompany"/>
<SMS UDH="4" CODING="3" TEXT=" 424547494E3A56434152440D0A56455253494F4E3A322E310D0A4E3A536D6974683B4D696B650D0A54454C3B505245463A2B35353531323334350D0A454E443A564341
52440D0A" PROPERTY="" ID="1">
<ADDRESS FROM="919812345678" TO="919812345678" SEQ="1"
TAG="some client side random data" />
<ADDRESS FROM="VALUEFIRST" TO="919812345678" SEQ="3" /> </SMS>
<SMS UDH="4" CODING="3" TEXT=” 424547494E3A56434152440D0A56455253494F4E3A322E310D0A4E3A536D6974683B4D696B650D0A54454C3B505245463A2B35353531323334350D0A454E443A564341
52440D0A" PROPERTY="" ID="2">
<ADDRESS FROM="VALUEFIRST" TO="919812345678" SEQ="3" /> <ADDRESS FROM="VALUEFIRST" TO="919812345678" SEQ="6" />
</SMS> </MESSAGE>
The following table describes the different elements of a SMS-MT request.
Tag Name Description
UDH UDH is used for sending binary messages. For Business card message the value should be 4.
Coding Extended type of messages. For text message the value should be 3.
Text It must contain Hex-converted PDU for vCard. It will cost you approx. 1 to 5 credits according to the length of SMS.
f. SMS-MT Example for Sending WAP Push
Here is a complete example for a valid SMS-MT request using ValueFirst Pace Client API
version .
<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE MESSAGE SYSTEM "http://127.0.0.1/psms/dtd/message.dtd" >
<MESSAGE>
<USER USERNAME="mycompany" PASSWORD="mycompany"/> <SMS UDH="5" CODING="3"
TEXT="546869732069732073616D706C652056616C7565466972737420574
23
150204D65737361676520536572766963652E;7777772E7666697273742E63
6F6D" PROPERTY="" ID="1"> <ADDRESS FROM="919812345678" TO="919812345678" SEQ="1"
TAG="some client side random data" /> <ADDRESS FROM="VALUEFIRST" TO="919812345678" SEQ="3" />
</SMS> </MESSAGE>
The following table describes the different elements of a SMS-MT request:
Tag Name Description
UDH UDH is used for sending binary messages. For WAP Push message the
value should be 5. Coding Extended type of messages. For text message the value should be 3.
Text Message Text must be in Hex characters for WAP Push and it can contain 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 takes 3 credits.
Example: <?xml version="1.0" encoding="ISO-8859-1"?>
<MESSAGE> <USER USERNAME="test" PASSWORD="test"/>
<SMS UDH="5" CODING="3" TEXT="56616c75656669727374;7777772e7666697273742e636f"
PROPERTY="" ID="1">
<ADDRESS FROM="VALUEFIRST" 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.
g.SMS-MT Example of Sending Unicode Text Messages
Here are examples for a valid SMS-MT request using ValueFirst Pace Client API version 1.2.
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="9812345678" TO="919812345678" SEQ="1" TAG="" />
<ADDRESS FROM="9812345678" TO="wrong_addr" SEQ="2" />
<ADDRESS FROM="VALUEFIRST" TO="919812345678" SEQ="3" /> </SMS>
24
</MESSAGE>
The following table describes the different elements of a SMS-MT request:
Tag Name Description
UDH For Text message the value should be 0. Coding Extended type of messages. For Unicode text message the value should
be 2. Text Message 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.
h. 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.
<?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="0605040B840B84" CODING="3"
TEXT="080603CBAF88030E6A00C505850686078701464703312E30000101494A4648
036369643A3035305F6161634074616D696C2E6D757369632E697466696E6974792E6E65740001014B4CC31070DF131A9948B12A0C22883377AC7CF40101014D0E0101
01" PROPERTY="0" ID="1"> <ADDRESS FROM="9198XXXXXX91" TO="9198XXXXXX93" SEQ="1" TAG=""/>
</SMS>
</MESSAGE>
Following table describes the usage of attributes and their values used in the above code:
Tag Name Description
UDH The UDH attribute must contain hexadecimal string as value. The length of
hexadecimal 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.
Coding For port based messaging, “coding” attribute must store the value 3.
Text This attribute contains message content in the Hex or simple textual format.
25
SMS-SR Status Request Service Status request API supports multiple message status per transaction. A simple example of SMS-
SR is shown below: <?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE STATUSREQUEST SYSTEM "http://127.0.0.1/psms/dtd/requeststatus.dtd" >
<STATUSREQUEST> <USER USERNAME="mycompany" PASSWORD="mycompany"/>
<GUID GUID="3de2ec71-1c37-4999-a758-e354dd6fdb1d">
<STATUS SEQ="1" /> <STATUS SEQ="2" />
</GUID> <GUID GUID="3de2ec71-1c37-4999-a758-s354dd6fdb1d" />
</STATUSREQUEST>
The elements of the above XML example are explained in the following table.
Tag Name Description
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 whose status needs to be extracted. If no Status tag is sent the API shall return status of all Sequences in the
specified Transaction
UserName User name of the sender of the message Password User password
When the server receives SMS-SR query, it will respond with following XML:
<?xml version="1.0" encoding="ISO-8859-1"?>
<STATUSACK> <GUID GUID="3de2ec71-1c37-4999-a758-e354dd6fdb1d">
<STATUS SEQ="1" ERR="50" DONEDATE="2004:10:13 12:10:12"/> <!--Message delivered successfully-->
<STATUS SEQ="2" ERR="8448" DONEDATE="0"/> <!--Invalid Message ID--> </GUID>
<GUID GUID="3de2ec71-1c37-4999-a758-s354dd6fdb1d">
<STATUS SEQ="1" ERR="8448" DONEDATE="2004:10:13 12:10:12" REASONCODE=""/> <!--Message delivered successfully-->
<STATUS SEQ="2" ERR="8448" DONEDATE="2004:10:13 12:10:12" REASONCODE=""/> <!--Message delivered successfully-->
< STATUS SEQ="4" ERR="8449" DONEDATE="2004:10:13 12:10:12"
REASONCODE="1"/> <!—Message Delivery failed, see Reason Code--> <STATUS SEQ="5" ERR="8448" DONEDATE="2004:10:13 12:10:12"
REASONCODE=""/> <!--Message delivered successfully--> <STATUS SEQ="6" ERR="8448" DONEDATE="2004:10:13 12:10:12"
REASONCODE=""/> <!--Message delivered successfully--> </GUID>
</STATUSACK>
26
The elements of the above XML are explained in the following table.
Tag Name Description
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 message delivery is tried on a user handset whose number
exists in DNC, the messages will fail immediately with error-code 999.
ValueFirst will not charge any credits for such events.
27
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:
<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE REQUESTCREDIT SYSTEM "http://127.0.0.1/psms/dtd/
requestcredit.dtd" >
<REQUESTCREDIT USERNAME="" PASSWORD=""> </REQUESTCREDIT>
The elements of the above XML are explained in the following table:
Tag Name Description UserName User name of the sender of the message
Password User password
SMS-CR Example of Credit Request Response When the server receive SMS-CR query, the server shall respond with following XML:
<?xml version="1.0" encoding="ISO-8859-1"?> <SMS-Credit User="test">
<Credit Limit="100000000" Used="1522932.00"/> </SMS-Credit>
The elements of the above XML are explained in the following table:
Tag Name Description Credit Limit Total credits assigned.
Used Credits used.
28
Mobile Originated (MO) Messages (Ver.1.0)
Data Format The service endpoint for retrieving the inbound SMS messages is http://www.myvaluefirst.com/psms/servlet/psms.MOService1_1 that is the MO-SMS service.
For testing the MO-SMS service can also be accessed through the URL
http://www.myvaluefirst.com/psms/getXML1_1.jsp (Figure 2).
Figure 2 http://www.myvaluefirst.com/psms/getXML.jsp
In the response the message format, in which the inbound numbers are received, is as follows:
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE Messaging SYSTEM "http://127.0.0.1/dtd/Request.dtd" > <REQUEST>
<USER>testuser</USER> <PASSWORD>test123</PASSWORD>
<INITIAL>0</INITIAL>
<SIZE>10</SIZE> <CONDITION TONUMBER="919811212345" FROMNUMBER="*"
FROMDATE="" TODATE="" /> <KEYWORD></KEYWORD>
<FLAG> </FLAG>
</REQUEST>
29
Note: You need to specify a valid value for keyword.
MO-SMS response
When ValueFirst Pace receives a request for downloading messages, it sends back response in the following format:
<?xml version=1.0 encoding=ISO-8859-1?> <Messaging>
<TO NUMBER=9811112345> <SMS>
<From>9811912182</From>
< MSG >Sample Message Text1</MSG > </SMS>
<SMS> <From>9811912182</From>
< MSG >Sample Message Text2</MSG >
</SMS> </To>
</Messaging>
30
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: <?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE MESSAGE SYSTEM "http://127.0.0.1/psms/dtd/message.dtd" > <MESSAGE>
<USER USERNAME="mycompany" PASSWORD="mycompany"/>
<SMS UDH="0" CODING="1" TEXT="This message will be delivered in future!" SEND_ON="2007-10-15 20:10:10 +0530">
<ADDRESS FROM="VALUEFIRST" TO="919812345678" SEQ="1" />
</SMS> </MESSAGE> The SEND_ON attribute is used to specify a delivery in future
Tag Name Description
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 <?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE SCHEDULE SYSTEM "http://127.0.0.1/psms/dtd/schedule_q.dtd" > <SCHEDULE ACTION="DELETE">
<USER USERNAME="mycompany" PASSWORD="mycompany"/>
<GUID GUID="3de2ec71-1c37-4999-a758-e354dd6fdb1d" MODIFIER=""/> </ SCHEDULE >
The following table describes the different elements of a SMS-MT request.
Tag Name Description SCHEDULE ACTION Specify the type of action, for deleting the schedule use DELETE action USER USERNAME Username for authentication PASSWORD Password for authentication GUID
31
GUID Specify the SMS GUID against which the message was scheduled MODIFIER Specify additional parameter that applies to particular GUID. For Delete Schedule
the Value of this field should be zero
For above query the system will respond with following XML
<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE SCHEDULE_RESPONSE SYSTEM
"http://127.0.0.1/psms/dtd/schedule_r.dtd" > <SCHEDULE_RESPONSE ERROR="0">
<GUID GUID="3de2ec71-1c37-4999-a758-e354dd6fdb1d" ERROR=""/> </SCHEDULE_RESPONSE> The following table describes the different elements of a SMS-MT request.
Tag Name Description
SCHEDULE_RESPONSE ERROR Specify a critical error. If the Value is nonzero the system is not able to
process the XML 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
Update Scheduled Message A previously scheduled message can be updated using following XML Post. Please note only new
datetime can be specified. Other option like change of receiver‟s numbers is not supported.
<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE SCHEDULE SYSTEM "http://127.0.0.1/psms/dtd/schedule_q.dtd" > <SCHEDULE ACTION="UPDATE">
<USER USERNAME="mycompany" PASSWORD="mycompany"/> <GUID GUID="3de2ec71-1c37-4999-a758-e354dd6fdb1d" MODIFIER="2009-
10-24 20:10:00 GMT+5:30"/> </SCHEDULE> The following table describes the different elements of a SMS-MT request.
Tag Name Description
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 GUID Specify the SMS guid against which the message was scheduled
MODIFIER Specify additional parameter that applies to GUID. The field must contain the new datetime that need to be setup.
For above query the system will respond with following XML <?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE SCHEDULE_RESPONSE SYSTEM
"http://127.0.0.1/psms/dtd/schedule_r.dtd" > <SCHEDULE_RESPONSE ERROR="0">
<GUID GUID="3de2ec71-1c37-4999-a758-e354dd6fdb1d" ERROR=""/> </SCHEDULE_RESPONSE> The following table describes the different elements of a SMS-MT request.
32
Tag Name Description
SCHEDULE_RESPONSE ERROR Specify a critical error. If the Value is nonzero the system is not able to
process the XML 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
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:
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE SCHEDULE_LIST SYSTEM "http://127.0.0.1/psms/dtd/schedule_sq.dtd" > <SCHEDULE_LIST>
<USER USERNAME="mycompany" PASSWORD="mycompany"/> <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> The following table describes the different elements of a SMS-MT request.
Tag Name Description 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 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.
For above query the system will respond with following XML
<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE SCHEDULE_LIST_RESPONSE SYSTEM
"http://127.0.0.1/psms/dtd/schedule_sr.dtd" >
33
<SCHEDULE_LIST_RESPONSE ERROR="0">
<GUID GUID="3de2ec71-1c37-4999-a758-e354dd6fdb1d" ERROR=""
CREDIT_USED="" ADDRESS="" SCHEDULED_ON="" EXECUTED_ON=""/> </SCHEDULE_LIST_RESPONSE> The following table describes the different elements of a SMS-MT request.
Tag Name Description
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.
34
Standard Error Code ValueFirst Pace Client API version uses Bit-based error reporting structure. Error code is 2 bytes
long. The first byte specifies the error category, whereas the second specifies the error / success condition.
Error Type Ext Error Error Source (Module) Error Code
S S X X M M M M E E E E E E E E
Error type specifies the general error type. 00: Command was successfully completed
01: General Error 10: Not specified/used
11: Fatal Error
Ext Error Type specifies the Module type for which the error was generated.
00: Auth 01: Billing
10: General 11: System/Service
Error Source specifies the XML type that was the source for generating this error. 0000: SMS Mobile Terminated XML
0001: SMS Status Request XML 0010: SMS Credit Check XML
0011: SMS User Management XML was executed 0100: SMS Mobile Originating XML generated this error
0101: Message Schedule Related error was generated
1111: General Module generated this error
35
All errors that may come across in ValueFirst Pace Client API version are listed below.
Binary Value Decimal Error Code
General
11001111 00000000 52992 Username / Password incorrect
11011111 00000001 57089 Contract expired
11011111 00000010 57090 User Credit expired
11011111 00000011 57091 User disabled
11111111 00000000 65280 Service is temporarily unavailable
11111111 11111111 65535 The specified message does not conform to DTD
00010000 00000000 0 SMS submitted success NO Error (not returned in ValueFirst
Pace Client API version )
Message Post
01110000 00000001 28673 Destination number not numeric
01110000 00000010 28674 Destination number empty
01110000 00000011 28675 Sender address empty
01110000 00000100 28676 SMS over 160 character
01110000 00000101 28677 UDH is invalid
01110000 00000110 28678 Coding is invalid
01110000 00000111 28679 SMS text is empty
01110000 00001000 28680 Invalid sender ID
01110000 00001001 28681 Invalid message. Submit failed
01110000 00001010 28682 Invalid Receiver ID (will validate Indian mobile numbers
only.)
01110000 00001011 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
00110001 00000000 8448 Message delivered successfully
00110001 00000001 8449 Message failed
01110001 00000010 8450 Message ID is invalid
Scheduler Related
00110101 00000000 13568 Command Completed Successfully
01110101 00000001 13569 Cannot update/delete schedule since it has already been
processed
01110101 00000010 13570 Cannot update schedule since the new date-time parameter
is incorrect.
01110101 00000011 13571 Invalid SMS ID/GUID
01110101 00000100 13572 Invalid Status type for schedule search query. The status
strings can be “PROCESSED”, “PENDING” and “ERROR”.
01110101 00000101 13573 Invalid date time parameter for schedule search query
01110101 00000110 13574 Invalid GUID for GUID search query
01110101 00000111 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.
36
37
Data Type Definitions
SMS-MT Data Type Definition SMS-MT (SMS Mobile Terminated) communication is defined by the following DTD <?xml version="1.0" encoding="ISO-8859-1"?>
<!ELEMENT MESSAGE (USER,SMS+)>
<!ELEMENT USER EMPTY>
<!ATTLIST USER
USERNAME CDATA #REQUIRED
PASSWORD CDATA #REQUIRED
>
<!ELEMENT SMS (ADDRESS+)>
<!ATTLIST SMS
UDH CDATA #IMPLIED
CODING CDATA #IMPLIED
TEXT CDATA #REQUIRED
PROPERTY CDATA #IMPLIED
ID CDATA #REQUIRED
DLR CDATA #IMPLIED
VALIDITY CDATA #IMPLIED
SEND_ON CDATA #IMPLIED
>
<!ELEMENT ADDRESS EMPTY>
<!ATTLIST ADDRESS
FROM CDATA #REQUIRED
TO CDATA #REQUIRED
SEQ CDATA #REQUIRED
TAG CDATA #IMPLIED
>
When a client sends messages in XML conforming to above DTD the server replies in XML
conforming to the following DTD. This DTD is version acknowledge.dtd: <?xml version="1.0" encoding="ISO-8859-1"?>
<!ELEMENT MESSAGEACK (Err?|GUID*)>
<!ELEMENT Err EMPTY>
<!ATTLIST Err
Code CDATA #REQUIRED
Desc CDATA #REQUIRED
>
<!ELEMENT GUID (ERROR*)>
<!ATTLIST GUID
GUID CDATA #REQUIRED
SUBMITDATE CDATA #REQUIRED
ID CDATA #REQUIRED
>
<!ELEMENT ERROR EMPTY>
<!ATTLIST ERROR
SEQ CDATA #REQUIRED
CODE CDATA #REQUIRED
38
DESC CDATA #IMPLIED>
SMS-SR Status Request Data Type Definition When checking for status of a message or group of messages, the client should send XML
conforming to the following DTD: <?xml version="1.0" encoding="ISO-8859-1"?>
<!ELEMENT STATUSREQUEST (USER,GUID+)>
<!ELEMENT USER EMPTY>
<!ATTLIST USER
USERNAME CDATA #REQUIRED
PASSWORD CDATA #REQUIRED
>
<!ELEMENT GUID (STATUS*)>
<!ATTLIST GUID
GUID CDATA #REQUIRED
>
<!ELEMENT STATUS EMPTY>
<!ATTLIST STATUS
SEQ CDATA #REQUIRED
>
When server receives messages or group of messages conforming to above DTD, the server
replies with XML conforming to the following DTD. This DTD is statusack.dtd: <?xml version="1.0" encoding="ISO-8859-1"?>
<!ELEMENT STATUSACK (GUID+)>
<!ELEMENT GUID (STATUS*)>
<!ATTLIST GUID
GUID CDATA #REQUIRED
>
<!ELEMENT STATUS EMPTY>
<!ATTLIST STATUS
SEQ CDATA #REQUIRED
ERR CDATA #REQUIRED
DONEDATE CDATA #REQUIRED
REASONCODE CDATA #IMPLIED
>
SMS-CR Data Type Definition SMS-CR (SMS Credit Request) communication is defined by the following DTD <?xml version="1.0" encoding="ISO-8859-1"?>
<!ELEMENT REQUESTCREDIT ANY>
<!ATTLIST REQUESTCREDIT
USERNAME CDATA #REQUIRED
PASSWORD CDATA #REQUIRED
>
When a client sends messages in XML conforming to above DTD the server replies in XML
conforming to the following DTD. This DTD is version creditack.dtd: <?xml version="1.0" encoding="ISO-8859-1"?>
<!ELEMENT SMS-Credit (Err|Credit)?>
<!ATTLIST SMS-Credit
User CDATA #REQUIRED
39
>
<!ELEMENT Err EMPTY>
<!ATTLIST Err
Code CDATA #REQUIRED
Desc CDATA #REQUIRED
>
<!ELEMENT Credit EMPTY>
<!ATTLIST Credit
Limit CDATA #REQUIRED
Used CDATA #REQUIRED
>
SMS-MO Data Type Definition
SMS-MO (SMS Mobile Originated) communication is defined by the following DTD: <!ELEMENT REQUEST (USER,PASSWORD,CONDITION*,FLAG)>
<!ELEMENT USER (#PCDATA)>
<!ELEMENT PASSWORD (#PCDATA)>
<!ELEMENT FLAG (#PCDATA)>
<!ELEMENT CONDITION (TONUMBER?,FROMNUMBER?,TODATE?,FROMDATE?)>
<!ELEMENT TONUMBER (#PCDATA)>
<!ELEMENT FROMNUMBER (#PCDATA)>
<!ELEMENT TODATE (#PCDATA)>
<!ELEMENT FROMDATE (#PCDATA)> When ValueFirst Pace receives a request for downloading messages, it sends back response in
the following format: <!ELEMENT MESSAGING (TO+,REMAININGMSG)>
<!ELEMENT TO (SMS+)>
<!ELEMENT SMS (FROM,MSG)>
<!ELEMENT FROM (#PCDATA)>
<!ELEMENT MSG (#PCDATA)>
<!ELEMENT REMAININGMSG (#PCDATA)>
SMS-SCHEDULE Data Type Definition SMS-schedule (SMS scheduling functions) uses following DTD: <?xml version="1.0" encoding="ISO-8859-1"?>
<!ELEMENT SCHEDULE (USER,GUID+)>
<!ELEMENT USER EMPTY>
<!ATTLIST SCHEDULE
ACTION (DELETE|UPDATE) "UPDATE"
>
<!ATTLIST USER
USERNAME CDATA #REQUIRED
PASSWORD CDATA #REQUIRED
>
<!ELEMENT GUID EMPTY>
<!ATTLIST GUID
GUID CDATA #REQUIRED
MODIFIER CDATA #IMPLIED>
40
When a schedule-delete or modify command is sent the following is the response DTD: <?xml version="1.0" encoding="ISO-8859-1"?>
<!ELEMENT SCHEDULE_RESPONSE (GUID)>
<!ELEMENT GUID EMPTY>
<!ATTLIST SCHEDULE
ERROR CDATA #REQUIRED
>
<!ATTLIST GUID
GUID CDATA #IMPLIED
ERROR CDATA #REQUIRED
>
SMS-SCHEDULE-LIST Data Type Definition SMS-schedule LIST (SMS scheduling reporting functions) uses following DTD: <?xml version="1.0" encoding="ISO-8859-1"?>
<!ELEMENT SCHEDULE_LIST (USER,CONDITION)>
<!ELEMENT USER EMPTY>
<!ELEMENT CONDITION EMPTY>
<!ATTLIST SCHEDULE_LIST
ACTION (LIST) "LIST"
>
<!ATTLIST USER
USERNAME CDATA #REQUIRED
PASSWORD CDATA #REQUIRED
>
<!ATTLIST CONDITION
STATUS_TYPE (PROCESSED|PENDING|ERROR|SCHEDULED|GUID) "PROCESSED"
START_DATE CDATA #IMPLIED
END_DATE CDATA #IMPLIED
GUID CDATA #IMPLIED
>
When a schedule list query is sent, the following is the response: <?xml version="1.0" encoding="ISO-8859-1"?>
<!ELEMENT SCHEDULE_LIST_RESPONSE (GUID)>
<!ATTLIST SCHEDULE_LIST_RESPONSE ERROR CDATA #REQUIRED>
<!ELEMENT GUID EMPTY>
<!ATTLIST GUID
GUID CDATA #REQUIRED
ERROR CDATA #REQUIRED
CREDIT_USED CDATA #REQUIRED
ADDRESS CDATA #REQUIRED
SCHEDULED_ON CDATA #REQUIRED
EXECUTED_ON CDATA #REQUIRED
>
41
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
alphanumeric and short-code sender id. The Direction can be downloaded directly from TRAI website or by following clicking following link:
http://www.trai.gov.in/WriteReadData/trai/upload/Directives/131/direction10dec08.pdf
The Identification Code will be of three characters, consisting, Service Provider Code and Service
Area Code, followed by a Hyphen. Hence the maximum length of an Alpha-numeric sender ID will be reduced to 8 characters from the existing 11 characters.
The details of operator codes are as below:
42
The Details of Circle codes are as below:
43
National Do Not Call Registry (N DNC) NDNC is a global database of all users who do not wish to receive unsolicited commercial communication. The list is managed by TRAI. A person whose mobile number exists in this list
must not be sent any commercial communication using voice or SMS, when he has not given explicit permission to receive so.
ValueFirst has a strict No-SPAM policy. This means all messages terminated using ValueFirst APIs
will go through DNC check. Messages sent to end-user whose mobile phone is in DNC will not be terminated on his handset.