mgateway http interface user guide

mGateway

HTTP Interface User Guide Version 1.3

Date 11/2009

Table of Contents

1 Forewords 3 1.1 Getting Started 3 1.2 Netsize Technical Support 3

2 Introduction 4 2.1 Architecture 4 2.2 Supported Operations 4

3 Sending MT SMS 5 3.1 Process 5 3.2 Account Parameters 5 3.3 mGateway URLs 5 3.4 Mandatory Parameters 7 3.5 Optional Parameters 8 3.6 The Netsize Test Page 12 3.7 Various MT Messages Samples 13 3.8 HTTP Response 15

4 Receiving MO SMS & Status Reports 17 4.1 Process 17 4.2 MO SMS Parameters 19 4.3 Status Reports Parameters 24 4.4 HTTP Requests Samples 25

5 Sending WAP Push Service Indication 28 5.1 Connection Parameters 28 5.2 mGateway URLs 28 5.3 The Netsize Test Form 31 5.4 Samples of HTTP Request 32 5.5 Return Result Page 33

© 2009 Netsize Forewords 2 / 35

1 Forewords Note: This document was previously named NMO Fast HTTP Interface User Guide.

The HTTP interface is intended for the developers who want to connect to mGateway for:

• Mobile Terminated (MT) bulk/Premium SMS services • Mobile Originated (MO) bulk/Premium SMS services.

The HTTP interface requires developing an HTTP client to send MT SMS messages to mGateway and an HTTP server to receive MO messages and Status Reports.

Note: The mGateway HTTP interface is compatible with high volume messaging applications.

Several interfaces are available to access the Netsize mGateway: • API (Java/.NET/C++) • HTTP based • SMPP protocol • SOAP to connect via a Web service.

1.1 Getting Started

You will need the following from Netsize to use the HTTP interface:

• Valid login/password • Endpoint name.

Netsize provides you the above information when opening your mGateway account.

In order to receive MO SMS and Status Reports, you will need to provide the following information to your Netsize account manager:

• URL of your HTTP server for receiving MO SMS • URL of your HTTP server for receiving Status Reports.

If your HTTP server filters IP addresses, you must contact your Netsize technical manager. He will provide you with the list of the Netsize IP ranges.

1.2 Netsize Technical Support

If you run into any issues, you may connect to Netsize Webcare https://webcare.netsize.com using your login and password.

Process

1. You enter your technical request (case) on Netsize Webcare 2. Your request is transmitted to Netsize support teams. Processing time will depend on:

• your SLA • the type of request • the type of service.

All exchanges are done through the Webcare and reported by email. In order to get technical support, please use your extranet access at: https://webcare.netsize.com

© 2009 Netsize Forewords 3 / 35

https://webcare.netsize.com/

https://webcare.netsize.com/

2 Introduction The Netsize HTTP Interface lets you develop applications to send and receive SMS messages via HTTP.

Note: The Netsize HTTP interface does not enable to send or receive MMS messages. In order to send or receive MMS messages, you must use Netsize API for MMS or MM7 Interface.

2.1 Architecture

The Netsize HTTP server is fully integrated into the mGateway broker. If you want to connect to this server, you need to use an HTTP client application. Netsize develops HTTP servers for each Netsize gateway worldwide.

2.2 Supported Operations

MT SMS

You can send MT SMS in:

• GET (all parameters are stored in the URL) or • POST (all parameters are stored in the body of the HTTP request, in plain text or XML format).

By default, Netsize returns a response in plain text. You can also ask to receive responses in XML with short tags or XML with long tags. See Output parameter.

MO SMS/SR

You can receive MO SMS and Status Reports in GET or POST.

© 2009 Netsize Introduction 4 / 35

3 Sending MT SMS 3.1 Process

In order to send an MT SMS, you must:

1. Build an HTTP request including all the necessary parameters 2. Send the HTTP request to Netsize. 3. Once you have sent the MT SMS, you must:

a. receive an HTTP response from Netsize b. Check the HTTP response.

In order to build an HTTP request to send an MT SMS, first you need to set your connection parameters. This includes:

• your account parameters • the URL of the Netsize gateway from which you send the MT SMS.

3.2 Account Parameters

Netsize provides you with mGateway accounts to perform SMS traffic. For each mGateway account, Netsize provides you with the parameters:

• sEndpointName • sLogin • sPassword.

3.3 mGateway URLs

mGateway accounts enable you to send MT SMS from a Netsize URL. Netsize URLs have the following format:

http://xxx.netsizeonline.com:yyyy/Request.aspx

xxxx corresponding to the Netsize gateway prefix and yyyy to connection port, usually 8080

You will use one of the following URLs; depending on:

• the type of traffic you perform (standard SMS/Premium SMS/Massive Push/Wordwide Push) • the destination country of your MT SMS.

3.3.1.1 Bulk (Standard) SMS Traffic

Country mGateway URL

Austria http://at.netsizeonline.com:8080/Request.aspx

France http://Fr.netsizeonline.com:8080/Request.aspx

Belgium http://be.netsizeonline.com:8080/Request.aspx

Germany http://de.netsizeonline.com:8080/Request.aspx

Italy http://IT.netsizeonline.com:8080/Request.aspx

Netherlands http://NL.netsizeonline.com:8080/Request.aspx

Spain http://es.netsizeonline.com:8090/Request.aspx

Sweden http://se.netsizeonline.com:8080/Request.aspx

Switzerland http://ch.netsizeonline.com:8080/Request.aspx

UK http://uk.netsizeonline.com:8080/Request.aspx

© 2009 Netsize Sending MT SMS 5 / 35

http://at.netsizeonline.com:8080/Request.aspx

http://fr.netsizeonline.com:8080/Request.aspx

http://be.netsizeonline.com:8080/Request.aspx

http://de.netsizeonline.com:8080/Request.aspx

http://it.netsizeonline.com:8080/Request.aspx

http://nl.netsizeonline.com:8080/Request.aspx

http://es.netsizeonline.com:8090/Request.aspx

http://se.netsizeonline.com:8080/Request.aspx

http://ch.netsizeonline.com:8080/Request.aspx

http://uk.netsizeonline.com:8080/Request.aspx

