Before you begin
Please make sure that CONNECT Support has provided you with the following information:
Username, Password, platformId, platformPartnerId
If you will be receiving Delivery Reports for your messages, please provide CONNECT Supportwith an URL and they will also give you a gateId to use. For more information on Delivery Reports, see the “Delivery Reports” chapter.
To use Delivery Reports, make sure you have made an opening in any firewalls so that Common can connect to you to transfer Delivery Reports. The addresses to open for are listed below.
Scope of this document
This document will describe the Application Programming Interface (API) to send text messages through the Sergel Connect “Common” platform. It will also describe the mechanism for delivering, to your platform, Delivery Reports for each message sent.
A separate document describes the API for receiving text messages.
Common is a REST API. This means it uses HTTP verbs to receive commands. A basic familiarity with REST APIs is assumed, as well as a familiarity with JSON.
Capabilities of “Common” platform
Common is a high-capacity, high-availability SMS Gateway designed to let you send and receive SMS Text messages, as well as receive a notification when the text message is received by the end-user.
A message can be free for the end-user to receive, or it can cost money. (Certain countries only). In certain markets, you can charge the end-users without actually sending them a message, so-called "Silent billing".
A message can be of any length up to the maximum defined by the GSM standard (254 segments)
It can contain any character in the UTF-8 2-byte character set. (Unicode 4-byte characters are not supported).
When sending free messages, the sender of the message can be set to any string of 2-11 characters, a-Z,0-9 (Must begin with a non-numeric character).
Common tracks the status of each message every step of the way until it is delivered to the end-user’s handset, and will provide you with this status through a Delivery Report. Delivery Reports can be sent in JSON, HTTP GET or POST formats.
Terms and glossary
Size limits
An SMS Text message can be a maximum of 140 bytes. With the most common character encoding, GSM-7, this translates to 160 characters. If your message is longer than 140 bytes, it must be split into multiple messages, and preceded by a header signifying that it is a multipart message. Common can handle this splitting, concatenation, and the overhead unless you want to do it yourself.
MT
Mobile Terminated. Refers to any SMS message which is sent to a mobile phone. (The message is terminated, or “ends”, at the phone.)
MO
Mobile Originated. Refers to any SMS message which is sent from a mobile phone. (The message’s origin, or beginning, is at the phone.)
Charged, Premium
An MT message can cost money for the end-user to receive. This is usually referred to as a charged message or premium message. If you are going to send charged messages to end-users, please review the rules and regulations for your country. Charged messages are only available in some countries and shortcodes. In certain markets, you can charge the end-users without actually sending them a message, so-called "Silent billing". Support will be happy to advise you if you are in doubt.
Bulk
A message which does not cost money for the end-user to receive. Bulk messages can set their Source (the “From”-field) of the message to any text, 2-11 characters a-Z. Using this feature to impersonate other parties will lead to a termination of your account.
Delivery Report
For each MT message we send, we can send you an acknowledgement when the message is confirmed received by the end-user’s handset. If the message fails for any reason, we will inform you about this. Delivery reports are mandatory for charged messages, optional for bulk.
TON
Type of Number. This identifies how systems shall interpret your Source (your “From”-field). It can be a Shortcode, an alphanumeric string, or a phone number (MSISDN). Same applies for the Destination, or recipient, of the message, though destination will almost always be an MSISDN.
KeyValue
Map with string key and string value where you may specify unique parameters.
Character Encoding
All communication to and from Common will be using UTF-8 encoding.
IP Addresses
When Common is delivering a Delivery Report to you, the requests can be coming from several different IP addresses.
Appendix 1 contains the hostnames and IP addresses that are currently active.
Please configure your firewalls so that these hosts/networks can connect to your systems to deliver messages.
Sending MT messages
Base URL:s
You will get this URL assigned to you when your account is created:
https://wsx.sp247.net/sms | 194.71.165.27, 195.84.162.140 Legacy |
Authentication
There are two ways of doing authentication: OAuth 2.0 or Basic Authentication.
OAuth 2.0
The preferred way of authentication is using OAuth 2.0. It requires the client to obtain a token to be used in other requests.
The only grant type currently supported is “client_credentials” where the “client_id” is the username and “client_secret” is the password provided by Support.
This would be posted to the access token URL as:
POST /auth/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id=user&client_secret=secret
Successful result with HTTP status 200:
{"access_token":"tokenxxx","token_type":"Bearer","expires_in":3599}
The access_token value should be used as a header in requests to be used for authorization:
Authorization: Bearer tokenxxx
The max age for a token is specified in the expires_in field in seconds.
Unsuccessful results will return a different HTTP status than 200 and the body will contain a error parameter in a JSON object with any of the following results: invalid_request, unsupported_grant_type, invalid_client or internal_error.
Basic Authentication
Authenticate in the HTTP request using Basic Authentication with the username and password provided by Support.
HTTP Methods, statuses, and actions
HTTP Method | Message sent | Message sent, no response | No access | Invalid request | Invalid login |
POST | 200 OK Returns SendResponse | 204 No Content | 403 Forbidden | 400 Bad Request | 401 Unauthorized |
Methods
POST /sms/send
Submits a message object for delivery to a mobile phone. Set Content-Type: application/json in your request header and POST a JSON object with the following properties:
Parameter | Data type | Description |
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 below. |
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. |
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. |
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. Common will handle the 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 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 by default. |
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 | 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). |
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. |
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. |
vat | Integer | Deprecated - implementations should not use this field any more. The VAT that used for the premium transaction, default differ per market. 2500 equals 25%. Absence or value = -1 means not set. |
age | Integer | Allowed age for (adult) content. |
priority | Priority | See the Priority value table, Optional. |
platformId | String | Your platformId. Provided to you by Support. |
platformPartnerId | String | Your platformPartnerId. Provided to you by Support. |
refId | String | Your own internal transaction ID. Not used for anything except as a reference. |
productDescription | String | When sending premium messages, a description of the service. This will be printed on the end-user’s phone bill. |
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. |
moReferenceId | String | A reference to the ID of the MO message which triggered the MT message. Required for some operators. |
customParameters | 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. Default is false. |
DCS
Data Coding Scheme sets the encoding used for the message. Default and recommended is TEXT.
DCS value | Description |
GSM | GSM-7 default alphabet encoding. |
BINARY | 8-bit binary data. |
UCS2 | UCS-2 encoding |
TEXT | Server-side handling of encoding and segmenting. Recommended. |
TON
TON stands for Type of Number and designates how a number is to be interpreted.
TON value | Description |
SHORTNUMBER | Shortnumber; 1-14 digits depending on country. |
ALPHANUMERIC | Up to 11 valid GSM characters. Some operators and some handsets don’t accept all characters. Safe characters are a-z, A-Z, 0-9. |
MSISDN | A mobile number, international format, starting with +. |
Priority
It gives the sending a certain priority.
Priority value | Description |
HIGH | For high priority of sending |
NORMAL | For normal priority of sending |
LOW | For low priority of sending |
Error Result Codes
Result Code | Description |
101100 | Invalid authentication. Please check your username and password. |
101101 | Access denied. Please check your username and password. |
106000 | Unknown Error. Please contact Support and include your whole transaction. |
106001 | Parse Error. The object to send in the request is badly formatted. |
106102 | Unable to access SMSC credentials |
106200 | Invalid or missing platformId. Please check your platformId. |
106201 | Invalid or missing platformPartnerId. Please check your platformPartnerId. |
106202 | Invalid or missing currency for premium message. Please check your price and currency. |
106300 | No gates available. Please contact Support and include your whole transaction. |
106301 | Specified gate unavailable. Please check your gateId. |
Example
In this example, the platformId and platformPartnerId and deliveryReportGates are set to invalid values. The values that are correct for you will be provided by Support.
A minimal example, including only required fields. This would send the message “Hello world” to the Norwegian phone number +4799999999, and not use a delivery report. The sender is set to “SERGEL”.
This JSON would be POSTed to https://[your assigned URL]/sms/send
{
"source": "SERGEL",
"destination": "+4799999999",
"userData": "Hello world",
"platformId": "0",
"platformPartnerId": "0",
"useDeliveryReport": false
}
Success Result
On a successful request, Common will reply with HTTP 200 OK, or HTTP 204 No Content if “ignoreResponse” is set to TRUE.
In the body you will find the messageId of the message:
{
"messageId":"Dcshuhod0PMAAAFQ+/PbnR3x",
"resultCode":1005,
"description":"Queued"
}
If the customParameter “replySmsCount” with the case insensitive String value “true” is found in the sending request, then the reply will have an extra parameter called “smsCount” that has an integer value, it shows the amount of message parts or SMS sent per SendRequestMessage.
{
"messageId":"Dcshuhod0PMAAAFQ+/PbnR3x",
"resultCode":1005,
"description":"Queued",
"smsCount":1
}
If there’s an invalid value or the case insensitive String value “false”, then the “smsCount” parameter wouldn’t be shown. The returned smsCount is a preliminary value, an estimation, of message parts and the final smsCount will be found in the delivery report.
Please note that this is not a delivery report. Save the messageId; when the delivery report arrives, it will include the same messageId.
Batch sending MT messages
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
https://[your assigned URL]/sms/sendbatch
batchSendRequest
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 | 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). |
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. |
priority | Priority | See the Priority value table, optional. |
platformId | String | Your platformId. Provided to you by Support. |
platformPartnerId | String | Your platformPartnerId. Provided to you by Support. |
customParameters | 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. Default is true. |
sendRequestMessages | List | An array of messages. The maximum number of messages allowed within the array is 1000. See the following table for its content. |
sendRequestMessage
Parameter | Data type | Description |
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 below. |
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. |
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. |
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. Common will handle the 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 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 by 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. |
vat | Integer | Deprecated - implementations should not use this field anymore. The VAT that used for the premium transaction, default differ per market. 2500 equals 25%. Absence or value = -1 means not set. |
age | Integer | Allowed age for (adult) content. |
refId | String | Your own internal transaction ID. Not used for anything except as a reference. |
productDescription | String | When sending premium messages, a description of the service. This will be printed on the end-user’s phone bill. |
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. The acceptable productCategory values are specified under productCategory values. |
moReferenceId | String | A reference to the ID of the MO message which triggered the MT message. Required for some operators. |
customParameters | KeyValue | Advanced. Additional parameters may be specified if needed. Support will advise you if you need to use custom parameters. These additional parameters are overridden by those that are in the batchSendRequest. |
productCategory values
Product categories defined by SERGEL Mobility:
Value | Description |
1 | CPA_REGULAR_RINGTONES |
2 | CPA_REGULAR_RINGBACK_TONES |
3 | CPA_REGULAR_MUSIC_FULL_TRACK |
4 | CPA_REGULAR_WALLP_ANIM |
5 | CPA_REGULAR_VIDEOS |
6 | CPA_REGULAR_NEWS |
7 | Not in use |
8 | CPA_REGULAR_LOTTERY |
9 | Not in use |
10 | CPA_REGULAR_VOTING |
11 | CPA_REGULAR_MOBILE_MARKETING |
12 | Not in use |
13 | Not in use |
14 | CPA_REGULAR_COMMUNITY |
15 | CPA_REGULAR_INFO_SERVICE |
16 | CPA_REGULAR_MIXED_CONTENT |
17 | GAS_CHARITY |
18 | GAS_CONCERT_TICKETS |
19 | GAS_MEMBERSHIP_FEE |
20 | GAS_PHYSICAL_GOODS_NON_FOOD |
21 | MEDIA_CPA_INTERNET_TV |
22 | MEDIA_CPA_INTERNET_FILM |
23 | MEDIA_CPA_E_BOOK |
24 | MEDIA_CPA_E_MAGAZINE |
25 | MEDIA_CPA_E_NEWSPAPER |
26 | Not in use |
27 | CPA_REGULAR_OTHER |
28 | GAS_CINEMA_TICKETS |
29 | GAS_BOOK |
30 | GAS_MUSIC_CD |
31 | GAS_MAGAZINE |
32 | GAS_ACCESS_FEE_SPORTS |
33 | GAS_ZERORATED_SMS |
34 | GAS_CLASSIFIED_ADS |
35 | GAS_CLASSIFIED_ADS_ABOVE_PRICE_200 |
36 | Note: --- NOT TO BE USED ---- |
37 | MANUAL_SERVICES |
38 | PHYSICAL_GOODS_FOOD_DRINK |
39 | TRANSPORT_BUS |
40 | TRANSPORT_TRAIN |
41 | HEALTH_SERVICES |
42 | PARKING |
43 | AUTOMATIC NUMBER DIRECTORY SERVICES |
44 | ALERT SERVICES |
45 | INFORMATION SERVICES |
46 | MEDIA |
47 | MEMBERSHIP_COMMERCIAL |
48 | FISHING_LICENSE |
49 | GIFT_CERTIFICATE |
50 | MANUAL_SERVICE_REGISTERED |
51 | CINEMA_TICKET |
52 | ROADTAX |
53 | NON_HUMANITARIAN_DONATIONS |
Strex productCategory values
The list of valid Strex business models: Strex Payment, Transport, Donation, Media, Information Services, Automatic Number Directory Service, Mobile Content Services, Mobile Content Services 18+, Alert Services, Voting.
Note: SERGEL CommonLayer product categories do not use these Strex business models: Media, Information Services, Automatic Number Directory Service, Alert Services.
Value | Description | Strex service code | Strex business model |
1 | CPA_REGULAR_RINGTONES | 03001 | MOBILECONTENTSERVICES |
2 | CPA_REGULAR_RINGBACK_TONES | 03002 | MOBILECONTENTSERVICES |
3 | CPA_REGULAR_MUSIC_FULL_TRACK | 03002 | MOBILECONTENTSERVICES |
4 | CPA_REGULAR_WALLP_ANIM | 03004 | MOBILECONTENTSERVICES |
5 | CPA_REGULAR_VIDEOS | 03007 | MOBILECONTENTSERVICES |
6 | CPA_REGULAR_NEWS | 02001 | MOBILECONTENTSERVICES |
7 | Not in use | N/A | N/A |
8 | CPA_REGULAR_LOTTERY | 03012 | MOBILECONTENTSERVICES |
9 | Not in use | N/A | N/A |
10 | CPA_REGULAR_VOTING | 04002 | VOTING |
11 | CPA_REGULAR_MOBILE_MARKETING | 02001 | MOBILECONTENTSERVICES |
12 | Not in use | N/A | N/A |
13 | Not in use | N/A | N/A |
14 | CPA_REGULAR_COMMUNITY | 03011 | MOBILECONTENTSERVICES |
15 | CPA_REGULAR_INFO_SERVICE | 04001 | MOBILECONTENTSERVICES |
16 | CPA_REGULAR_MIXED_CONTENT | 03011 | MOBILECONTENTSERVICES |
17 | GAS_CHARITY | 14002 | DONATION |
18 | GAS_CONCERT_TICKETS | 05010 | STREX-PAYMENT |
19 | GAS_MEMBERSHIP_FEE | 14001 | STREX-PAYMENT |
20 | GAS_PHYSICAL_GOODS_NON_FOOD | 15001 | STREX-PAYMENT |
21 | MEDIA_CPA_INTERNET_TV | 16001 | STREX-PAYMENT |
22 | MEDIA_CPA_INTERNET_FILM | 16002 | STREX-PAYMENT |
23 | MEDIA_CPA_E_BOOK | 16003 | STREX-PAYMENT |
24 | MEDIA_CPA_E_MAGAZINE | 16004 | STREX-PAYMENT |
25 | MEDIA_CPA_E_NEWSPAPER | 16005 | STREX-PAYMENT |
26 | Not in use | N/A | N/A |
27 | CPA_REGULAR_OTHER | 02001 | INFORMATIONSERVICES |
28 | GAS_CINEMA_TICKETS | 05010 | STREX-PAYMENT |
29 | GAS_BOOK | 15001 | STREX-PAYMENT |
30 | GAS_MUSIC_CD | 15001 | STREX-PAYMENT |
31 | GAS_MAGAZINE | 15001 | STREX-PAYMENT |
32 | GAS_ACCESS_FEE_SPORTS | 13003 | STREX-PAYMENT |
33 | GAS_ZERORATED_SMS | 89001 | STREX-PAYMENT |
34 | GAS_CLASSIFIED_ADS | 08001 | STREX-PAYMENT |
35 | GAS_CLASSIFIED_ADS_ABOVE_PRICE_200 | 08001 | STREX-PAYMENT |
36 | Note: --- NOT TO BE USED ---- | NA | STREX-PAYMENT |
37 | MANUAL_SERVICES | 02001 | STREX-PAYMENT |
38 | PHYSICAL_GOODS_FOOD_DRINK | 10001 | STREX-PAYMENT |
39 | TRANSPORT_BUS | 06002 | TRANSPORT |
40 | TRANSPORT_TRAIN | 06001 | TRANSPORT |
41 | HEALTH_SERVICES | 07001 | STREX-PAYMENT |
42 | PARKING | 06005 | TRANSPORT |
43 | AUTOMATIC NUMBER DIRECTORY SERVICES | 16008 | AUTOMATICNUMBERDIRECTORYSERVICE |
44 | ALERT SERVICES | 02001 | ALERTSERVICES |
45 | INFORMATION SERVICES | 02001 | INFORMATIONSERVICES |
46 | MEDIA | 16005 | MEDIA |
47 | MEMBERSHIP_COMMERCIAL | 14004 | STREX-PAYMENT |
48 | FISHING_LICENSE | 13001 | STREX-PAYMENT |
49 | GIFT_CERTIFICATE | 09001 | STREX-PAYMENT |
50 | MANUAL_SERVICE_REGISTERD | 13006 | STREX-PAYMENT |
52 | ROADTAX | 06007 | TRANSPORT |
Batch sending example
The following JSON would send a message to two recipients at the same time.
{
"platformId": "0",
"platformPartnerId": "0",
"useDeliveryReport": true,
"deliveryReportGates": [
"BVldZyQt"
],
"sendRequestMessages": [
{
"source": "2333",
"sourceTON": "SHORTNUMBER",
"destination": "+4746910822",
"userData": "Hello world, first message",
"refId": "wir7kkw"
},
{
"source": "2333",
"sourceTON": "SHORTNUMBER",
"destination": "+4741560067",
"userData": "Hello world, second message",
"refId": "qts883r"
}
]
}
Success Result
On a successful request, Common will reply with HTTP 200 OK, or HTTP 204 No Content if “ignoreResponse” is set to TRUE. In the body you will find an array of Json objects, every object is the result of every message sent, and the messageId of every message too:
[
{
"messageId": "QC5BGwiuYk0AAAFiQ08nTFOS",
"refId": “myRefId”,
"resultCode": 1005,
"message": "Queued"
},
{
"messageId": "QC5BHHuqylsAAAFiQ08nX2ph",
"refId": “myRefId”,
"resultCode": 1005,
"message": "Queued"
}
]
If the customParameter “replySmsCount” with the case insensitive String value “true” is found in the sending request, then the reply will have an extra parameter called “smsCount” that has an integer value, it shows the amount of message parts or SMS sent per SendRequestMessage in all the messages sent.
[
{
"messageId": "QC5BGwiuYk0AAAFiQ08nTFOS",
"refId": “myRefId”,
"resultCode": 1005,
"message": "Queued",
"smsCount": 1
},
{
"messageId": "QC5BHHuqylsAAAFiQ08nX2ph",
"refId": “myRefId”,
"resultCode": 1005,
"message": "Queued",
"smsCount": 1
}
]
If there’s an invalid value or the case insensitive String value “false”, then the “smsCount” parameter wouldn’t be shown.
Please note that this is not a delivery report. Save the messageId; when the delivery report arrives, it will include the same messageId.
Sending flash sms
This is possible by just adding the customParameter “flash.sms” with the case insensitive String values “true” or “false” within the request object. The default value for this customParameter is “false”.
Example within the object to POST in /sms/send/
{
"source": "SERGEL",
"destination": "+4799999999",
"userData": "Hello world",
"platformId": "0",
"platformPartnerId": "0",
"useDeliveryReport": false,
"customParameters":{
"flash.sms":"true"
}
}
In the case of batch sendings, this value can be added within the batchSendRequest or within the SendRequestMessage. But if this customParameter is added within the batchSendRequest, then it will override its value for all the messages within this single batchSendRequest.
Example 1
Here, all the messages will be sent as flash sms, even if the flash.sms customParameter is found with the value “false”within a sendRequestMessage:
{
"platformId": "0",
"platformPartnerId": "0",
"useDeliveryReport": true,
"deliveryReportGates": [
"BVldZyQt"
],
"customParameters":{
"flash.sms":"true"
},
"sendRequestMessages": [
{
"source": "2333",
"sourceTON": "SHORTNUMBER",
"destination": "+4746910822",
"userData": "Hello world, first message",
"refId": "wir7kkw",
"customParameters":{
"flash.sms":"false"
}
},
{
"source": "2333",
"sourceTON": "SHORTNUMBER",
"destination": "+4741560067",
"userData": "Hello world, second message",
"refId": "qts883r"
}
]
}
Example 2
Here, the first message will be sent as a flash SMS, meanwhile the second one and the third one will be sent as normal SMS. This will work if the customParameter “flash.sms” is absent in the batchSendRequest.
{
"platformId": "0",
"platformPartnerId": "0",
"useDeliveryReport": true,
"deliveryReportGates": [
"BVldZyQt"
],
"sendRequestMessages": [
{
"source": "2333",
"sourceTON": "SHORTNUMBER",
"destination": "+4746910822",
"userData": "Hello world, first message",
"refId": "wir7kkw",
"customParameters":{
"flash.sms":"true"
}
},
{
"source": "2333",
"sourceTON": "SHORTNUMBER",
"destination": "+4741560067",
"userData": "Hello world, second message",
"refId": "qts883r",
"customParameters":{
"flash.sms":"false"
}
},
{
"source": "2333",
"sourceTON": "SHORTNUMBER",
"destination": "+4741560096",
"userData": "Hello world, third message",
"refId": "qts847r"
}
]
}
Scheduled delivery of MT messages
Messages may be scheduled for a later delivery but at most 3 months in the future.
Add the custom parameter “scheduledTime” with the value as the date that the message should be sent. The date should be formatted according to RFC3339.
Example
{
"source": "SERGEL",
"destination": "+4799999999",
"userData": "Hello world",
"platformId": "0",
"platformPartnerId": "0",
"useDeliveryReport": false,
"customParameters": {
"scheduledTime":"2017-06-07T15:30:00Z"
}
}
Obfuscation
To use obfuscation, you need to add one of these customParameters on the request object, depending on the need:
Parameter | Value |
obfuscate.userData | true, this indicates that the userData should be obfuscated and the content itself will be replaced with the text OBFUSCATED. |
obfuscate | true, this indicates that the userData should be obfuscated and the content itself will be replaced with the text OBFUSCATED. This will also replace the destination with the countryCode and the first three digits (e.g. +4512345678 will be replaced to +45123) |
Please be aware that when you use the obfuscate function, you are not able to search in message logs for destination number or message content.
Obfuscation Example
Example for “obfuscate.userData”
Example for “obfuscate”
Delivery Reports
When an MT message is delivered to a handset, or fails for any reason, you will receive a callback with a delivery report. This is required for charged messages, optional (but recommended) for free messages. If the message is multi-part message, then it will get a delivery report for each part. It can be sent in JSON, XML, or HTTP GET/POST key/value pairs. If you want to change your format or your URL, please contact Support.
Common requires that your receiver responds with a HTTP status of 200 OK to acknowledge receipt of the delivery report. For added reliance, Common can also require that your receiver responds with a certain string in the body as well; this is optional. If you want this, please contact Support and they will enable it on your Gate.
Delivery reports will be POSTed to your service from the following IPs, please make sure there is an opening in your firewall for the hosts listed in the Appendix 1 in this document.
Delivery reports contain the following fields:
Field | Data type | Description |
refId | String | If you used a refId when submitting the message, this will be mirrored here. If not, this will be null. |
id | String | This is Common’s internal message ID for this message. It mirrors the ID which was given to you when submitting the message. If the message is a multipart message, the id will have the following pattern {id}${n}* where n is the ordinal number that identifies the part. *Example: abc123$0 is the first part of the message with id abc123 |
operator | String | The telecom operator the message was sent to (The end-users’s operator) |
sentTimestamp | DateTime | The timestamp when Common sent the message to the telecom operator. UTC time formatted according to RFC3339. |
timestamp | DateTime | The timestamp from the telecom operator for this status message. UTC time formatted according to RFC3339. |
resultCode | Integer | The status of the message. For what the different codes mean, see Status codes table below. |
operatorResultCode | String | The unmapped status of the message from the operator. Each telecom operator has different statuses and this is only provided for debugging or reference, resultCode is the real status. |
segments | Integer | The number of segments (of 140 bytes) the message was split into for delivery. |
gateCustomParameters | <List>KeyValue | If there are any custom parameters set on your gate, they will be provided here. Usually blank. |
customParameters | <List>KeyValue | If there are any extra fields in the delivery report Common receives from the operator, they will be listed here. Note: The parameters source and destination (as defined in the request) added by default to the customParameters. |
Result Codes
The most common result code is 1001 Delivered. This code indicates a successful delivery (and payment, if charged) of the message. Most statuses are final, indicating that the message either has been successfully delivered, or failed in a non-recoverable way.
resultCode | 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: UNKNOWN DELIVERY, UNKNOWN BILLING* |
5 | Operator unknown error | FINAL: UNKNOWN DELIVERY, UNKNOWN BILLING* |
6 | Operator error | FINAL: NOT DELIVERED, NOT BILLED* |
104 | Configuration error | FINAL: NOT DELIVERED, NOT BILLED* |
105 | Internal error (internal SERGEL Mobility error) | FINAL: NOT DELIVERED, NOT BILLED* |
1000 | Sent (to operator) | TEMP: NOT DELIVERED, NOT BILLED* |
1001 | Billed and delivered | FINAL: DELIVERED, BILLED* (if applicable) |
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 | FINAL: NOT DELIVERED, BILLED* |
1010 | Expired, generated by SERGEL | FINAL: UNKOWN DELIVERY, UNKNOWN BILLING* |
1011 | Billed OK and sent (to operator) | TEMP: NOT DELIVERED, BILLED* |
1012 | Delayed (temporary billing error, system will try to resend) | TEMP: NOT DELIVERED, NOT BILLED* (resending) |
1013 | Message sent to operator, Bill delayed | TEMP: NOT DELIVERED, NOT BILLED* |
2000 | Invalid source, the specified source number or Alpha is invalid | FINAL: NOT DELIVERED, NOT BILLED* |
2001 | Source shortnumber not supported, the source TON may not be set to shortnumber | FINAL: NOT DELIVERED, NOT BILLED* |
2002 | Source alpha not supported, the source TON may not be set to alpha | FINAL: NOT DELIVERED, NOT BILLED* |
2003 | Source MSISDN not supported, the source TON may not be set to MSISD | FINAL: NOT DELIVERED, NOT BILLED* |
2100 | Destination shortnumber not supported, the destination TON may not be set to shortnumber | FINAL: NOT DELIVERED, NOT BILLED* |
2101 | Destination alpha not supported, the destination TON may not be set to alpha | FINAL: NOT DELIVERED, NOT BILLED* |
2102 | Destination MSIDN not supported, the destination TON may not be set to MSISDN | FINAL: NOT DELIVERED, NOT BILLED* |
2103 | Operation blocked, requested operation is not supported for the specified destination | NOT DELIVERED, NOT BILLED* |
2104 | Unknown subscriber | FINAL: NOT DELIVERED, NOT BILLED* |
2105 | Destination blocked (subscriber permanently barred) | FINAL: NOT DELIVERED, NOT BILLED* |
2106 | Number error | FINAL: NOT DELIVERED, NOT BILLED* |
2107 | Destination temporarily blocked (subscriber temporarily barred) | FINAL: NOT DELIVERED, 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 | FINAL: NOT DELIVERED, NOT BILLED* |
2203 | Subscriber too young (for this particular content) | FINAL: NOT DELIVERED, NOT BILLED* |
2204 | Prepaid subscriber not allowed | FINAL: NOT DELIVERED, NOT BILLED* |
2205 | Service rejected by subscriber | FINAL: NOT DELIVERED, NOT BILLED* |
2206 | Subscriber not registered in payment system | FINAL: NOT DELIVERED, NOT BILLED* |
2207 | Subscriber has reached max balance | FINAL: NOT DELIVERED, NOT BILLED* |
3000 | GSM encoding is not supported | FINAL: NOT DELIVERED, NOT BILLED* |
3001 | UCS2 encoding is not supported | FINAL: NOT DELIVERED, NOT BILLED* |
3002 | Binary encoding is not supported | FINAL: NOT DELIVERED, NOT BILLED* |
4000 | Delivery report is not supported | FINAL: NOT DELIVERED, 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 destination | FINAL: NOT DELIVERED, NOT BILLED* |
*BILLED, NOT BILLED & UNKNOWN BILLING Transaction state indicates the state when sending premium SMS.
Delivery Report Example
The following example is an example of a successfully delivered message. refId and id have been set to invalid values in this example.
{
"refId": "0",
"id": "0",
"operator": "no.telenor",
"sentTimestamp": "2015-11-19T09:37:35Z",
"timestamp": "2015-11-19T09:37:00Z",
"resultCode": 1001,
"operatorResultCode": "2",
"segments": 1,
"gateCustomParameters": {},
"customParameters": {
"received": "2015-11-19 10:37:36",
"source": "2333",
"destination": ""+4746910822"
}
}
The following example is an example of a message which was attempted sent to a phone number which does not exist. refId and id have again been set to invalid values in this example.
{
"refId": "0",
"id": "0",
"operator": null,
"sentTimestamp": "2015-11-19T10:17:37Z",
"timestamp": "2015-11-19T10:17:37Z",
"resultCode": 2106,
"operatorResultCode": null,
"segments": 1,
"gateCustomParameters": {},
"customParameters": {
"received": "2015-11-19 11:17:37",
"source": "2333",
"destination": ""+4746910823"
}
}
Appendix 1
The following hosts are currently used for outgoing messaging.
Hostname(s) | IP address(es) |
socks1.sp247.net | 195.84.162.34 |
socks2.sp247.net | 194.71.165.71 |
socks3.sp247.net | 195.84.162.16 |
socks4.sp247.net | 194.71.165.98 |
socks5.sp247.net | 195.84.162.3 |
socks6.sp247.net | 194.71.165.122 |
s1.n-eu.SERGELmobility.io | 213.242.87.36 |
s2.n-eu.SERGELmobility.io | 213.242.87.37 |
s3.n-eu.SERGELmobility.io | 213.242.87.38 |
s4.n-eu.SERGELmobility.io | 213.242.87.39 |
s5.n-eu.SERGELmobility.io | 213.242.87.40 |
s6.n-eu.SERGELmobility.io | 213.242.87.41 |
s1.c-eu.SERGELmobility.io | 62.67.62.101 |
s2.c-eu.SERGELmobility.io | 62.67.62.102 |
s3.c-eu.SERGELmobility.io | 62.67.62.103 |
s4.c-eu.SERGELmobility.io | 62.67.62.104 |
s5.c-eu.SERGELmobility.io | 62.67.62.105 |
s6.c-eu.SERGELmobility.io | 62.67.62.106 |
s1.s-eu.SERGELmobility.io | 217.163.95.196 |
s2.s-eu.SERGELmobility.io | 217.163.95.197 |
s3.s-eu.SERGELmobility.io | 217.163.95.198 |
s4.s-eu.SERGELmobility.io | 217.163.95.199 |
s5.s-eu.SERGELmobility.io | 217.163.95.200 |
s6.s-eu.SERGELmobility.io | 217.163.95.201 |
s1.no.SERGELmobility.io | 213.242.87.68 |
s2.no.SERGELmobility.io | 213.242.87.69 |
s3.no.SERGELmobility.io | 213.242.87.70 |
s4.no.SERGELmobility.io | 213.242.87.71 |
s5.no.SERGELmobility.io | 213.242.87.72 |
s6.no.SERGELmobility.io | 213.242.87.73 |
Appendix 2
Silent Billing
To perform a Silent Billing (billing the end-user without them receiving a text message on their phone) set the customParameter "chargeOnly" to "true" (the string "true", not the Boolean true). Silent billing is only available in certain markets and is bound by additional agreements and restrictions. Your sales associate or Support will advise you if you are in doubt.
Examples
The following example shows how to send a premium (charged) message. The following message would cost 1 NOK for the end-user to receive. It is sent from Norwegian shortcode 2333 to Norwegian phonenumber 41560067 (country code +47). The delivery report is delivered to a predetermined gateId. (Delivery reports are required for charged messages. Only TON “SHORTNUMBER” is accepted for charged messages.)
{
"source": "2333",
"sourceTON": "SHORTNUMBER",
"destination": "+4741560067",
"userData": "This message costs 1 NOK to receive.",
"tariff": 100,
"currency": "NOK",
"platformId": "0",
"platformPartnerId": "0",
"refId": "9ui5kKL",
"productDescription": "Informational message from 2333",
"productCategory": 15,
"useDeliveryReport": true,
"deliveryReportGates": [
"0"
]
}
Norway (Strex) only
You must also set the customParameter "authorize" to "true", and "strex.username" to your company's Strex MerchantID. On the FIRST time you bill an end-user silently, you must also set the customParameter "strex.securityLevel" to 2. On the second and subsequent requests, this parameter should not be present.
Appendix 3
Supported TLS versions
From 2020-11-15 will TLS 1.2 or higher be required for all HTTPS connections.
Support for TLS 1.0 and 1.1 will be discontinued. Versions 1.0 and 1.1 of TLS are older protocols that have been deprecated and are considered as security risks in the Internet community.
SERGEL strongly recommend using HTTPS if HTTP is being used today. HTTP is deprecated as of 2020-09-01 by SERGEL and will be removed in the future. Date for HTTP removal is not yet decided.