LINK Mobility Implementation Guide REST API SMS User Guide

LINK Mobility Implementation Guide REST API SMS

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.

LINK Mobility provides a RESTful API that can be used to access LINK Mobility services such as sending SMS. This API is designed to be easy to use and compatible with all modern languages and frameworks. Using the language of your choice your application can use the Link Mobility REST API to implement powerful messaging and payment capabilities

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

Netsize™ and linkmobility™ 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.LinkMobility.com
http://www.linkmobility.com

Scope of Document

This document describes how the Service Provider uses the LINK Mobility REST API for SMS. It is intended for technical architects and designers who implement the services of the Service Provider.

1. Basic Usage

It is very easy to send an SMS. You send an HTTP request to LINK Mobility which can be accomplished using just a web browser.

2. 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 REST 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.

2.1 Sending an SMS message

Service Provider                    Netsize               Consumer

1. Send MT message
2. Return message ID
3. Submit SMS message
4. Deliver delivery report
5. Send delivery report

The basic flow for sending an SMS messages is described as follows:

The Service Provider makes a request to send an SMS message to a recipient via the LINK Mobility system.

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.

LINK Mobility handles routing and delivers the SMS message to the addressed Consumer.
A delivery report is triggered, e.g. when the SMS message is delivered to the Consumer’s device.

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 are invalid an error is returned to the Service Provider. The error indicates the reason for the rejection and the flow ends. No message IDs are returned.

3. Endpoint

The SMS resource is accessed using the path:
/restapi/v1/sms
Example URL
https://europe.ipx.com/restapi/v1/sms
For connection security the LINK Mobility REST API is only accessible over HTTPS.
The Link Mobility server certificate is signed by Thawte Server CA.

4. Operations

The SMS service provides the following operations:

4.1 Send

The send operation is used to send an SMS to a single recipient.

This operation is intended for both basic and advanced users. In the simplest case, only destination address, and the message text are required to deliver an SMS. LINK Mobility will detect the Data Coding Scheme and perform automatic concatenation of a message into multiple message parts if necessary.

For advanced usage, the Service Provider can use optional parameters for total control of the message formatting including the user data header.

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.

5. Authentication

Username and password are submitted in every request using HTTP Basic Authentication Scheme.

https://www.w3.org/Protocols/HTTP/1.0/spec.html#BasicAA

Credentials are sent in an Authorization header in the HTTP request. The client constructs the header field as described here:

https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side

For example, if the username is john and changeme is the password then the resulting Authorization header is:

Authorization: Basic am9objpjaGFuZ2VtZSA=

As a fall-back the username and password can be submitted as request parameters. This is only recommended for clients that do not support Basic Auth.

6. Submitting a request

6.1 Query string

Request parameters are submitted as a query string containing name/value pairs. The query string is encoded using Percent Encoding (URL encoding).

http://www.w3schools.com/tags/ref_urlencode.asp

For example, Hello World! is encoded as Hello+World%21.

6.2 Mandatory request parameters

to, starting with country code. Example: 46123456789.
For some markets (where the Consumer MSISDN must be obfuscated) this value can also be an alphanumeric alias, prefixed with“#”.
messageText| 1600| The SMS message content.

6.3 Optional request parameters (for advanced usage)

message. Type of originating address is defined by the originatorTON parameter.
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 omitted when originatingAddress and originatingTON are selected by the system. This function is market and configuration dependent.
Behaviour may vary with Operator integrations.
originatorTON| 1| The originating address’ type of number (TON):
0 – Short number
1 – Alpha numeric (max length 11)
2 – MSISDN
Can be omitted when originatingAddress and originatingTON will be selected by the system. This function is market and configuration dependant.
Behaviour may vary with Operator integrations.
userDataHeader| 280| 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.
DCS| 3| Data coding scheme.
Behaviour may vary with Operator integrations.
PID| 3| Protocol ID.
Behaviour may vary with Operator integrations.
relativeValidityTime| 6| Relative validity time in seconds (relative to the time for the submission to LINK Mobility). Max value is 604800 (7 days) and the default is 48 hours.
Behaviour may vary with Operator integrations.
deliveryTime| 20| Timestamp when SMS message should be delivered (delayed delivery time). See section on date time format.
statusReportFlags| 1| Deliver report request:
0 – No delivery report (default)
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.)
campaignName| 50| The LINK Mobility transactions are tagged with this name. It is used to group transactions in Link Mobility reports.
maxConcatenatedMessages| 1| A value between 1 and 10 which defines how many concatenated messages that are allowed. Default is 3.
correlationId| 100| ID provided by Service Provider that will be echoed in Delivery Report.
username| 100| Provided as an alternative to HTTP Basic Authentication.
password| 100| Provided as an alternative to HTTP Basic Authentication.

