Implementation SMS Messaging 1.0

Specifications

• Product Name: LINK Mobility Implementation Guide SMS Messaging
  1.0

• Provider: LINK Mobility

• Functionality: Message delivery, micro payments, location-based
  services

• Compatibility: PC, mobile phone, PDA

• Legal Information: Sole property and copyright of Netsize

Product Usage Instructions

Functional Overview

The LINK Mobility system provides basic functionality for SMS
messages. The SMS Messaging API is dedicated to sending standard
rate MT SMS messages asynchronously.

Sending an SMS Message

To send an SMS message using the LINK Mobility system, follow
these steps:

1. Connect to the service using the provided API.

2. Compose your message according to the GSM character tables
   provided.

3. Send the message asynchronously through the API.

Sending an SMS Message to Multiple Recipients

If you need to send an SMS message to multiple recipients:

1. Utilize the API’s functionality for sending messages to
   multiple numbers simultaneously.

2. Ensure each recipient’s number is correctly formatted.

3. Send the message to all recipients asynchronously.

FAQ

Q: What is the main functionality of the LINK Mobility

system?

A: The main functionality includes sending standard rate MT SMS
messages asynchronously.

Q: How can I send an SMS message using the LINK Mobility

system?

A: You can send an SMS message by connecting to the service
using the provided API, composing your message, and sending it
asynchronously.

LINK Mobility Implementation Guide SMS Messaging 1.0
LINK Mobility provides a service for message delivery, micro payments and location-based services. The platform acts as a transparent, white-label content acquirer and transaction router between Service Providers and Operators. The Service Providers connects to the service using an easily implemented API and LINK Mobility handles all integration with the Operators. The interface is independent of the Consumer’s device type. The device can amongst others be a PC, mobile phone or PDA.
© LINK Mobility, March 10, 2021

Legal Information
The information supplied in this document is the sole property and copyright of Netsize. It is confidential and intended for strictly informational use. It is not binding and might be subject to changes without notice. Any unauthorized disclosure or use shall be considered as unlawful.
NetsizeTM and linkmobilityTM are protected by French, EEC and international intellectual property laws.
All other trademarks quoted are the sole property of their respective owners.
Nothing contained herein shall be construed as conferring any license or right under Netsize patent, copyright, or trademark.
NETSIZE Société anonyme au capital de 5 478 070 euros Siège social :62, avenue Emile Zola92100 Boulogne ­France 418 712 477 R.C.S. Nanterre http://www.Link Mobility.com http://www.linkmobility.com

Transforming Personalized Communications

1

Table of contents
Scope of Document………………………………………………………….. 3
1. Functional Overview ……………………………………………………………………… 4 1.1 Sending an SMS message ……………………………………………………………………………. 4 1.2 Sending an SMS message to multiple recipients …………………………………………… 6
2. Installation…………………………………………………………………………………… 7 2.1 Interoperability…………………………………………………………………………………………….. 7 2.2 Web service…………………………………………………………………………………………………. 7 2.3 Security……………………………………………………………………………………………………….. 8
3. SMS message integration with LINK Mobility……………………………………… 8 3.1 Sending SMS messages ………………………………………………………………………………. 9 3.1.1 Operation comparison ……………………………………………………………………………… 9 3.1.2 Handling of optional element values …………………………………………………………. 9 3.2 Optional Features ………………………………………………………………………………………. 10 3.2.1 MSISDN Correction ………………………………………………………………………………… 10 3.2.2 Character Replacement ………………………………………………………………………….. 11 3.3 Send request ……………………………………………………………………………………………… 11 3.4 Send text request ………………………………………………………………………………………. 15 3.5 Send response …………………………………………………………………………………………… 18 3.6 Response codes ………………………………………………………………………………………… 19 3.7 Read timeout……………………………………………………………………………………………… 20 3.8 Receiving delivery report…………………………………………………………………………….. 20 3.9 Service Provider acknowledgement…………………………………………………………….. 23 3.10 Retry ……………………………………………………………………………………………………… 24 3.11 A comment on SMS message contents …………………………………………………… 26
4. Implementation examples…………………………………………………………….. 27 5. GSM character tables ………………………………………………………………….. 28
5.1 GSM default alphabet table (7-bit) ………………………………………………………………. 28 5.2 GSM default alphabet extension table (7-bit)……………………………………………….. 29 6. Acronyms and abbreviations…………………………………………………………. 30 7. References ………………………………………………………………………………… 30

