ValueFirst XML API v1.5.02 SMS API

  • Published on
    27-Dec-2015

  • View
    372

  • Download
    4

Embed Size (px)

DESCRIPTION

this is an api for valuefirst sms api doc.

Transcript

  • 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 codee.g. 91 in case of an Indian number. No leading 0 or + are allowede.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 Senders ID are db@sky (invalid character in Sender) SomeInvalidSender (more than 11 characters)

    Typical examples of correct Senders 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 users 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) &quot

    > &gt

    < &lt

    #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=&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%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 thr...