6.4 HTTP Request Methods

For maximum interoperability, the API supports both HTTP GET and POST request methods. No other HTTP methods are allowed.

6.4.1 GET

The encoded query string is appended to the URL.

GET
https://europe.ipx.com/restapi/v1/sms/send?destinationAddress=461234
56789&messageText=Hello+World%21
Authorization: Basic am9objpjaGFuZ2VtZSA=

6.4.2 POST

The encoded query string is submitted in the HTTP request message body. Content-Type is application/x-www-form-urlencoded.

POST https://europe.ipx.com/restapi/v1/sms/send
Host: europe.ipx.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic am9objpjaGFuZ2VtZSA=
Content-Length: 57

destinationAddress=46123456789&messageText=Hello+World%21

6.5 Date and time

Parameters in the REST API representing date and time are always in UTC time zone (Coordinated Universal Time). Timestamps are represented as a string with this exact format:
2017-04-25T23:20:50Z
This represents 20 minutes and 50 seconds after the 23rd hour of April 25th, 2017 in UTC.

7. Response message

After receiving and interpreting a request message the API responds with a HTTP response message.

7.1 HTTP status code

The REST API always returns HTTP status code 200 OK for processed requests. The message body contains a parameter responseCode that is used to determine the exact outcome.

7.2 Message body

The message body consists of JSON describing the outcome of the request.
http://json.org/
Link Mobility JSON complies with the Google JSON Style Guide.
https://google.github.io/styleguide/jsoncstyleguide.xml

7.3 Response parameters

(Refer to date/time format section).
traceId| 36| Link Mobility internal identifier. Used for support and troubleshooting.
messageIds| 10 x 36| Array of LINK Mobility unique message IDs for each successful message (multiple message IDs are returned if the message is concatenated).
Omitted in case of failure.

7.4 Example responses

Success

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 144
Date: Thu, 15 Sep 2016 13:20:31 GMT
{“responseCode”:0,”responseMessage”:”Success”,”timestamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}

Here is the same JSON formatted for readability:

{
“ responseCode “:0,
“ responseMessage “:”Success”,
“ timestamp “:”2016-0915T13:20:31Z”,
“ traceId “:”f678d30879fd4adc25f2”,
“ messageIds “:[“1-4850879008”] }

Failure

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 148
Date: Thu, 15 Sep 2016 13:20:31 GMT
{“responseCode”:1,”responseMessage”:” Invalid login or un-authorized API usage”,”timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}

Success

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 144
Date: Thu, 15 Sep 2016 13:20:31 GMT
{“responseCode”:0,”responseMessage”:”Success”,”timestamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}

Here is the same JSON formatted for readability:

{
“ responseCode “:0,
“ responseMessage “:”Success”,
“ timestamp “:”2016-0915T13:20:31Z”,
“ traceId “:”f678d30879fd4adc25f2”,
“ messageIds “:[“1-4850879008”] }

Failure

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 148
Date: Thu, 15 Sep 2016 13:20:31 GMT
{“responseCode”:1,”responseMessage”:” Invalid login or un-authorized API usage”,”timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}

7.5 Response codes

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

