Guidelines - sergel.zendesk.com€¦ · concatenated messages, WAP-push, Flash SMS, etc. More information about those cases can be provided by contacting support. Guidelines Confidential

Guidelines Confidential

Date Page

2018-06-04 1 (21) Identifier Version

Document id 1.3 Approved

Approved on Relation

2018-02-06 Object id.

Company information

Sergel Kredittjänster AB Box 184, 12323 Farsta, SE Registered office: Stockholm Business ID 556264-8310, VAT No 556264-8310

Approved by Creator

Sergel

Mats Villén Clearinghouse

+46-73-5964545 Name

[email protected]

SMSC API descriptions

Description

This is document describes the REST/Json interfaces to the SMSC-platform. This document will not handle specific use cases as concatenated messages, WAP-push, Flash SMS,

etc. More information about those cases can be provided by contacting support.


Date Page



Relation

Object id.

Table of contents

1 CommonLayer REST/Json MT SMS API ....................................................................................... 3

1.1 General ............................................................................................................................... 3 1.2 Base URL............................................................................................................................. 3 1.3 Authentication ...................................................................................................................... 3 1.4 SMS premium partner business model handling .................................................................. 3 1.5 The SMS bulk partner business model handling................................................................... 3 1.6 The SMS premium product categories ................................................................................. 3 1.7 Flash SMS handling ............................................................................................................. 3 1.8 Methods ............................................................................................................................... 4 1.9 Datatypes ........................................................................................................................... 14

2 Common Layer MT SMS Delivery Report .................................................................................... 17

2.1 General .............................................................................................................................. 17 2.2 Methods ............................................................................................................................. 17


Date Page



Relation

Object id.

1 CommonLayer REST/Json MT SMS API

1.1 General All HTTP requests and response (result) JSON documents must be encoded in UTF-8.

1.2 Base URL

https://wsx.sp247.net/sms/send/

1.3 Authentication

Authentication is performed via Basic Authentication.

1.4 SMS premium partner business model handling

• hese properties are used: platformId, platformPartnerId and productCategory.

• A productCategory defines both the product category and the business model. Please refer to Product Categories

• SMSC (the MT resource) should use this (platformId=PENDRAGON, platformPartnerId=12345 and productCategory=MEDIA_CPA_E_MAGAZINE) in addition to the operatorCode ("no.telenor") to find the "partner premium operator specific properties": Eg: partnerPremiumOperatorProperties = getPartnerPremiumOperatorProperties(platformId, platformPartnerId, productCategory, operatorCode)

1.5 The SMS bulk partner business model handling

• Routing is based on these properties: serviceId, platformId, platformPartnerId and destination (phone

number prefix)

• Setting of the productCategory is NOT used.

• Setting of the partner specific operator properties is NOT used.

1.6 The SMS premium product categories

Some operators require setting of the product category in the MT SMS CPA API. To handle this the Product Categories (property = productCategory) must be mapped to a particular operator specific product category. Eg: operatorProductCategory = getOperatorProductCategory(platformId, productCategory, operatorCode)

1.7 Flash SMS handling

At this time Flash SMS is not supported.

https://wsx.sp247.net/


Date Page



Relation

Object id.

1.8 Methods

POST

/send

Submits message object for delivery to mobile number.

Request Message object has following properties.

Parameter Data type Description

source String This is the source number from where the message should be sent. The format is depending on the specified sourceTON.

sourceTON TON This is the source type of number. See allowed TON values below. Default ALPHANUMERIC

destination String This is the destination number. The format is depending on the specified destinationTON.

destinationTON TON This is the destination type of number. See allowed TON values below. Default MSISDN.

dcs DCS This is the Data Coding Scheme that should be used when sending the SMS. See allowed DCS values below. Default TEXT

userDataHeader String This value may be specified when sending concatenated SMS, WAP-push, etc. The format is hex encoded 8-bit bytes. More information about valid UDH for long SMS etc may be given by support upon request.

userData String This is the message itself. The dcs specifies the format on this value.

GSM default alphabet encoded. Note that Extended GSM characters need 2 bytes for one character. Please refer to: GSM default alphabet

Binary messages should be hex encoded as 8-bit bytes


Date Page



Relation

Object id.

UCS2 encoded messages should be specified as text Note that messages that will be more than 140 bytes will be concatenated.

useDeliveryReport Boolean True indicates that a delivery report should be sent back when the message has come to a final state. It's recommended to set this value to true. "True" is mandatory for premium messages.

deliveryReportGates List<String> One or more gates that should be used for sending delivery reports.