Transforming Personalized Communications

2

Scope of Document
This document describes how the Service Provider sends SMS messages via LINK Mobility. It is intended for technical architects and designers who implement the services of the Service Provider.

Transforming Personalized Communications

3

1. Functional Overview
The LINK Mobility system provides the following basic functionality for SMS messages:
· Sending Mobile Terminated (MT) SMS messages, such as text or binary (e.g. WAP Push) premium and standard rate messages.
· Receiving delivery reports for submitted MT messages. · Receiving Mobile Originated (MO) SMS messages, premium and standard
rate.
The SMS Messaging API is dedicated to sending standard rate MT SMS messages. The API sends all SMS messages asynchronously, enabling features such as:
· “Fire-and-forget” ­ the Service Provider wants to have more predictable response times and does not want to wait for the result from the Operator.
· Retry functionality ­ LINK Mobility will resend the message if the Operator has temporary problems.
Further information about receiving MO SMS messages or sending premium MT SMS messages can be found ini. A utility SMS API is also available, containing a number of simplified operations for sending SMS messages, e.g. WAP push.
More information about these APIs is provided by LINK Mobility support upon request.
1.1 Sending an SMS message

Service Provider

Netsize

1. Send MT message

Consumer

2. Return message ID

3. Submit SMS message

4. Deliver delivery report

5. Send delivery report

Transforming Personalized Communications

4

The basic flow for sending SMS messages is described as follows:
1. The Service Provider makes a request to send an SMS message to a recipient via the LINK Mobility system.
2. A message ID is returned to the Service Provider. This ID can be used for e.g. correlate the message with the correct delivery report.
3. LINK Mobility handles routing and delivers the SMS message to the addressed Consumer.
Step 4 and 5 are executed if the Service Provider requested a delivery report in step 1.
4. A delivery report is triggered, e.g. when the SMS message is delivered to the Consumer’s device.
5. The delivery report is sent to the Service Provider. The report contains the same message ID as returned in step 2.
Alternative flow: Invalid request
If the supplied parameters or user credentials in the request (step 1) are invalid an error is returned to the Service Provider. The error indicates the reason for the rejection and the flow ends. No message ID is returned.

Transforming Personalized Communications

5

1.2 Sending an SMS message to multiple recipients

Service Provider

Netsize

1. Send MT message

Consumer

2. Return message IDs

3.1. Submit SMS message #1

3.2. Submit SMS message #2

3.n. Submit SMS message #n

5.1. Send delivery report #1 5.2. Send delivery report #2 5.n. Send delivery report #n

4.1. Deliver delivery report #1 4.2. Deliver delivery report #2 4.n. Deliver delivery report #n

The LINK Mobility system supports the sending of a standard rate SMS message to multiple recipients in a distribution list. The basic flow is described as follows:
1. The Service Provider makes a request to send a standard rate SMS message to multiple recipients via the LINK Mobility system.
2. The LINK Mobility system validates the SMS message syntax, the recipients and routes each SMS message before returning the message IDs to the Service Provider.
3. LINK Mobility submits one SMS message to each of the addressed Consumers. The LINK Mobility system will try to resend the SMS message when receiving an error response classified as temporary. LINK Mobility will try to resend the SMS message until it has expired or the LINK Mobility maximum retry limit has been reached.
Step 4 and 5 are executed if the Service Provider requested a delivery report in step 1.
4. A delivery report is triggered, e.g. when the SMS message is delivered to the Consumer’s mobile station.