3.3.1.2 Premium SMS Traffic

Country mGateway URL

Australia http://AUP.netsizeonline.com:8080/Request.aspx

Belgium http://BEP.netsizeonline.com:8080/Request.aspx

Denmark http://DKP.netsizeonline.com:8080/Request.aspx

Finland http://fip.netsizeonline.com:8080/Request.aspx/ http://FIP.netsizeonline.com:8080/Request.aspx

France http://FRP.netsizeonline.com:8080/Request.aspx

Greece http://grp.netsizeonline.com:8080/Request.aspx

Hungary http://hup.netsizeonline.com:8080/Request.aspx

Morocco http://map.netsizeonline.com:8080/Request.aspx

Netherlands http://NLP.netsizeonline.com:8080/Request.aspx

Norway http://nop.netsizeonline.com:8080/Request.aspx

Portugal http://ptp.netsizeonline.com:8080/Request.aspx

Russia http://rup.netsizeonline.com:8080/Request.aspx

South Africa http://zap.netsizeonline.com:8080/Request.aspx

Spain http://ESP.netsizeonline.com:8080/Request.aspx

Sweden http://sep.netsizeonline.com:8080/Request.aspx

Switzerland http://chp.netsizeonline.com:8080/Request.aspx

Turkey http://trp.netsizeonline.com:8080/Request.aspx

United Kingdom http://ukrc.netsizeonline.com:8080/Request.aspx

United States http://usp.netsizeonline.com:8080/Request.aspx

3.3.1.3 Worldwide Push

http://WWP.netsizeonline.com:8080/Request.aspx

3.3.1.4 Massive Push

http://hvb.netsizeonline.com:8080/Request.aspx


http://aup.netsizeonline.com:8080/Request.aspx

http://bep.netsizeonline.com:8080/Request.aspx

http://dkp.netsizeonline.com:8080/Request.aspx

http://fip.netsizeonline.com:8080/Request.aspx/

http://fip.netsizeonline.com:8080/Request.aspx

http://frp.netsizeonline.com:8080/Request.aspx

http://grp.netsizeonline.com:8080/Request.aspx

http://hup.netsizeonline.com:8080/Request.aspx

http://map.netsizeonline.com:8080/Request.aspx

http://nlp.netsizeonline.com:8080/Request.aspx

http://nop.netsizeonline.com:8080/Request.aspx

http://ptp.netsizeonline.com:8080/Request.aspx

http://rup.netsizeonline.com:8080/Request.aspx

http://zap.netsizeonline.com:8080/Request.aspx

http://esp.netsizeonline.com:8080/Request.aspx

http://sep.netsizeonline.com:8080/Request.aspx

http://chp.netsizeonline.com:8080/Request.aspx

http://trp.netsizeonline.com:8080/Request.aspx

http://ukrc.netsizeonline.com:8080/Request.aspx

http://usp.netsizeonline.com:8080/Request.aspx

http://wwp.netsizeonline.com:8080/Request.aspx

http://hvb.netsizeonline.com:8080/Request.aspx

3.4 Mandatory Parameters

The table below contains the mandatory parameter for submitting a message.

Parameter Description Value and/or Format

sEndpointName Account parameter Provisioned by Netsize

sLogin Account parameter Provisioned by Netsize

sPassword Account parameter Provisioned by Netsize

sExtensionName Name of the extension Must always be: AGSMSExt^Netsize

This field must be URL encoded

sMessage The message that will be sent to the mobile phone.

Warning: This parameter must not be used for multi‐part SMS. See Binary Parameters section.

The maximum length permitted is:

• 160 characters for a text message • 140 bytes for a binary message • 70 characters for a Unicode message.

sTarget MSISDN(s) of the mobile phone(s) that will receive the MT SMS. The maximum number of MSISDNs permitted is 10. MSISDNs must be separated by a “;” character (semi‐colon)

International format is required.

Example: +33xxxxxxxxx for France

This field must be URL encoded


3.5 Optional Parameters

The following lists the optional parameters for submitting a message. Optional parameters may be product or operator specific.

General Parameters

Parameter Description Value and/or format Data Type

nClassType The SMS message Class. See the Glossary section for further details on the GSM SMS Classes.

Value

Description

0 Flash SMS

1 SMS stored on mobile equipment. Netsize default value

2 SMS stored on the SIM

3 SMS stored on terminal equipment

Long

dDelayDate Delays delivery of the SMS to the mobile phone

Format is: YYYY/MM/DD hh:mm:ss (for example, 2000/01/31%2012:30:00)

Datetime

nNotification The notification level requested for the MT message. Notification is an operator‐dependent feature.

Value

Types of notifications returned

0 Netsize default value. No operator notification returned

1 Only buffered message notification

2 Only delivery notification

3 Only non delivery notification

4 Buffered message + delivery notification

5 Buffered message + non delivery notification

6 Delivery + non delivery notification

7 All notifications

Long

sOADC Defines the sender address. OadC is an operator‐dependent feature. Please contact your Netsize account manager for more information on the supported OAdC (numeric or alphanumeric) on each operator.

Maximum length is 15 characters and depends on operator

String

nPriority Defines the priority level of the message 0: Normal. Netsize default value

1: High

2: Urgent

Long

sSmsExtId An identifier defined by the Customer for the MT SMS. If defined, it is returned in the parameter P2 of the Status Report.

The maximum length permitted is 64 characters

String

dValidityDate Defines the date beyond which the MT message will not be retained in the operator network. If it exceeds three days, Netsize cannot guarantee that the MT message and/or notification will be

Netsize default value is 3 days.

You can define a lower value if necessary.

Date format is: YYYY/MM/DD hh:mm:ss (e.g. 2000/01/31%2012:30:003)

Datetime


delivered correctly. Validity date is an operator‐dependent feature.

Output Format of the HTTP response Netsize default value is plain text if this parameter is not provided.You can set the following values:

“XML”: XML with short tags

“XMLLongTags”: XML with long tags

String

Account Selection/Master Accounts Parameters

Master accounts enable to switch among several accounts without logging off and logging in. The SMS traffic is dispatched based upon one or several parameters, each Dispatch value being linked to an mGateway account. The following parameters can be provisioned by Netsize for the Customers who wish to set up a master account configuration.