relativeValidityTime Long This specifies how long the message is supposed to live. The value should be specified in milliseconds. -1 indicates default validity time should apply. Recommended time is between 15 minutes (900000) and 48 hours (172800000). The default validity time is 48h (172800000) The parameter absoluteValidity time override relativeValidityTime.

absoluteValidityTime Date The absolute time when a message should expire. Minimum 15 minutes and maximum 48h in the future. Formatted

tariff Integer eg. In 300 = 3 NOK - should not be specified for BULK messages. If premium sms splitted into segments: ONLY the FIRST segment set the billing price. Other segments set the price = 0.

currency Currency The currency should be set if the default country currency not to be used. See Currency. Optional.

vat Integer The VAT that should be used for the transaction, default differ per market. 2500 equals 25%. Absence or value = -1 means not set. Optional.

age Integer Allowed age for (adult) content. Optional.

priority Priority See Priority value table /Quality and Priority use cases below. Optional.


Date Page



Relation

Object id.

quality Quality See Quality value table /Quality and Priority use cases below. Optional.

platformId String Service platform id. Now following platforms supported: MERLIN, PENDRAGON, MOBILE_STUDIO, VOTING (other platform values may be specified) Note that the platform must be valid for the authenticated session.

platformPartnerId String This is the service platform partner id.

refId String This is the service platform transaction id Optional.

platformServiceType String This is the service type defined in the service platform. Optional.

platformServiceId String This is the id of the service instance defined in the service platform. Optional.

productDescription String This is the product description of the MT SMS content. Should only be used for premium messages

productCategory Integer See allowed premium product categories values: Product Categories. Should only be used for premium messages

moReferenceId String MO SMS reference id. (Mandatory for some operators)

customParameters KeyValue All additional parameters may be specified if needed. Note that only one level with key-value data is allowed. Optional.

ignoreResponse Boolean Indicate if this operation must be asynchronous without any response object/ document returned. Default is false (due to compatibility with older version)

Custom Parameters

Name Data type Description

scheduledTime Date Time when message should

be delivered to handset. Date

format according toRFC3339

UTC/GMT+0

Ex. 2017-10-

18T11:00:00.000+02:00


Date Page



Relation

Object id.

chargeOnly String String with value “true” or

“false.”

True, only charging with

operator or payment provider

is done.

False or omitted, charging

with operator or payment

provider AND SMS delivery

is performed.

Request example

{

"deliveryReportGates" : [

"h4Lb12"

] ,

"customParameters" : {

"Key" : "Value"

} ,

"source" : "1905" ,

"sourceTON" : "SHORTNUMBER" ,

"destination" : "+4796121212" ,

"destinationTON" : "MSISDN" ,

"dcs" : "TEXT" ,

"userData" : "Hello world!" ,

"tariff" : 100 ,

"currency" : "NOK" ,

"vat" :2 500 ,

"priority" : "NORMAL" ,

"quality" : "NORMAL" ,

"platformId" : "SMSC" ,

"platformPartnerId" : "1" ,

"refId" : "9ui5kKL" ,

"platformServiceType" : "INBOX" ,

"platformServiceId" :" 321" ,

"productDescription" : "Wimp" ,

"productCategory" : 26 ,

"ignoreResponse" : false

}


Date Page



Relation

Object id.

Response HTTP status 200 and the following object will be returned if ignoreResponse is false, otherwise will HTTP

status 204 be returned.


messageId String This is the ID of the message.

resultCode Integer See available codes under "API Specific result codes" and in Platform Delivery Report

description String A description of the result

If HTTP status 4XX is received the following object will be returned


status Integer Result code of the call. See available codes under "API Specific result codes".

description String A short description of the result code

translatedDescription String A translated description of the result. Please note that this is not available for all status codes


Date Page



Relation

Object id.

/sendbatch

If you want to send many messages at one time, you can use the Batch Sender to send multiple messages at once, reducing connection overhead. You will receive an array of responses when you submit, with the messageId and refId of each message posted. Sending a batch MT message is similar to sending a single MT message, except that certain parameters are moved into a sendRequestMessages parameter, which you then post an array of. The names and types and functions of all parameters except sendRequestMessages are the same as if you were sending a single MT message. Delivery reports are handled normally. The URL for submitting batch messages is http://wsx.sp247.net/sms/sendbatch

Request Parameter Data type Description

useDeliveryReport Boolean True indicates that a delivery report should be sent back when the message has come to a final state. (Delivered or failed) TRUE is mandatory for premium messages. Defaults to TRUE, and it is recommended to use delivery reports.