Transforming Personalized Communications

6

5. The delivery report is sent to the Service Provider, containing the same message ID as returned in step 2.
It is highly recommended requesting delivery reports to verify that the Consumers have received their SMS message successfully.
2. Installation
LINK Mobility provides an API exposed as a web service with a SOAP interfaceii. The SOAP protocol and the Link Mobility server are independent of the platform used by the Service Provider, although the installation of the SOAP tools could be different. The web service API is described in WSDLiii.
For those not familiar with web services, LINK Mobility also provides a set of Java classes generated from the web service WSDL description. These classes are provided by Link Mobility support upon request.
2.1 Interoperability
Even though web services are interoperable across different platforms in theory, it sometimes happens that the server framework and client framework are incompatible. To ensure interoperability across platforms, LINK Mobility web services are built and verified according to the recommendations of the Web Services Interoperability Organization, WS-Iiv.
WS-I requires a web service to support UTF-8 and UTF-16-character sets. Link Mobility supports both, but it is recommended to use UTF-8.
All LINK Mobility web services have been verified on the following platforms:
· Java · .NET · PHP · Perl · ASP · Ruby · Python
2.2 Web service

Transforming Personalized Communications

7

The web service URL and the location of the WSDL file is provided by LINK Mobility support upon request.
2.3 Security
Sending requests
For authentication, the user ID and password of the Service Provider are submitted in every web service invocation. It is the responsibility of the Service Provider to keep this user ID and password protected.
For connection security, LINK Mobility strongly recommend the usage of HTTPS when accessing the LINL Mobility web services. The LINK Mobility server certificate is signed by Thawte Server CA.
Additionally, it is recommended to use the LINK Mobility firewall for blocking unknown IP addresses from accessing the account of the Service Provider. Contact LINK Mobility support for further information.
Please note that HTTP is supported for backward compability reasons only and will be removed in the future.
Receiving delivery reports
For authentication, it is recommended that the Service Provider uses: · Basic authentication for access towards their web server. · A firewall, ensuring that only requests from LINK Mobility are allowed.
For connection security, it is recommended that the Service Provider uses: · HTTPS for access towards their web server.
HTTPS on the Service Provider premises can be used seamlessly, providing that the certificate of the web server is signed by a root CA certificate included in the list of trusted CA certificatesv.
3. SMS message integration with LINK Mobility

Transforming Personalized Communications

8

3.1 Sending SMS messages
The Service Provider can send SMS messages to their Consumers via LINK Mobility, using the SMS web service API as described in this chapter.
Implementation examples on how to integrate with LINK Mobility in various programming languages can be found in chapter 4.
3.1.1Operation comparison
The SMS Messaging API defines two different operations: a send request and a send text request. This subsection gives an overview of the functionality provided by the two operations and high-lights important differences.
The send request is targeted towards more advanced use cases where the Service Provider have total control of the message formatting including the user data header. It supports GSM Default, Unicode, and binary Data Coding Schemes. The Service Provider can send concatenated messages, but the preparation of the user data and user data header must be made by the Service Provider and the message must be sent by means of multiple send requests towards LINK Mobility.
The send text request assumes that the message text contains characters from the GSM default alphabet including the extension table or Unicode alphabet. The Data Coding Scheme is automatically detected by LINK Mobility by examining the contents of the message text. Automatic concatenation of a message into multiple messages is supported up to a by the Service Provider specified maximum limit.
Concatenation might be necessary if the message text length exceeds the max length supported by the Data Coding Scheme used by the message text.
3.1.2Handling of optional element values
Kindly observe that for interoperability purposes, all XML elements in the requests and responses are mandatory according to the XML definition, i.e. needs to be present. The notation for specifying an optional value is:
· For integer values: -1

Transforming Personalized Communications

9