Note: Customers may ask their Netsize technical contact to set up a master account configuration.

Parameter Description Value and/or format

Data Type

sDispatchPrice

Can be used if you want to launch several end‐user prices on the same Premium SMS short code. You ask Netsize to configure one Dispatch Price value per end‐user price. Example of configuration for a Premium SMS short code in Germany that propose three end‐user prices.

• “3.50”: account with end‐user price at 3.50 Euro • “1.50”: account with end‐user price at 1.50 Euro • “1.20”: account with end‐user price at 1.20 Euro Warning: In France, the value “1.00” is used to send Premium SMS messages whatever the price of the short code. Pleaserefer to the Premium MO/MT Messaging User Guide for France for all details.

Provisioned by Netsize. Format must be ‘x.xx’

String

sDispatchShortCode Can be used to dispatch the traffic basing on the short code value, for instance, if you use the same master accounts for several short codes.

Provisioned by Netsize

String

nDispatchOperator

Can be used to dispatch the traffic basing on the operator. Example of configuration:

• 208001: Orange France • 208010: SFR • 208020: Bouygues Telecom


Long

sDispatchApplication

Can be used to dispatch the traffic basing any parameter chosen by the Customer. Example of configuration:

• 0: Account with priority “normal” • 1: Account with priority “High” • 2: Account with priority “Urgent”


String


Specific parameter (only for standard traffic in France)

Parameter Description Value and/or format Data Type

nAppType Define the type of application relating to the MT message.

Only for standard traffic in France.

• 0: Closed User Group • 1: Content delivery • 2: Direct marketing,

Netsize Default Value. • 3: Chat

Long

Binary Parameters

The table below contains the additional parameters to send a binary message.

Parameter Description Value Data Type

bHexString

Identifies the use of a hexadecimal string to represent the message.

Warning: This parameter must not be used for multi‐part SMS.

Must be set to 1 Boolean

nBinary Identifies the type of the binary message • 1: Wap push

• 2: Unicode • 3: Multi‐part text

Long

bUnicode Must be used to send a Unicode message Must be set to 1 Boolean

bTPUDHI Identifies the use of a UDH (User Data Header) or not Must be set to 1 Boolean

sTPPID Configure TPPID value in SMS. Example : “0127” String

oMessage

Must be used for multi‐part SMS only. Includes the message that will be sent to the mobile phone.

Warning: If used, this parameter replaces the sMessage parameter.

String

Note: Examples of binary MT requests are provided in the Various MT Messages Samples section.


Premium SMS Parameters

The table below contains optional parameters for submitting a message relating to a Premium SMS service. Optional parameters may be product or operator specific.

Note: You may refer to the Premium Messaging User Guides to get the parameters that need to be implemented in each country.


sRealAlias The alias of the service as provisioned by Netsize

Provisioned by Netsize String

nMediaType

Channel through which the end‐user ordered the service

• 0: SMS • 1: WAP • 2: Web

Long

sRequestId

When supported by the operator, this parameter is used as a Billing ID. You receive it in incoming MO SMS. Upon receiving such information, you must post it back into the Request ID field of the MT reply.

Provided via MO SMS by the operator String

nSubscriptionAction

Provides information on the status of an end‐user subscription

• 0:Subscribes end‐user to service • 1:Suspends end‐user

subscription • 2:Renews end‐user subscription • 3:Unsubscribe end‐user from

service • 4:Unsubscribe end‐user from all

services on short code • 5:Follow‐up: Marks service

delivery for an active subscription

Long

nRequestPIN For Vodafone Germany, this parameter enables customers to have Vodafone generate and send a PIN code to the end‐user

Value must be set to 1 Long

nSubscriptionPIN For Vodafone Germany, this parameter triggers a billing validation request

Value corresponds to the PIN sent by Vodafone and entered by the end‐user on the Customer’s Web site

Long

sTimMessageType

For TIM Italy, all‐in‐one parameterthat includes information regarding the channel, service, content, price and content provider.

Provisioned by Netsize in the service project description form

String

sExtContentType Type of content included in the MT message See Premium Messaging User Guide String

sContractID For SFR France, ID number assigned by the operator for an end‐user subscription

Provided via MO SMS String

3.5.1.1 Deprecated Parameters

The following parameters are deprecated. You may use the Subscription Action parameters instead.


bFollowUp Specifies that the MT message corresponds to a service delivery


bSubscribe Specifies that the MT message corresponds to a subscription request


bUnsubscribe Specifies that the MT message corresponds to an unsubscription request



3.6 The Netsize Test Page

Netsize test pages enable to send HTTP requests without having to build the whole HTTP request.

URLs format is: http:www.XX.netsizeonline.com/ServerAccess/

Example: http://msuk.netsize.com/NS_SMS/SendForm.aspx


http://msuk.netsize.com/NS_SMS/SendForm.aspx

3.7 Various MT Messages Samples

The following samples can be used in HTTP GET or HTTP POST. All values in these examples should be replaced by your own values.

HTTP GET Requests Encoding

If you use HTTP GET, all parameters must be URL encoded, for example ‘+33’ must be encoded as ‘%2B33’.

Character + # ^ / :

Encoded value %2B %23 %5E %2F %3A

Text SMS

sExtensionName=AGSMSExt^Netsize &sEndpointName=EndpointName &sLogin=Login &sPassword=Password &sTarget=+336XXXXXXXX &sMessage=Message &nClassType=1 &nNotification=7 &sOADC=OADC &sSmsExtId=ExtId

Text: multi‐part (long SMS)

Part 1: sExtensionName=AGSMSExt^Netsize &sEndpointName=EndpointName &sLogin=Login &sPassword=Password &sTarget=+336XXXXXXXX &oMessage=0500031202017468697320697320612076657279206C6F6E67206D657373616765207468617420 77696C6C20626520656E636F64656420696E746F20322070617274732E204561636820706172742077696C6C2 062652073656E742073657061726174656C7920616E64207468652068616E647365742077696C6C2070617374 207468652074776F20706172747320746F2073686F77206F6E6C79206F6E65 &nClassType=1 &nBinary=3 &bTPUDHI=1 oMessage = [UDH –Length = 05][UDH-Information Element [Identifier = 00][Length = 03][Data [ReferenceNumber = 12][NumberOfParts = 02][PartNumberInSequence=01]]][text=’this is a very long message that will be encoded into 2 parts. Each part will be sent separately and the handset will past the two parts to show only one’] using Windows 1252 Encoding


