Download pdf - ValueFirst XML API v1.5.02 SMS API

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.


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.

mailto:dth@dishtv

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) &#032

#34 (double quote) &quot

> &gt

< &lt

#13 (Line feed) &#013

#10(form feed) &#010

#9(Tab) &#009

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

http://127.0.0.1/psms/dtd/message.dtd

Accessing Server Services

To access ValueFirst Pace, you need to register for a regular business account. For getting an account, contact ValueFirst at [email protected]

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/.

mailto:[email protected]

http://api.myvaluefirst.com/psms/

15


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"  </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.


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" />


</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.

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


<!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" />


<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>



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 .




<SMS UDH="4" CODING="3" TEXT=" 424547494E3A56434152440D0A56455253494F4E3A322E310D0A4E3A536D6974683B4D696B650D0A54454C3B505245463A2B35353531323334350D0A454E443A564341

52440D0A" PROPERTY="" ID="1">

<ADDRESS FROM="919812345678" TO="919812345678" SEQ="1"

TAG="some client side random data" />


<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>



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:


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" />


http://www.vfirst.com/

24

</MESSAGE>

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


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.


<!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:


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.


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:


<STATUSACK> <GUID GUID="3de2ec71-1c37-4999-a758-e354dd6fdb1d">

<STATUS SEQ="1" ERR="50" DONEDATE="2004:10:13 12:10:12"/> 

<STATUS SEQ="2" ERR="8448" DONEDATE="0"/>  </GUID>

<GUID GUID="3de2ec71-1c37-4999-a758-s354dd6fdb1d">

<STATUS SEQ="1" ERR="8448" DONEDATE="2004:10:13 12:10:12" REASONCODE=""/> 

<STATUS SEQ="2" ERR="8448" DONEDATE="2004:10:13 12:10:12" REASONCODE=""/> 

< 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=""/>  <STATUS SEQ="6" ERR="8448" DONEDATE="2004:10:13 12:10:12"

REASONCODE=""/>  </GUID>

</STATUSACK>

26

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 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:


<!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>

http://www.myvaluefirst.com/psms/servlet/psms.MOService

http://www.myvaluefirst.com/psms/getXML1_1.jsp

http://www.myvaluefirst.com/psms/getXML.jsp

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"?>



<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


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">


<GUID GUID="3de2ec71-1c37-4999-a758-e354dd6fdb1d" MODIFIER=""/> </ SCHEDULE >


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.


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.


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


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:


<!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.


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+)>


<!ATTLIST USER



>

<!ELEMENT GUID (STATUS*)>

<!ATTLIST GUID


>

<!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


>

<!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



>

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+)>


<!ATTLIST SCHEDULE

ACTION (DELETE|UPDATE) "UPDATE"

>

<!ATTLIST USER



>

<!ELEMENT GUID EMPTY>

<!ATTLIST GUID


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)>


<!ATTLIST SCHEDULE

ERROR CDATA #REQUIRED

>

<!ATTLIST GUID

GUID CDATA #IMPLIED


>

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 CONDITION EMPTY>

<!ATTLIST SCHEDULE_LIST

ACTION (LIST) "LIST"

>

<!ATTLIST USER



>

<!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>


<!ATTLIST GUID



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:

http://www.trai.gov.in/WriteReadData/trai/upload/Directives/131/direction10dec08.pdf

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.