· For string values: #NULL#
It is important to note that values of ignored elements must be set to the values stated in the corresponding comment until the element is supported. This is to ensure forward compatibility towards LINK Mobility.

3.2 Optional Features 3.2.1MSISDN Correction
MSISDN correction is an optional feature that can be enabled by LINK Mobility support if requested.

This feature will correct destination addresses and align them to the required E.164 format. In addition of format correction, the system may also perform market specific functionality such as translating international French numbers to correct DOM-TOM (départements et territoires d’outre-mer) numbers when applicable.

Below are several examples of corrections:

Submitted Destination Address +46(0)702233445 (0046)72233445 +460702233445 46(0)702233445 46070-2233445 0046702233445 +46(0)702233445aaa 336005199999

Corrected Destination Address 46702233445 46702233445 46702233445 46702233445 46702233445 46702233445 46702233445 2626005199999 (French number translated to a DOM-TOM number)

Additionally, it is possible to allow national phone numbers for a selected market. When this feature is enabled any international numbers for other markets must be sent with an initial `+’ sign to distinguish them from the selected market.

Below are several examples of corrections done when using Sweden (country code 46) as default market for national numbers.

Submitted Destination Address 0702233445 070-2233 445 070.2233.4455 460702233445 +460702233445 +458022334455 45802233445

Corrected Destination Address 46702233445 46702233445 46702233445 46702233445 46702233445 458022334455 Invalid since the `+’ sign is missing

Transforming Personalized Communications

10

Note that the corrected MSISDN will be used by LINK Mobility and it will be returned in the delivery reports.
Please contact LINK Mobility support for more information.
3.2.2 Character Replacement
Character replacement is an optional feature that can be enabled by LINK Mobility support if requested.
This feature will translate non-GSM alphabet characters in the user data (SMS text) to equivalent GSM alphabet characters when the DCS is set to “GSM” (17). For example “Seqüência de teste em Português” will be translated to “Seqüencia de teste em Portugues”.
Please contact LINK Mobility support for more information.
3.3 Send request
The send request element is formatted as follows:

Transforming Personalized Communications

11

The send request child elements are handled by LINK Mobility as follows:

Element correlationId
originatingAddress

Type String
String

M/O/I* Default Value^

O

­

O

System will set

value if

configured and

supported.

Max length 100
16

Description
Correlation ID to keep track of SOAP requests and responses, according to WS-I recommendation. The server echoes the provided value. Additionally, the correlation ID can be used as an external ID since it will be included in DR and stored with the transaction data. Note that restriction regarding allowed characters may apply. The originating address for the outgoing SMS message. Type of originating address is defined by the orginatorTON parameter. Short number max length is 16. Alpha numeric sender is limited to GSM default Alphabet with max length 11 characters.

Transforming Personalized Communications

12

originatorTON

Integer O

destinationAddress String

M

userData userDataHeader

String

O

String

O

DCS

integer O

PID

integer O

relativeValidityTime integer O

deliveryTime

String

O

System will set value if configured and supported.
­
Empty message No user data header 17 0 172800 (48 hours) Immediately

1
40(*)
280 280 3 3 9 25

MSISDN sender max length is 15 (using same format as the destinationAddress element). Can be set to #NULL# when originatingAddress and originatingTON is selected by the system. This function is market and configuration dependant. For further information, please contact LINK Mobility support. Behaviour may vary with Operator integrations. The originating address’ type of number (TON): 0 ­ Short number 1 ­ Alpha numeric (max length 11) 2 ­ MSISDN Can be set to -1 when originatingAddress and originatingTON will be selected by the system. This function is market and configuration dependant. For further information, please contact LINK Mobility support. Behaviour may vary with Operator integrations. The MSISDN that the SMS message should be sent to, starting with country code. Example: 46762050312. For some markets (where the Consumer MSISDN must be obfuscated) this value can also be an alphanumeric alias, prefixed with”#”.
Sending SMS message to multiple recipients is supported by providing a distribution list of semi-colon separated MSISDNs (e.g. 46762050312;46762050313). The recipients must be unique within a list and the distribution list is limited to 1000 entries. (*) Max length value does not apply for distribution lists. The SMS message content. User Data Header together with the User Data can contain up to 140, i.e. 280 when hex-encoded, octets. This parameter is always hex-encoded. Data coding scheme. Behaviour may vary with Operator integrations. Protocol ID. Behaviour may vary with Operator integrations. Relative validity time in seconds (relative to the time for the submission to LINK Mobility). Behaviour may vary with Operator integrations. The SMS message can be delivered with delayed delivery time. Format: yyyy-MM-dd HH:mm:ss Z, example: 2000-01-01 01:01:01 ­0000.