deliveryReportGates List <String> One or more gates that should be used for sending delivery reports. If you do not specify any Gates to deliver Delivery Reports to, make sure to set useDeliveryReport to FALSE. See the chapter on delivery reports for more information. Required for premium messages.

relativeValidityTime Long This specifies how long the message is supposed to live. If the message takes longer to deliver to the handset than the validityTime, the message will be discarded. The value is specified in milliseconds. Default is 48 hours (172800000).

http://wsx.sp247.net/sms/sendbatch


Date Page



Relation

Object id.

absoluteValidityTime Date The absolute time when a message should expire. Minimum 15 minutes and maximum 48h in the future. Formatted according to RFC3339, e.g. 2010-03-30T12:59:40+02:00. Overrides relativeValidityTime if both are set.

platformId String Your platformId. Provided to you by Support.

platformPartnerId String Your platformPartnerId. Provided to you by Support.

customParameters <List> KeyValue Advanced. Additional parameters may be specified if needed. Support will advise you if you need to use custom parameters.

ignoreResponse Boolean Indicates whether you want a response in the body when you submit the message. This is not a delivery report, only a confirmation of message submission.

sendRequestMessages List <KeyValue> An array of messages. See the following table for its contents.

sendRequestMessages:


source String Required. This is the source number from where the message should be sent. The

format is depending on the specified sourceTON.

sourceTON TON This is the source type of number. See allowed TON values


Date Page



Relation

Object id.

below. Default ALPHANUMERIC.

destination String Required. This is the destination number.

The format is depending on the specified destinationTON.

Remember that MSISDNS include the country code and a leading plus sign. (+)

destinationTON TON This is the destination type of number. See allowed TON values below. Default

MSISDN.

dcs DCS Advanced. This is the Data Coding Scheme that should be

used when sending the SMS. See allowed DCS values in a separate table. Default TEXT.

userDataHeader String Advanced. This value may be specified when sending concatenated SMS, WAP-push, etc. The

format is hex encoded 8-bit bytes. More information about valid UDH for long SMS may

be given by Support upon request. We recommend setting DCS to TEXT and

letting Common handle splitting and concatenation of messages if you do not

have a specific reason to do it yourself.

userData String This is the message content itself. The DCS


Date Page



Relation

Object id.

specifies the format (encoding) on this value. Note that messages

that messages of more than 140 bytes must be split into multiple messages. Common will do that

automatically if DCS is TEXT (default).

tariff Integer Price, in local currency, in 1/100 of currency.

For example, to send a message costing 5 NOK, this should be set to 500.

If you are splitting a long message into multiple segments yourself, set price only

on the first segment. Default 0.

currency Currency The currency should be set if the default

country currency not to be used. Supported currencies are NOK, SEK, DKK, EUR, LTL.

Ignored for non-premium messages.

vat Integer The VAT that should be

used for the transaction, default differ per market. 2500 equals 25%. Absence

or value = -1 means not set. Ignored for non-premium messages.

age Integer Allowed age for (adult) content. Optional. Not supported by all operators.


Date Page



Relation

Object id.

refId String Your own internal transaction ID. Not used for anything except as a reference.

Optional.

productDescription String When sending premium messages, a description of the

service. This will be printed on the end-user’s phone bill. Ignored for non-premium messages.

productCategory Integer When sending premium messages, specify which category

the service is. This lets the operator know which rates to apply to the message. Support or your sales contact

will help you determine the correct productCategory to set. Ignored for non-

premium messages.

moReferenceId String A reference to the ID of the MO message which triggered the MT

message. Required for some operators.

Custom Parameters


scheduleTime Date Time when message should

be delivered to handset. Ex.

2017-10-

18T11:00:00.000+02:00