Part 2: sExtensionName=AGSMSExt^Netsize &sEndpointName=EndpointName &sLogin=Login &sPassword=Password &sTarget=+336XXXXXXXX &oMessage=050003120202206D657373616765 &nClassType=1 &nBinary=3 &bTPUDHI=1 oMessage = [UDH–Length = 05][UDH-Information Element [Identifier = 00][Length = 03][Data [ReferenceNumber = 12][NumberOfParts = 02][PartNumberInSequence=02]]][text=’ message’] using Windows 1252 Encoding

WAP Push SMS

sExtensionName=AGSMSExt^Netsize &sEndpointName=EndpointName &sLogin=Login &sPassword=Password &sTarget=+336XXXXXXXX &sMessage=0605040B8423F08B060403AE81EA02056A0045C60B03687474703A2F2F7777772E6E657473697A652E636F6D2F001103313233406E657473697A652E636F6D00080AC3072003111315441110C30420131113010354657374204F54412066726F6D204E657473697A65000101 &nNotification=7 &sOADC=OADC &sSmsExtId=ExtId &nClassType=1 &bHexString=1 &bTPUDHI=1 &nBinary=1

Unicode SMS

sExtensionName=AGSMSExt^Netsize &sEndpointName=EndpointName &sLogin=Login &sPassword=Password &sTarget=+336XXXXXXXX &sMessage=0445043E0440043E0448043E0301 &nNotification=7 &nClassType=1 &bHexString=1 &bUnicode=1


3.8 HTTP Response

After receiving and interpreting your HTTP request, Netsize sends an HTTP response message.

HTTP responses include:

• a status line (return code + generic message) • as many additional lines as targets included in the HTTP request message (return code + ticketID +

specific information message for each target).

Return code value Explanation

0 MT SMS has been successfully sent to the operator SMS‐C and for all targets. You can ignore the rest of the response.

Different from ‘0’

MT SMS sending failed. In addition to the HTTP codes, you may receive:

• the error return code ‘47’ if at least one mandatory MT SMS parameter is missing or is invalid, or,

• an mGateway error return code. View the mGateway Error Codes document.

Plain Text

By default, you receive HTTP response in plain text. Format is:

code;message\r\n

code;ticket;message\r\ncode;ticket;message\r\n

XML short tags

Here is an example of XML short tags formatted response for a multiple sending (1 MT SMS for 2 MSISDNs).

<?xml version="1.0" encoding="UTF-8"?> <NMGSMSMTR> <R> <RC>0</RC> <RM>Success</RM> </R> <TL> <T> <C>0</C> <M/> <A>+33600000001</A> <I>987654321</I> </T>


http://www.netsize.com/sdk/NSO_SMS.html

XML Long Tags

Here is an example of XML long tags formatted response for a multiple sending (1 MT SMS for 2 MSISDNs).

<?xml version="1.0" encoding="UTF-8"?> <NMGSMSMTResponse> <Result> <Code>0</Code> <Message>Success</Message> </Result> <TicketList> <Ticket> <StatusResultCode>0</StatusResultCode> <StatusResultMessage/> <Address>+33600000001</Address> <IdTicket>987654321</IdTicket> </Ticket>


4 Receiving MO SMS & Status Reports 4.1 Process

The Netsize HTTP interface enables to directly receive MO SMS or SRs on a page of your Web server; without having to connect to the Netsize gateway to retrieve asynchronous MO SMS/SRs.

Indeed, it is Netsize that contacts you to push MO SMS/SRs.

You can retrieve MO SMS/SRs on any type of Web server via a script page such as ASP, CGI or PHP.

Steps to Process an MO SMS or a Status Report

1. Netsize pushes the MO SMS/SR via HTTP (GET/POST) to your Web application. 2. You store the MO SMS/SR in your database. 3. You send an acknowledgement to confirm that the MO SMS/SR has arrived and been stored correctly. 4. You can process the MO SMS/SR message.

4.1.1.1 Storing MO SMS/SR IDs

You must store this set of values for each MO SMS/SR that you receive:

• MO SMS/SR ID, (parameter labelled ‘P1’ by default) • GW • PORT • for SR only: Event (SR parameter labelled ‘P3’ by default).

This set of values enables to determine unique messages (primary key for database).

4.1.1.2 Acknowledging MO SMS/SRs

For each MO SMS/SR that you receive, you must:

• return an HTTP response ‘200 OK’ (redirection codes of type 3xx are forbidden) • send back from your Web server an HTML page including in plain text ‘status=0’.

Any other returned information, such as HTML tags, will be considered as an incorrect processing of the MO SMS/SR and Netsize will retry sending the MO SMS/SR.

Warning: If you do not acknowledge the MO SMS/SR correctly, Netsize implements a retry mechanism.

© 2009 Netsize Receiving MO SMS & Status Reports 17 / 35

4.1.1.3 Netsize Retry Mechanism

Netsize implements a retry mechanism if you do not acknowledge correctly an MO SMS/SR.

Consequently, you must store all SMS MO/SR IDs to know if an SMS MO/SR has already been received and avoid processing again an MO SMS/SR.

Note: Netsize will try to send the MO/SR message at a decreasing lapse.

Here are some of the cases where Netsize HTTP server will implement a retry mechanism:

wrong code you sent back another HTTP code than 2xx (1xx or 3xx or 4xx or 5xx)

disconnection the HTTP connection was too slow and Netsize disconnected before getting your acknowledgement

no response you did not send any HTTP response

timeout expired you sent the HTTP response after the HTTP server timeout had expired. Netsize default HTTP timeout is set to 20 seconds to get an HTTP result (HTTP code and acknowledgment)


4.2 MO SMS Parameters

In the Netsize HTTP interface, MO SMS parameters are identified by labels that you can customize.