Transforming Personalized Communications

13

statusReportFlags

integer O

0

accountName

String

O

According to

account

configuration

referenceId serviceMetaData

String

O

­

String

O

No value set

campaignName

String

O

­

username

String

M

­

password

String

M

­

• M = Mandatory, O = Optional, I = Ignored.

1
50
150 1000 50 64 64

Behaviour may vary with Operator integrations. Deliver report request: 0 ­ No delivery report 1 ­ Delivery report requested 9 ­ Server delivery report requested (LINK Mobility do not forward the report to the Service Provider but makes it available in reports etc.) This field allows LINK Mobility to route SMS messages in a flexible manner, which may or may not be Service Provider specific. For normal usage, #NULL# should be supplied. Note: Usage of this field must be provisioned by LINK Mobility. For this API usually a message ID of a web opt-in ordering MO SMS message. The service meta data. Set to #NULL# if not used or not supported by the market. This is market specific information. For further information, please contact LINK Mobility support. The LINK Mobility transactions are tagged with this name. It is used to group transactions in LINK Mobility reports. Set to #NULL# if not used. The username of the Service Provider, provided by LINK Mobility. The password of the Service Provider, provided by LINK Mobility.

^ The default value is used if an element value is set to null.

Transforming Personalized Communications

14

3.4 Send text request
The send request element is formatted as follows:

The Send text request child elements are handled by LINK Mobility as follows:

Element correlationId

Type String

originatingAddress String

M/O/I* Default Value^

O

­

O

System will set

value if

configured and

supported.

Max length 100
16

Description
Correlation ID to keep track of SOAP requests and responses, according to WS-I recommendation. The server echoes the provided value. Additionally, the correlation ID can be used as an external ID since it will be included in DR and stored with the transaction data. Note that restriction regarding allowed characters may apply. The originating address for the outgoing SMS message. Type of originating address is defined by the orginatorTON parameter.

Transforming Personalized Communications

15

originatorTON

Integer O

destinationAddress String

M

messageText

String

M

maxConcatenatedM integer O essages

PID

integer O

relativeValidityTime integer O

System will set value if configured and supported.
­
Empty message 3 0 172800 (48 hours)

1
40(*)
39015 3 3 9

Short number max length is 16. Alpha numeric sender is limited to GSM default Alphabet with max length 11 characters. MSISDN sender max length is 15 (using same format as the destinationAddress element). Can be set to #NULL# when originatingAddress and originatingTON is selected by the system. This function is market and configuration dependant. For further information, please contact LINK Mobility support. Behaviour may vary with Operator integrations. The originating address’ type of number (TON): 0 ­ Short number 1 ­ Alpha numeric (max length 11) 2 ­ MSISDN Can be set to -1 when originatingAddress and originatingTON will be selected by the system. This function is market and configuration dependant. For further information, please contact LINK Mobility support. Behaviour may vary with Operator integrations. The MSISDN that the SMS message should be sent to, starting with country code. Example: 46762050312. For some markets (where the Consumer MSISDN must be obfuscated) this value can also be an alphanumeric alias, prefixed with”#”.
Sending SMS message to multiple recipients is supported by providing a distribution list of semi-colon separated MSISDNs (e.g. 46762050312;46762050313). The recipients must be unique within a list and the distribution list is limited to 1000 entries. (*) Max length value does not apply for distribution lists. The SMS message content. The Data Coding Scheme is auto detected. Supported schemes are GSM 7-bit, or UCS-2. A value between 1 and 255 where the value defines how many concatenated messages that are acceptable. If the number of concatenated messages exceeds this value the request fails. Protocol ID. Behaviour may vary with Operator integrations. Relative validity time in seconds (relative to the time for the submission to LINK Mobility).