Batch sending example The following JSON would send a message to two recipients at the same time. { "platformId": "SMSC", "platformPartnerId": "0",


Date Page



Relation

Object id.

"useDeliveryReport": true, "deliveryReportGates": [ "Ave57kv" ], "sendRequestMessages": [ { "source": "71300", "sourceTON": "SHORTNUMBER", "destination": "+46709835932", "userData": "Sergel test, meddelande 1", "refId": "sdJW67o" }, { "source": "71300", "sourceTON": "SHORTNUMBER", "destination": "+46735964545", "userData": Sergel test, meddelande 2", "refId": "wqR67p" } ] }

1.9 Datatypes

DCS DCS stands for "Data Coding Scheme" and describes how the data should be presented. Basic values that are

used when sending are:

Value

(enumeration)

Segment Handling Description

GSM client side GSM default alphabet encoding.

BINARY client side 8-bit binary data

UCS2 client side UCS2 encoded

TEXT server side Server side handling of the SMS segments.

DCS could be set to either "GSM" or

"USC2" by the service (server side)

TON TON stands for "type of number" and describes how the number should be presented source and destination.

Value (enumeration) Description

SHORTNUMBER Short number; 1-14 digits

ALPHANUMERIC Alphanumeric; Up to 11 valid GSM default

alphabet characters. Some operators don't

accept all the characters. Safe characters are

A-Z, a-z, 0-9.


Date Page



Relation

Object id.

MSISDN MSISDN; A mobile number on international

format starting with +.

Quality Value (enumeration) Description

BULK

NORMAL

PREMIUM


Date Page



Relation

Object id.

Priority Value (enumeration) Description

LOW

NORMAL

HIGH

API Specific result codes

See MT SMS Delivery Report for other possible result codes.

Result code Description

106000 Unknown error

106100 Invalid authentication

106101 Access denied

106200 Invalid or missing platformId

106201 Invalid or missing platformPartnerId

106202 Invalid or missing currency

106300 No gates available

106301 Specified gate not found

Quality and Priority use cases

Normal usage

• High volume bulk: quality=BULK, priority=LOW

• Normal 1 by 1 bulk traffic: quality=BULK, priority=NORMAL

• Normal 1 by 1 premium traffic - (usage of the premium SMS account/ not a bulk provider for sending

price 0 SMS's): quality=PREMIUM, priority=NORMAL

• NOTE: The value (String) is case sensitive.

• BULK HIGH: No valid use case, Redcats (by price)

• BULK NORMAL: 1 by 1 messages., smaller customer clubs, etc

• BULK LOW: High volume bulk.

• NORMAL HIGH: Confirmation messages, message response without cost, reminders.

• NORMAL NORMAL: Normal ordinary traffic

• NORMAL LOW: High volume consumer messages,

• PREMIUM HIGH: Emergency: Announcement service/ fire alarms

• PREMIUM NORMAL: 1 by 1 normal premium messages or smaller customer clubs

• PREMIUM LOW: Typical vote response sms (Thank you for voting...)


Date Page



Relation

Object id.

2 Common Layer MT SMS Delivery Report

2.1 General

This is the service that should be used when receiving delivery reports.

2.2 Methods

POST Submits delivery report object for registration

Request example {

"refId":"exampleMessageRefId",

"id":"exampleMessageId",

"operator":"se.telenor",

"timestamp":"2010-03-30T12:59:40+02:00",

"sentTimestamp":"2010-03-30T12:59:40+01:00",

"resultCode":1001,

"operatorResultCode":"DELIVERD"

}

Response HTTP 200 and text/plain body with "OK" or HTTP 204 for a successful receive

Delivery Report object has following properties:


refId String This is the unique refId

(platformTransactionId set

by the client when sending

the Platform MT SMS ) and

may be referred to when

sending questions to support.

id String This is the unique message id

(messageId returned by

Platform MT SMS) and

should be referred to when

sending questions to support.

operator String The operator code. Please

refer to: Supported operators

resource

sentTimestamp String The time the message is sent

by the SMSC to operator;


Date Page



Relation

Object id.

formatted according to

RFC3339, e.g. 2010-03-

30T12:59:40+02:00.

timestamp String Time set by operator. Can be

time for final status such as

Delivered; formatted

according to RFC3339, e.g.

2010-03-

30T12:59:40+02:00.

resultCode Integer The result code. Available

result codes listed below

operatorResultCode String Status code as it is returned

by operator

segments Integer Number of sent SMS

segments.

gateCustomParameters KeyValue Gate

resource:customParameters.

customParameters KeyValue Note that this will be treated

as a key value map see below

for constants.

Custom Parameters


subscriptionType String The subscription type (of the

end user). Values: "postpaid"

or "prepaid"

Result Codes and Transaction states These are the result codes that may appear in the resultCode field (represent a MT SMS transaction state).

Code Description Transaction State

0 Unknown error FINAL: NOT DELIVERED,

NOT BILLED

1 Temporary routing error FINAL: NOT DELIVERED,

NOT BILLED

2 Permanent routing error FINAL: NOT DELIVERED,

NOT BILLED

3 Maximum throttling

exceeded

FINAL: NOT DELIVERED,

NOT BILLED

4 Timeout FINAL: UNKOWN

DELIVERY, UNKNOWN

BILLING


Date Page



Relation

Object id.

5 Operator unknown error FINAL: UNKOWN

DELIVERY, UNKNOWN

BILLING

6 Operator error FINAL: NOT DELIVERED,

NOT BILLED

100 Service not found FINAL: NOT DELIVERED,

NOT BILLED

101 User not found FINAL: NOT DELIVERED,

NOT BILLED

102 Account not found FINAL: NOT DELIVERED,

NOT BILLED

103 Invalid password FINAL: NOT DELIVERED,

NOT BILLED

104 Configuration error FINAL: NOT DELIVERED,

NOT BILLED

105 Internal error (internal SE-

Link error)


NOT BILLED

200 OK (this code will only be

used by methods that not

deliver messages)

FINAL: NA DELIVERY,

BILLED

1000 Sent (to operator) TEMP: NOT DELIVERED,

NOT BILLED

1001 Delivered (Bulk: Delivered,

Premium: Delivered and OK

Billed)

FINAL: DELIVERED,

BILLED

1002 Expired FINAL: NOT DELIVERED,

NOT BILLED

1003 Deleted FINAL: NOT DELIVERED,

NOT BILLED

1004 Mobile full FINAL: NOT DELIVERED,

NOT BILLED

1005 Queued TEMP: NOT DELIVERED,

NOT BILLED

1006 Not delivered FINAL: NOT DELIVERED,

NOT BILLED

1007 Delivered, Billed delayed TEMP: DELIVERED, NOT

BILLED

1008 Billed OK (charged OK

before sending message)

TEMP: NOT DELIVERED,

BILLED

1009 Billed OK and NOT

Delivered


BILLED

1010 Expired, absence of operator

delivery report

FINAL: UNKOWN

DELIVERY, UNKNOWN

BILLING

1011 Billed OK and sent (to

operator)


BILLED


Date Page



Relation

Object id.

1012 Delayed (temporary billing

error, system will try to

resend)


NOT BILLED (resending)

2000 Invalid source number FINAL: NOT DELIVERED,

NOT BILLED

2001 Short number is not

supported as source


NOT BILLED

2002 Alpha is not supported as

source


NOT BILLED

2003 MSISDN is not supported as

source number


NOT BILLED

2100 Short number is not

supported as destination


NOT BILLED

2101 Alpha is not supported as

destination


NOT BILLED

2102 MSISDN is not supported as

destination


NOT BILLED

2103 Operation blocked FINAL: NOT DELIVERED,

NOT BILLED

2104 Unknown subscriber FINAL: NOT DELIVERED,

NOT BILLED

2105 Destination blocked

(subscriber permanently

barred)


NOT BILLED

2106 Number error FINAL: NOT DELIVERED,

NOT BILLED

2107 Destination temporarily

blocked (subscriber

temporarily barred)


NOT BILLED

2200 Charging error FINAL: NOT DELIVERED,

NOT BILLED

2201 Subscriber has low balance FINAL: NOT DELIVERED,

NOT BILLED

2202 Subscriber barred for

overcharged (premium)

messages


NOT BILLED

2203 Subscriber too young (for

this particular content)


NOT BILLED

2204 Prepaid subscriber not

allowed


NOT BILLED

2205 Service rejected by

subscriber


NOT BILLED

2206 Subscriber not registered in

payment system


NOT BILLED

2207 Subscriber has reached max

balance


NOT BILLED

2300 Refunded FINAL: REFUNDED


Date Page



Relation

Object id.

3000 GSM encoding is not

supported


NOT BILLED

3001 UCS2 encoding is not

supported


NOT BILLED

3002 Binary encoding is not

supported


NOT BILLED

4000 Delivery report is not

supported


NOT BILLED

4001 Invalid message content FINAL: NOT DELIVERED,

NOT BILLED

4002 Invalid tariff FINAL: NOT DELIVERED,

NOT BILLED

4003 Invalid user data FINAL: NOT DELIVERED,

NOT BILLED

4004 Invalid user data header FINAL: NOT DELIVERED,

NOT BILLED

4005 Invalid data coding FINAL: NOT DELIVERED,

NOT BILLED

4006 Invalid VAT FINAL: NOT DELIVERED,

NOT BILLED

4007 Unsupported content for dest. FINAL: NOT DELIVERED,

NOT BILLED

Documents

Guidelines - sergel.zendesk.com€¦ · concatenated messages, WAP-push, Flash SMS, etc. More information about those cases can be provided by contacting support. Guidelines Confidential