Mandatory Parameters

The following parameters are always found in MO SMS.

Parameter Label Description Data Type

Alias P5 Alias found in the MO message String

Alias processed P4 mGateway alias or large account String

Binary P24 Message encoding method Long

Message date P11 Date when the MO SMS was inserted into the mGateway database Datetime

Delivery date P13 Delivery date indicated by the SMS‐C Datetime

Destination address

P33 Short code from which the MO SMS is received String

Encryption type P34 For the Customer who requested encryption of MO content, determines whether the content of the MO is encrypted

Long

First word P15 First word of the MO message String

Gateway ID P35 Identifiers the MO receiving gateway Long

Message ID P1 MO message ticket ID Long

Integration date P36 Datetime

Keyword found P37 Determines whether a keyword was found in the MO SMS. Value: 0: Yes; 1: no

Boolean

Keyword generic P38 Determines whether a generic keyword was found in the MO message. By ‘generic’, we mean a ‘universal’ keyword recognized by Netsize for all countries & operators (e.g. ‘CONTACT’, ‘HELP’, ‘INFO’, ‘INDEX’, ‘RULE’, ‘RENEW’, ‘START’, ‘STATUS’; ‘STOP’,‘TEST’, ‘VIEW’)

Boolean

Keyword local P39 Determines whether a local keyword was found String

Keyword processed

P30 Keyword found in the MO SMS (e.g. ‘STOP’, ‘START’, ‘INFO’) String

Large account P40 Customer account corresponding to the alias determined for MO SMS String

Large account number

P8 The Short code from which the message has been received String

Login P42 Account login corresponding to the alias determined for MO SMS String

Message P3 MO SMS text without alias and separator String

Message received P2 MO SMS text with alias and separator Netsize adds the alias if the end‐user did not type it.

NOTE: • If the end‐user is in an MO session* and did not type the alias, parameter value = “<alias><space><P20>”

• If the end‐user typed the alias “<P2>=<P20>”

String

Message typed P20 Text of the MO message, as typed by the end‐user and received from the operator. Parameter value = “<alias><separator><text>” or “<text>” if the end‐user is in an MO session and did not type the alias

String


Mandatory Parameters (continued)

Parameter Label Description Data Type

Message (Unicode hexastring)

P43 This parameter is transmitted for MO SMS formatted in Unicode. It includes the text of the MO message without alias and separator, encoded in hexastring

String

Message received (Unicode hexastring)

P44 This parameter is transmitted for MO SMS formatted in Unicode. It includes the whole MO text message, as received from the operator, encoded in hexastring

String

Message typed (Unicode hexastring)

P45 This parameter is transmitted for MO SMS formatted in Unicode. It includes the text of the MO, as typed by the end‐user encoded in hexastring.

String

Mo Context P23 Context of the MO SMS. This parameter is related to the MO Session technical option. It enables to route MO SMS without alias.

Value Description

0 Regular alias

3 Target routing

4 Generic keyword

10 Explicit session

12 Explicit session timeout with Failed MO account

13 Explicit session stop command

14 Explicit session beginning

15 Explicit session beginning with stop command

20 Implicit session

22 Implicit session timeout with Failed MO account

Long

Operator MCC P9 Mobile Country Code of the operator who sent the MO to Netsize Long

Operator MNC P10 Mobile Network Code of the operator who sent the MO to Netsize Long

Origin P7 MSISDN of the sender String

Originated MCC P18 Operator Mobile Country Code. May differ from parameter P9 in case of roaming

Long

Originated MNC P19 Operator Mobile Network Code. May differ from parameter P10 in case of roaming

Long

Receival date P12 Date when the Netsize gateway received the MO message from the operator Datetime

Second separator

P17 Second separator of the MO message String

Second word P16 Second word of the MO message String

Separator P6 Separator found in the MO message String

SMS ID P46 MO ticket identifier (unique on a gateway) Long

Gateway GW DNS name of the SMS gateway String

Port PORT Port value to access the SMS gateway Long


4.2.1.1 MO Session

MO session is a technical option, which is targeted at Netsize Customers who have launched their services on a shared short code. Thanks to this option, end‐users do not have to enter the service alias each time they send an MO to the shared short code. Netsize stores the service alias information and automatically adds it to the end‐user’s MO message during the Premium session.

Customers will have the possibility to activate Implicit or Explicit MO sessions, depending on the type of services they want to launch.

In both cases the end‐user will not have to enter the service alias to send an MO to the short code.

The service alias is assigned to the end‐user’s MSISDN when he sends his first MO message.

MO Session Type

Description

Target routing

• The Customer declares a list of MSISDNs that will be associated to his alias. • Each time an MO SMS is sent from one of these MSISDNs, Netsize automatically

routes the MO SMS to the Customer’s URL.

Note: Target routing is possible on standard dedicated short codes only.

Implicit • During this type of session, if the end‐user sends an MO with another alias, for instance to order another service, Netsize switches his alias accordingly.

• These sessions are activated for a maximum period of 24 hours. This type of session can be used for Chat services.

Explicit • During this type of session, if the end‐user sends an MO with another alias, Netsize will ignore this new alias and will automatically associate the explicit service alias to his MO message.

• These sessions remain activated until the end‐user sends a keyword, for instance, STOP, to leave the session; or until the timeout Netsize has defined by default has expired.

This type of session can be used for subscription‐based‐services.

Note: Please ask your Netsize technical contact to activate this option.


Optional Parameters

Parameter Label Description Value Data Type

Billing plan P26 For Premium SMS in Australia, identifies whether the MSISDN is pre‐paid or post‐paid

• 1 = pre‐paid • 2 = post‐paid

Long

Concatenated message index

P49 Position of the MO SMS in a multi‐part MO SMS Long

Concatenated message length

P50 Number of parts of the multi‐part MO SMS Long

Concatenated message reference

P51 MO SMS multi‐part identifier positioned by the sending device

Long

ContractID P31 For Premium MT SMS with SFR (France), identifies an end‐user subscription

Provided by operator String

Fake MO P52 Identifies if the MO is a fake MO, i.e., has not been sent by an end‐user but generated by Netsize

Value must be set to ‘TRUE’