Transforming Personalized Communications

16

deliveryTime

String

O

Immediately

statusReportFlags

Integer O

0

accountName

String

O

According to account configuration

referenceId serviceMetaData

String

O

String

O

­ No value set

campaignName

String

O

­

username

String

M

­

password

String

M

­

• M = Mandatory, O = Optional, I = Ignored.

25
1
50
150 1000 50 64 64

Behaviour may vary with Operator integrations. The SMS message can be delivered with delayed delivery time. Format: yyyy-MM-dd HH:mm:ss Z, example: 2000-01-01 01:01:01 ­0000. Behaviour may vary with Operator integrations. Deliver report request: 0 ­ No delivery report 1 ­ Delivery report requested 9 ­ Server delivery report requested (LINK Mobility do not forward the report to the Service Provider but makes it available in reports etc.) This field allows LINK Mobility to route SMS messages in a flexible manner, which may or may not be Service Provider specific. For normal usage, #NULL# should be supplied. Note: Usage of this field must be provisioned by LINK Mobility. For this API usually a message ID of a web opt-in ordering MO SMS message. The service meta data. Set to #NULL# if not used or not supported by the market. This is market specific information. For further information, please contact LINK Mobility support. The LINK Mobility transactions are tagged with this name. It is used to group transactions in Link Mobility reports. Set to #NULL# if not used. The username of the Service Provider, provided by LINK Mobility. The password of the Service Provider, provided by LINK Mobility.

^ The default value is used if an element value is set to null.

Transforming Personalized Communications

17

3.5 Send response
The send response element is formatted as follows:

The send response is used for both send request and send text request.

The send response child elements are handled by LINK Mobility as follows:

Element correlationId messageDetails
responseCode

Type
string list of messa geDetai l integer

M/O/I* O M
M

Default Value^ ­ ­
­

Max length 100 1000 elements
5

responseMessage string M

­

200

• M = Mandatory, O = Optional, I = Ignored. ^ The default value is used if an element value is set to null.

Description
Echoed request correlation ID. List of LINK Mobility unique message IDs and response code for successful or partial successful transaction, empty list on failure. LINK Mobility response code 0 indicates successful transaction. Response code 50 indicates partly successful transaction; at least one message was sent to a recipient, see messageDetails for individual response codes per recipient. Any other error code indicates complete failure to send. See separate table for complete list of response codes. Response textual description, e.g. error text.

Transforming Personalized Communications

18

The messageDetail child elements are handled by LINK Mobility as follows:

Element
destinationAddress messageIds

Type
string string

M/O/I*
M M

Default Value^
­ ­

responseCode

integer M

­

responseMessage

String

M

­

• M = Mandatory, O = Optional, I = Ignored.

Max length 40 5864
5
200

Description
Echoed request destinationAddress. LINK Mobility unique message ID for successful transaction, empty string on failure. Several message IDs are returned if the message is concatenated. The message IDs are semi-colon separated. For certain error conditions an empty list is returned. LINK Mobility response code 0 indicates successful transaction. See separate table for complete list of response codes. NOTE: The response code 0 indicates that the message is scheduled for delivery, not that successful delivery has been made. Response textual description, e.g. error text.

^ The default value is used if an element value is set to null.

3.6 Response codes
The following response codes can be returned in the send response:

Code 0 1 2 3 4 5 6 7 8 9