Service Provider is barred by LINK Mobility.
2| Consumer is blocked by Link Mobility| The Consumer is blocked by LINK Mobility.
3| Operation is not provisioned by LINK Mobility| The operation is blocked for the Service Provider.
4| The consumer is unknown to LINK Mobility | The Consumer is unknown to LINK Mobility.
Or if alias was used in the request; alias not found.
5| Consumer has blocked this service in LINK Mobility| The Consumer has blocked this service in LINK Mobility.
6| The originating address is not supported| The originating address is not supported.
7| Alpha originating address not supported by account| The alpha originating address is not supported by account.
8| MSISDN originating address not supported| The MSISDN originating address not supported.
9| GSM extended not supported| GSM extended not supported.
10| Unicode not supported| Unicode not supported.
11| Status report not supported| Status report not supported.
12| Required capability not supported| The required capability (other than the above) for sending the message is not supported.
13| The content provider max throttling rate is exceeded| The Service Provider is sending the SMS messages to LINK Mobility too fast.
14| Protocol ID not supported by account| Protocol ID not supported.
15| Message concatenation limit exceeded| The number of concatenated messages exceeds the max number requested.
16| Unable to 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 provider account| Service provider is blocked due to Too low balance
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 address| The alphanumeric originating address is invalid.
108| Invalid validity time| The validity time is invalid.
109| Invalid delivery time| The delivery time is invalid.
110| Invalid message content/user data| The user data, i.e. the SMS message, is invalid.
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 number of concatenated messages| The maximum number of concatenated messages is invalid.
121| Invalid msisdn originating address| The MSISDN originating address is invalid.
122| Invalid correlation ID| The correlation ID is invalid.

8. Optional features

8.1 MSISDN 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 a number of examples of corrections:

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

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.

8.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”.

9. Delivery reports

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 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 receive HTTP GET or POST requests.

Parameters

The request includes the following parameters:

Parameter| Type| **M/O/I*| Default Value| Max length| Description**
---|---|---|---|---|---
MessageId| string| M| –| 22| The message ID of the MT message that this report corresponds to.
DestinationAddress| string| M| –| 40| The Consumer’s MSISDN, i.e. the destination address of the original MT message.
StatusCode| integer| M| | 1| Status code indicates the status of the MT message.
Applicable status codes are:
0 – Delivered
2 – Deleted (reason code applies)
TimeStamp| string| 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.
Operator| string| 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.
ReasonCode| integer| 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
121 – SMSC congestion
122 – SMSC roaming
130 – Handset error
131 – Handset memory exceeded
Behavior may vary with Operator integrations.
OperatorTimeStamp| string| O| –| 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.
StatusText| string| O| –| 255| Placeholder for additional information from the Operator, e.g. clear text description of the status/reason. Behavior may vary with Operator integrations.
CorrelationId| string| O| –| 100| The correlation ID provided in the SendRequest or SendTextRequest.
OperatorNetworkCode| integer| O| –| 6| The Mobile Network Code (MCC + MNC) of the Operator.

• M = Mandatory, O = Optional, I = Ignored.
  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?%20MessageId=122&DestinationAddress=46762050312&Operator=Vodafone&TimeStamp=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=20100401%2007%3A47%3A59&TimeStamp=20100401%2007%3A47%3A51&StatusCode=2&StatusText=Delivery%20failed&ReasonCode=10

The parameters are URL encodedi.

Character encoding:
The Service Provider can choose which preferred character encoding to use:
UTF-8 (recommended)
ISO-8859-1.

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

Negative acknowledgement, NAK, delivery report not delivered:
Any reply other than positive acknowledgement, for example, a negative acknowledgement is triggered by any HTTP error code or the following XML content:

The XML content can be used for controlling the LINK Mobility retry mechanism. A NAK will cause retry attempt, if enabled. For Service Providers not configured for the retry mechanism, the XML content is optional.

Below is an HTTP POST request and response example of a delivery report delivered to a Service Provider:

HTTP Request:

POST /context/app HTTP/1.1
Content-Type: application/x-www-form-urlencoded;charset=utf-8
Host: server:port
Content-Length: xx

MessageId=213123213&DestinationAddress=46762050312&Operator=Telia& OperatorTimeStamp=20130607%2010%3A45%3A00&TimeStamp=20130607%2010%3A 45%3A02&StatusCode=0

HTTP Response:

HTTP/1.1 200 OK
Content-Type: text/plain