Boolean

I‐mode status P21 For Premium SMS with Bouygues Telecom (France), specifies whether the end‐user is registered to the I‐Mode option

• 0: no • 1: yes

Long

MMS status P28 For Premium SMS with Bouygues Telecom (France), specifies if the mobile phone is MMS compatible

• 0: no • 1: yes

Long

Parental control level

P29 For Premium SMS with SFR (France), specifies the level of parental control activated on an MSISDN

• 0: reinforced • 1: regular • 2: not activated • 999: data NOT

available

Long

RequestID P14 Billing ID assigned by the operator to the MO SMS String

SAC P27 For Premium SMS with Bouygues Telecom (France), provides the 2 last digits of the mobile phone Type Allocation Code. It must be concatenated with the parameter TAC to get the complete 8 digits of the Type Allocation Code.

String

Service access

P32 For Premium MT SMS with Mobilcom (Germany), specifies whether the end‐user is authorized to receive Premium MT SMS messages

• 0: Yes • 1: No

Long

Subscription action

P25 MO request type • 0: subscription request

• 3: unsubscription request

Long

TAC code P22 For Premium SMS in France, provides different information depending on operators:

Operator

Description Length

Bouygues Telecom

The 6 first digits of the mobile phone Type Allocation Code. It must be concatenated with the parameter SAC to get the complete 8 digits of the Type Allocation Code.

6 digits

Orange France

A 4‐digit TAC ID that must be mapped with Orange France TAC

4 digits

String


Note: The Type Allocation Code corresponds to the 8 first digits of the IMEI number. IMEI stands for International Mobile Equipment Identity. It is a unique number that identifies every GSM mobile phone.

code table to get the real Type Allocation Code. Please ask your Netsize technical contact to get Orange France TAC code table.

SFR The mobile phone Type Allocation Code

8 digits


4.3 Status Reports Parameters

SR parameters are identified by labels, which can be customized. The table below lists the SR parameters.

Parameter Label Description

Ticket ID P1 The unique Netsize ID for the MT message

Ext ID P2 MT SMS Client ID

Event P3 The status of the MT message

Code Label Description Type

2 RetryFailed The MT SMS could not be sent to the operator SMS‐C several times. Mgateway gave up sending the MT SMS. The MT SMS has been routed to the undelivered MT SMS administration queue.

Final

3 Sent to the SMS‐C

The MT SMS has been sent to the operator SMS‐C. The event 3 is:

- final if no operator notification was requested

- Intermediate if a final notification was requested.

Final/ intermediate

4 Sent Pending The MT SMS has been delivered to the operator SMS‐C and is pending on the operator SMS‐C.

Intermediate

5 Delivered The MT SMS has been successfully delivered to the end‐user’s mobile phone.

Final

6 Not Delivered The MT SMS has been sent to the operator SMS‐C but could not be delivered to the end‐user’s mobile phone.

Final

Event Reason

P4 Explanation of the message status. Please refer to the mGateway Error Codes document to get the list of the mGateway event reasons.

Notification Date

P5 Date of the message changes of status. Default format is:YYYY‐MM‐DDThh:mm:ss (T is a separator). You can also combine any of the following formats:

YYYY or YY

MM

DD

hh

mm

ss

Login P6 Customer’s account that sent the notified SMS

Gateway GW DNS name of the SMS gateway

Port PORT Port value to access the SMS gateway


http://www.netsize.com/sdk/NSO_SMS.html

4.4 HTTP Requests Samples

You define method that shall be used by Netsize to push MO SMS/SRs: GET or POST.

GET

In this method, you receive an URL including:

• your Website address, • the path to access the script page where MOSMS and/or SRs are processed • your script page name; • the parameters related to MO SMS or SRs.

Here is an example of URL transmitted by Netsize for an MO SMS in the HTTP GET method.

http://www.myWebSite.com/Netsize/MO.asp?P1=123456789&P7=%2B33612345678&P3=Hello&GW=fr.netsizeonline.com......

where is

www.myWebSite.com your Web site

Netsize/MO.asp the path to access the script page where MOs and/or SRs are processed

MO.asp the script page

%2B33612345678 the sender phone number

Hello the text of the short message

fr.netsizeonline.com the gateway which has performed the MO Push

...... the other parameters related to the MO Push.

You should receive the message "Hello", identified by the ID 123456789, from the phone number 33612345678, sent through the Netsize French gateway.


POST with Parameters in HTTP Body in XML format

In this method, you define your own template and DTD, which will be used by Netsize to transmit MO SMS/SRs.

4.4.1.1 MO SMS

Here is an example of template and DTD that can be used to transmit MO SMS.

Template DTD

<?xml version="1.0" encoding="iso‐8859‐1"?>

<MO>

<P1>SMSMessageId</P1>

<P2>SMSMessageReceived</P2>

<P3>SMSMessage</P3>

<P4>SMSAliasProcessed</P4>

<P5>SMSAlias</P5>

<P6>SMSSeparator</P6>

<P7>SMSOrigin</P7>

<P8>SMSLargeAccountNumber</P8>

<P9>SMSOperatorMCC</P9>

<P10>SMSOperatorMNC</P10>

<P11>SMSDate</P11>

<P12>SMSRecvDate</P12>

<P13>SMSDelivDate</P13>

<P14>SMSRequestId</P14>

<P15>SMSFirstWord</P15>

<P16>SMSSecondWord</P16>

<P17>SMSSeparator2</P17>

<P18>SMSOriginatedMCC</P18>

<P19>SMSOriginatedMNC</P19>

<P20>SMSMessageTyped</P20>

<P21>SMSImodeStatus</P21>

<P22>SMSTac</P22>

<P23>SMSMOContext</P23>

<P24>SMSBinary</P24>

<P25>SMSSubscriptionAction</P25>

<GW>GatewayAddress</GW>

<PORT>GatewayPort</PORT>

</MO>

<!DOCTYPE MO [

<!ELEMENT MO

(P1,P2,P3,P4,P5,P6,P7,P8,P9,P10,P11,P12,

P13,P14,P15,P16,P17,P18,P19,P20,GW,PORT)>

<!ELEMENT P1 (#PCDATA)>

























<!ELEMENT GW (#PCDATA)>

<!ELEMENT PORT (#PCDATA)>

]>


4.4.1.2 Status Reports (SRs)

Here is an example of template and DTD that can be used to transmit SRs.

Template DTD

<?xml version="1.0" encoding="iso‐8859‐1"?>

<SR>

<P1>NotifId</P1>

<P2>NotifExtId</P2>

<P3>NotifEvent</P3>

<P4>NotifReason</P4>

<P5>NotifDate</P5>

<P6>LOGIN</P6>

<GW>GatewayAddress</GW>

<PORT>GatewayPort</PORT>

</SR>

<!DOCTYPE SR [

<!ELEMENT SR (P1,P2,P3,P4,P5,P6,GW,PORT)>







<!ELEMENT GW (#PCDATA)>

<!ELEMENT PORT (#PCDATA)>

]>


5 Sending WAP Push Service Indication This appendix explains how to use the Netsize OTA HTTP Interface to send WAP Push Service Indication to a mobile phone. The Netsize OTA HTTP Interface enables to format binary SMS messages (non‐text messages).

Note: WAP Push Service Indication (SI) is a WAP address embedded within a specially formatted SMS. WAP Push SI is displayed as an alert message to the end‐user. It gives him the option of connecting directly to a particular URL via the mobile phone WAP browser (if supported).

5.1 Connection Parameters

Parameter Description

Port The connection port should be 38500

Note: If you want to send WAP Push Service Information through a standard (bulk) SMS account, you must make sure that your account login ends with ‘_OTA’ or ‘$’. (For example: netsize_OTA or Netsize$)

5.2 mGateway URLs

The table below lists the URLs that you can use. You may use the nearest access point to send WAP PUSH service information.

Gateway URL

Australia http://wwwau.netsizeonline.com/OTA‐WAPPushSI/Send.asp

Belgium http://wwwbe.netsizeonline.com/OTA‐WAPPushSI/Send.asp

Germany http://wwwde.netsizeonline.com/OTA‐WAPPushSI/Send.asp

France http://wwwfr.netsizeonline.com/OTA‐WAPPushSI/Send.asp

Italy http://wwwit.netsizeonline.com/OTA‐WAPPushSI/Send.asp

Netherlands http://wwwnl.netsizeonline.com/OTA‐WAPPushSI/Send.asp

Spain, Portugal http://wwwes.netsizeonline.com/OTA‐WAPPushSI/Send.asp

Sweden, Norway, Finland, Denmark http://wwwse.netsizeonline.com/OTA‐WAPPushSI/Send.asp

UK, Ireland http://wwwuk.netsizeonline.com/OTA‐WAPPushSI/Send.asp

© 2009 Netsize Sending WAP Push Service Indication 28 / 35

http://wwwau.netsizeonline.com/OTA-WAPPushSI/Send.asp

http://wwwbe.netsizeonline.com/OTA-WAPPushSI/Send.asp

http://wwwde.netsizeonline.com/OTA-WAPPushSI/Send.asp

http://wwwfr.netsizeonline.com/OTA-WAPPushSI/Send.asp

http://wwwit.netsizeonline.com/OTA-WAPPushSI/Send.asp

http://wwwnl.netsizeonline.com/OTA-WAPPushSI/Send.asp

http://wwwes.netsizeonline.com/OTA-WAPPushSI/Send.asp

http://wwwse.netsizeonline.com/OTA-WAPPushSI/Send.asp

http://wwwuk.netsizeonline.com/OTA-WAPPushSI/Send.asp

Input Parameters

Parameter Description Value and/or format Required

sBrokerAddress DNS name or IP address of the gateway to contact Provisioned by Netsize Yes

sBrokerPort IP port of the gateway to contact. Provisioned by Netsize Yes

sEndpointName Account Parameter Provisioned by Netsize Yes

sTimeout Connection timeout Digital value in milliseconds No

sLogin Account Parameter Provisioned by Netsize Yes

sPassword Account Parameter Provisioned by Netsize Yes

sTarget MSISDN of the mobile phone that must receive the message.

Warning: The OTA HTTP Interface supports only one MSISDN per request.

Must be in the international format. Ex. +33xxxxxxxxx for France

Yes

sName Text presented as the message title on the mobile phone

Yes

sUrl URL used to access the service or content The string has to start with http:// or https://

Yes

sID SI identifier. Either you define your own ID (WAP Push reference on the mobile phone) or Netsize will generate automatically a 9 character‐long ID.

Warning: If you send an SI ID that already exists on the handset, the MT will be replaced except if you set the bUseAction parameter to Delete (code 4).

No

bUseAction Activates the parameter Action (set value on “checkbox”) and deactivates for any other value

No

sAction Specifies the action that shall be taken when the SI is received.

Values from 0 to 3 add or update a SI. Value 4 delete an existing SI, which ID is the ID specified above.

Action Code

Signal None 0

Signal Low 1

Signal Medium. Netsize default value

2

Signal High 3

Delete 4

No

sCreation Creation date time. To update an existing SI, you must provide its ID and a creation date time closer than the one used in the existing SI.

Date format: “YYYY/MM/DD hh:mm:ss”

No

sValidity Validity date. SI will be deleted when this validity date expires.

Date format: “YYYY/MM/DD hh:mm:ss”

No

bNotification Activates the SMS notification (set value on “checkbox”) and deactivates for any other value.

No

Warning: The parameters Delay date, SMS_Ext_ID, DISPATCH_PRICE, DISPATCH_OPERATOR, DISPATCH_SHORT_CODE are not supported by the OTA HTTP interface.


5.2.1.1 WAP Push Size Limitations

If you want to send your WAP Push in a single MT message, you shall consider the following:

Note: The parameters ID and ACTION cannot be deactivated.

Max. usable size without optional parameters 112 112 112 112

ID (9-character default ID) x x x x

ACTION x x x x

CREATION DATE x x

VALIDITY DATE x x

Max. usable size with optional parameters 99 89 89 79

Warning: Usable size = WAP Push title + URL (without the http:// or https:// part).


5.3 The Netsize Test Form

Netsize provides you with test forms, which enable you to send HTTP requests, without having to build a whole HTTP request.

URLs are: http://wwwXX.netsizeonline.com/OTA‐WAPPushSI

XX = access point (e.g. ‘au’, ‘fr’. See Access Points list)

In this page, define your MT SMS parameters and click [Send].

An ASP script is automatically generated and displays in the HTTP client browser.


http://wwwxx.netsizeonline.com/OTA-WAPPushSI

5.4 Samples of HTTP Request

The following samples can be used in HTTP GET or HTTP POST. They correspond to a customer who logs to the French Netsize gateway and who has subscribed to main options.

HTTP GET

5.4.1.1 Requests Encoding

If you want to use HTTP GET, all parameters must be URL encoded. For example, ‘+33’ must be encoded as ‘%2B33’.

Character + # ^ / :

Encoded value %2B %23 %5E %2F %3A

5.4.1.2 Request Sample

http://wwwfr.netsizeonline.com/OTA-WAPPushSI/Send.asp?sBrokerAddress=<fr.netsizeonline.com>& sBrokerPort=38500&sTimeout=5000sLogin=<nsglogin>&sPassword=<nsgpassword>&sEndpointName=NSGClientASP%5ENetsize&sTarget=%2B33600000000&sName=Title&sUrl=http://wapserver.wapsite.com/default.wml&sID=123456@&bUseAction=Checkbox&sAction=2&sCreation=2009%2F01%2F31+12%3A30%3A00&sValidity=2010%2F01%2F31+12%3A30%3A00&bNotification=Checkbox&sRequestID=requestID

HTTP POST

Here is an example of HTTP POST request.

POST /OTA-WAPPushSI/Send.asp HTTP/1.1 Host: fr.netsizeonline.com Content-Type: application/x-www-form-urlencoded sBrokerAddress=<fr.netsizeonline.com>&sBrokerPort=38500&sTimeout=5000sLogin=<nsglogin>&sPassword=<nsgpassword>&sEndpointName=NSGClientASP%5ENetsize&sTarget=%2B33600000000&sName=Title&sUrl=http://wapserver.wapsite.com/default.wml&sID=123456@&bUseAction=Checkbox&sAction=2&sCreation=2009%2F01%2F31+12%3A30%3A00&sValidity=2010%2F01%2F31+12%3A30%3A00&bNotification=Checkbox&sRequestID=<Your Request ID>


http://wwwfr.netsizeonline.com/OTA-WAPPushSI/Send.asp?sBrokerAddress

http://wwwfr.netsizeonline.com/OTA-WAPPushSI/Send.asp?sBrokerAddress


5.5 Return Result Page

After receiving and interpreting your HTTP request, Netsize sends an HTTP response message in plain text.

Parameters Returned

Tag Type Description Value example

CODE Long Netsize error code 0

MESSAGE String The error message (presented between quotes) "Success"

REASON String The description of the error message (presented between quotes), when available

““

ID_TICKET Long Netsize ID Ticket 41959155 or ‐1 (if MSISDN has been blacklisted by Netsize)

Example of Return Result

CODE = 0 MESSAGE = "Success" REASON = "" ID_TICKET = 41959155

Glossary

Term Definition

Alias ASCII combination generated by Netsize. An alias is designed to specify the client application to route MO SMS messages to.

ASCII ASCII (American Standard Code for Information Interchange), is a character encoding based on the English alphabet. ASCII codes represent text in computers, communications equipment, and other devices that work with text. Most modern character encodings have a historical basis in ASCII.

Broker Server which receives, stores and forwards messages to client application. It stores the message in a queue until the application is ready to receive it.

DCS DCS stands for Data Coding Scheme. The DCS parameter indicates how the data is encoded within the message: whether the SMS is a text or a binary message, and in case of text messages, which alphabet is used.

Gateway Network point that acts as an entrance to another network. In the network of a company, a computer server acting as a gateway node is often also acting as a proxy server and a firewall server. Gateways also involve the use of routers and switches.

GSM Message Classes

GSM SMS classes are options for the termination of SMS on a mobile phone:

Class Description

0 SMS is displayed directly on the screen (flash SMS)

1 SMS is stored on mobile equipment (default meaning ‐ Mobile Equipment specific)

2 SMS is stored on SIM (SIM ‐ specific message)

3 SMS is stored on terminal equipment (default meaning ‐ Terminal Equipment specific): used for SIM Toolkit and OTA short messages. See standard GSM TS 07.05

Unicode Unicode is an industry standard whose goal is to provide the means by which text of all forms and languages can be encoded for use by computers.

OAdC Short for Originating Address Code. The OAdC corresponds to the telephone number of the SMS sender. Customers use OAdC to display specific data on the mobile phone screen of their end‐users. The OAdC is composed of numeric or alphanumeric characters.

SSL Short for Secure Sockets Layer. SSL is a program layer created to manage the security of message transmissions in a network and to hide the information a web browser and a web server send to each other. A protocol designed to enable secured communications across the Internet, providing privacy, authentication, and message integrity. SSL is used mostly (but not exclusively) in communications between Web browsers and Web servers.

Status Report

A status report (SR) or notification is an option which lets you get information related to the delivery status of the MT message.

Ticket ID Short for Ticket Identifier. ID Number attributed by Netsize to a MT message to enable the customer to track his message and to know the message status.

Legal Information The information supplied in this document is Netsize S.A. sole property and copyright.

It is intended for strictly informational use. It is not binding and might be subject to changes without notice.

Any unauthorized disclosure shall be considered as unlawful.

Netsize™ is protected by French, EEC and international intellectual property laws.

All other trademarks quoted are the sole property of their respective owners.

NETSIZE S.A. 53, Rue Raspail ‐ 92594 Levallois‐Perret ‐ France Tel: +33 (0) 1 41 27 56 00 Fax: +33 (0)1 41 27 57 00 http://www.netsize.com

http://www.netsize.com/

mgateway http interface user guide

Documents

sextensionname agsmsext netsize

sname title

stimeout 5000slogin

slogin login

sendpointname endpointname

spassword password

encodedin hexastring thisparameteristransmittedformosmsformattedinunicode

starget 336xxxxxxxx