Text Success Invalid login or un-authorized API usage Consumer is blocked by Link Mobility Operation is not provisioned by Link Mobility The consumer is unknown to Link Mobility Consumer has blocked this service in Link Mobility The originating address is not supported Alpha originating address not supported by account MSISDN originating address not supported GSM extended not supported

Description Successfully executed. Incorrect username or password or Service Provider is barred by LINK Mobility. The Consumer is blocked by LINK Mobility.
The operation is blocked for the Service Provider.
The Consumer is unknown to LINK Mobility. Or if alias was used in the request; alias not found. The Consumer has blocked this service in Link Mobility.
The originating address is not supported.
The alpha originating address is not supported by account.
The MSISDN originating address not supported.
GSM extended not supported.

Transforming Personalized Communications

19

10

Unicode not supported

Unicode not supported.

11

Status report not supported

Status report not supported.

12

Required capability not

The required capability (other than the above) for sending the message

supported

is not supported.

13

The content provider max

The Service Provider is sending the SMS messages to LINK Mobility too

throttling rate is exceeded

fast.

14

Protocol ID not supported by

Protocol ID not supported.

account

15

Message concatenation limit

The number of concatenated messages exceeds the max number

exceeded

requested.

16

Could not route message

LINK Mobility was unable to route the message.

17

Prohibited time period

Not allowed to send message during time period

18

Too low balance on service

Service provider is blocked due to Too low balance

provider account

50

Partial success

Partial success when sending an SMS message to multiple recipients.

99

Internal server error

Other LINK Mobility error, contact LINK Mobility support for more

information.

100

Invalid destination address

The destination address (MSISDN, or alias) is invalid.

102

Invalid referenced (linked) ID

The reference ID is invalid, maybe the reference ID is already used, too

old or unknown.

103

Invalid account name

The account name is invalid.

105

Invalid service meta data

The service meta data is invalid.

106

Invalid originating address

The originating address is invalid.

107

Invalid alphanumeric originating The alphanumeric originating address is invalid.

address

108

Invalid validity time

The validity time is invalid.

109

Invalid delivery time

The delivery time is invalid.

110

Invalid message content/user

The user data, i.e. the SMS message, is invalid.

data

111

Invalid message length

The SMS message length is invalid.

112

Invalid user data header

The user data header is invalid.

113

Invalid data coding scheme

The DCS is invalid.

114

Invalid protocol ID

The PID is invalid.

115

Invalid status report flags

The status report flags are invalid.

116

Invalid TON

The originator TON is invalid.

117

Invalid campaign name

The campaign name is invalid.

120

Invalid limit for maximum

The maximum number of concatenated messages is invalid.

number of concatenated

messages

121

Invalid msisdn originating

The MSISDN originating address is invalid.

address

122

Invalid correlation ID

The correlation ID is invalid.

3.7 Read timeout
Since invocations on the Link Mobility APIs normally results in LINK Mobility invoking other external systems, such as Operator payment systems and SMSCs, it is recommended that the Service Provider uses a rather high read timeout. A read timeout of 10 minutes for HTTP requests is advised. Using this timeout will handle even the most extensive read time out cases.

3.8 Receiving delivery report
The Service Provider can, if provisioned, request SMS message delivery reports or delivery notifications for the MT messages sent. These reports are triggered in the

Transforming Personalized Communications

20

Operator SMSC when the MT message is either delivered to the targeted Consumer or deleted, e.g. expired or, for some reason, not routable. Only final status of the SMS message is reported to the Service Provider, i.e. delivered or deleted. Only one report per MT message is generated. With the deleted status, a reason code may apply. This reason code specifies the reason for the SMS message not being delivered.

The reports are routed through Link Mobility and sent to the Service Provider using the HTTP protocol.

To receive reports, the Service Provider needs to implement for example a Java Servlet or an ASP.NET page. Both of these receive HTTP GET or POST requests.

Parameters

The request includes the following parameters:

Parameter MessageId DestinationAddress StatusCode
TimeStamp
Operator
ReasonCode

Type string string integer
string
string
integer

M/O /I*

Default Value

Max length

Description

M

­

22

The message ID of the MT message

that this report corresponds to.

M

­

40

The Consumer’s MSISDN, i.e. the

destination address of the original MT

message.

M

1

Status code indicates the status of the

MT message.

Applicable status codes are:

0 ­ Delivered

2 – Deleted (reason code applies)

M

­

20

Time indicating when the delivery

report was received by LINK Mobility.

The time zone of the timestamp is CET

or CEST (with summer time as defined

for the EU).

Format: yyyyMMdd HH:mm:ss.

M

­

100

The name of the Operator used when

sending the SMS message or the

account name used when sending the

SMS message.

A list of available Operators is provided

by LINK Mobility support.

O

­

3

Reason code indicates why the

message ended up in the status

deleted.

Applicable reason codes are:
100 ­ Expired 101 ­ Rejected 102 ­ Format error 103 ­ Other error 110 ­ Subscriber unknown 111 ­ Subscriber barred 112 ­ Subscriber not provisioned 113 ­ Subscriber unavailable 120 ­ SMSC failure

Transforming Personalized Communications

21

OperatorTimeStamp

string

O

­

StatusText

string

O

­

CorrelationId

string

O

­

OperatorNetworkCode

integer O

­

• M = Mandatory, O = Optional, I = Ignored.

121 ­ SMSC congestion

122 ­ SMSC roaming

130 ­ Handset error

131 ­ Handset memory exceeded

Behavior may vary with Operator

integrations.

20

Time indicating when the report was

triggered in the SMSC of the Operator

(if provided by the Operator).

The time zone of the timestamp is CET

or CEST (with summer time as defined

for the EU).

Format: yyyyMMdd HH:mm:ss.

255

Placeholder for additional information

from the Operator, e.g. clear text

description of the status/reason.

Behavior may vary with Operator

integrations.

100

The correlation ID provided in the

SendRequest or SendTextRequest.

6

The Mobile Network Code (MCC +

MNC) of the Operator.

The Service Provider has to provide LINK Mobility with the target URL for delivery reports (optionally including credentials for HTTP basic authentication).

The Service Provider can choose which preferred HTTP method to use:

· HTTP POST (recommended) · HTTP GET.

Example using HTTP GET (successfully delivered):
https://user:password@www.serviceprovider.com/receivereport? MessageId=122&DestinationAddress=46762050312&Operator=Vodafone&TimeSt amp=20100401%2007%3A47%3A44&StatusCode=0
Example using HTTP GET (not delivered, the Operator has supplied timestamp for the event):
https://user:password@www.serviceprovider.com/receivereport?MessageId=123 &DestinationAddress=46762050312&Operator=Vodafone&OperatorTimeStamp=2 0100401%2007%3A47%3A59&TimeStamp=20100401%2007%3A47%3A51&Status Code=2&StatusText=Delivery%20failed&ReasonCode=10

Transforming Personalized Communications

22

The parameters are URL encodedvi.
Character encoding:
The Service Provider can choose which preferred character encoding to use: · UTF-8 (recommended) · ISO-8859-1.
3.9 Service Provider acknowledgement
The Service Provider should acknowledge each delivery report. The acknowledgement can be positive, i.e. delivery report successfully received, or negative, i.e. failure.
Please note: LINK Mobility has a read timeout for acknowledgments of 30 seconds for delivery reports. A timeout will trigger a delivery retry (if retry enabled) or a cancellation of the delivery (if retry disabled). This means that the Service Provider application must ensure quick response times, especially during high load.
It is highly recommended to acknowledge the delivery report towards LINK Mobility before processing it.
The rule for positive and negative acknowledgement is described as follows:
Positive acknowledgement, ACK, delivery report delivered: HTTP 200 range response code in combination with the following XML formatted content: