Front SMS Gateway API (Product description)
1 Account
1.1 Users
When ordering, you will receive an invitation to an administrator user for the WEB interface. Once you have created this, you will be given the choice to invite more users. If you have your own developer or development team, you can invite them as «Administrator» so that they have access to setting up the SMS Gateway API, and can set this up as desired. The page is in both Norwegian and English.
You can also find product information under https://fro.no/gw-produktbeskrivelse (Norwegian) and under https://fro.no/gw-productdescription (English).
1.2 Set up – SMS Gateway API
Authentication
Under the API settings, you will find examples of JSON and HTTP GET requests.
There is also information about the user identification to be used (Service ID). You can choose whether you want to authenticate by IP address(es) or create a password.
URL for status and incoming
You can set up the desired URL for status messages. This is not mandatory but allows receiving feedback if messages are delivered to the recipient’s mobile phone, and possibly other status messages received from the carriers.
To support receiving SMS or replies, you must set up the URL where you wish to receive these.
Notifications for error messages
You can set up one or more email addresses for receiving error messages. We recommend this especially in the initial phase/development phase, as these messages provide useful information about the cause of the error (error codes). There are separate notifications for errors while sending text messages and errors delivering received text messages to your server. For incoming notifications where we cannot deliver messages, the messages will be queued. The notifications will include a link to restart the queue once the problem is solved.
Security measures
NB: If the functionality to generate an SMS is on a publicly available, we recommend implementing security measures. Examples are solutions where you enter a mobile number to receive a one-time code or other information.
This is to prevent malicious robots from mass sending messages via your account. We have customers who have been exposed to this with traffic to various countries. We therefore recommend setting up logic to limit the risk of such attacks that often come from geographical locations, with many requests from the same IP addresses, or unusually high traffic to countries you do not operate in. reCAPTCHA in combination with other measures (limitations) might be a solution to consider.
2 Parameter INDEX
2.1 OUTBOUND MESSAGES
Texts may be sent by either performing by performing a HTTP POST request with a JSON document containing the parameters below or a HTTP GET request to the SMS Gateway including the parameters in the query string.
| Parameter | Description | Accepted values | Comment |
| serviceid | Server identifier | Unique customer ID | Required |
| phoneno | Telephone number for the recipient. | International phone number with country code 004799999999 or +4799999999 | Required |
| txt | The message being sent. | Text containing only characters in the GSM character set (GSM 03.38). Other characters are replaced. If the «unicode» parameter is supplied, all Unicode characters are accepted. | Required. A message consists of 160 characters (Unicode: 70). If a message contains more, it counts as multiple SMS. Each SMS is then a length of 153 characters (Unicode: 67). Max is 1530 characters. |
| fromid | Unique Sender ID | An assigned number / serial number of Front or assigned sender text, maximum 11 characters. | Required – Unique number to receive a response or text. |
| price | Premium (overcharged) messages | In Norwegian cents (øre). Eg. NOK 1=100, NOK 30=3000. Must be activated by the Front! | Optional. When a valuation is set, fromid must be «2401»; max 160 characters in the text. Can only be sent to Norwegian phone numbers. |
| unicode | Allow sending of Unicode texts | true, false | Optional. By default, all texts are sent using the GSM character set (GSM 03.38), and non-supported characters are converted. When “unicode” is true, all characters (emoji, etc.) are allowed, and no conversions are applied. The text will only be sent as Unicode if it contains characters not found in the GSM character set. |
| encoding | URL percent encoding character set | iso-8859-1, utf8, utf-8 | Optional. Default character set is latin1 (ISO-8859-1). Note: most modern HTTP libraries perform UTF-8 percent encoding by default. (This parameter is not used for JSON requests, as JSON is always encoded as UTF-8). |
| ref | Your ID or reference | ext, max 100 characters or an integer | Optional. If ref is included in the request, the ref and phoneno will be included in the delivery status report |
| scheduled | Date and time to send the text | ISO 8601 datetime, eg. 2024-01-30T14:40:00Z | Optional. Must be in the future Default value: immediate. UTC is assumed if no time zone is supplied. |
| validity | Validity period in minutes | positive integer | Optional. Default value: 1 week in minutes. Validity period is how long the carrier should attempt to deliver the text before failing when the recipient is not connected to the mobile network (phone turned off, no coverage, SIM card removed, etc.). The carrier’s maximal validity period is used when it is shorter than the supplied value. |
| flash | Flash message | true, false | Optional. Default value: false. Attempt to send the text as Flash SMS that is displayed directly on the main screen without user interaction. Not supported by all carriers. |
| protocolid | GSM Protocol Identifier (TP-PID) | 0 – 255 | Optional. Default value: 0. Attempt to send with GSM Protocol Identifier (TP-PID), which can be used to set Replace Type 1-7 (65-71), for example. |
2.1.1 Send Text Examples using HTTP POST with a JSON document
Example of sending a text using HTTP POST with a JSON document:
POST /psk/push.php HTTP/1.1
Host: www.pling.as
Content-Type: application/json
{
«serviceid»: 3,
«fromid»: «26114123450000»,
«phoneno»: «004799999999»,
«txt»: «Test æøå ÆØÅ»,
«unicode»: false
}
Example of sending a text containing an emoji:
POST /psk/push.php HTTP/1.1
Host: www.pling.as
Content-Type: application/json
{
«serviceid»: 3,
«fromid»: «26114123450000»,
«phoneno»: «004799999999»,
«txt»: «Test 🤣»,
«unicode»: true
}
Example sending a text with all parameters:
POST /psk/push.php HTTP/1.1
Host: www.pling.as
Content-Type: application/json
{
«serviceid»: 3,
«fromid»: «26114123450000»,
«phoneno»: «004799999999»,
«txt»: «Test 🤣»,
«unicode»: true,
«ref»: «3d56c6bd-ffcc-49bb-a815-81b21f082606»,
«scheduled»: «2024-01-30T13:50:00Z»,
«validity»: 60,
«flash»: false,
«protocolid»: 0
}
Example success response when using HTTP POST with a JSON document:
{
«id»: 145099,
«errorcode»: 0,
«description»: «OK»
}
Example error response when using HTTP POST with a JSON document:
{
«id»: 0,
«errorcode»: 1,
«description»: «Invalid mobile number»
}
See §2.2 for a list of error codes.
2.1.2 Send Text Examples using HTTP GET
Example of sending a text using HTTP GET with latin1 percent encoding:
http://www.pling.as/psk/push.php?serviceid=1234&phoneno=004799999999&fromid=26114123450000&txt=Test%20%E6%F8%E5%20%C6%D8%C5
Example of sending a text using HTTP GET with UTF-8 percent encoding:
Example of sending a text containing an emoji using HTTP GET with UTF-8 percent encoding:
Example of sending a text with all parameters:
Note: the order of the parameters has no significance.
Example response:
ErrorCode=0, ID=145099
See §2.2 for a list of error codes.
2.2 ERROR CODES SENDING TEXTS
When sending the text, the SMS Gateway returns a response to the text you submit. This response consists of an «error code» number and a unique reference ID.
| Error code | Description |
| errorcode=0 | OK (Message is sent) |
| errorcode=1 | Illegal mobile number |
| errorcode=2 | Message sent from illegal IP address |
| errorcode=3 | Invalid fromid |
| errorcode=4 | Illegal value SMS |
| errorcode=5 | No remaining SMS messages on account |
| errorcode=6 | Not access to premium (overcharged) texts |
| errorcode=7 | Your account has been blocked by Front, or incorrect serviceid |
| errorcode=8 | serviceid is blank / parameter is missing |
| errorcode=9 | phoneno is blank / missing parameter |
| errorcode=10 | txt is blank / missing parameter |
| errorcode=11 | fromid is blank / missing parameter |
| errorcode=12 | Illegal mobile number premium (overcharged) text |
| errorcode=13 | Invalid password |
| errorcode=14 | The message is too long (max 1530 characters) |
| errorcode=15 | The premium message is too long (max 160 characters). Only relevant for premium messages (price > 0) |
| errorcode=16 | The message contains an invalid character. The message can only contain characters in the GSM character set (GSM 03.38). Error code only in use for bulk messages (§2.4). |
| errorcode=17 | Duplicate message. Message with same fromid, phoneno and txt has been sent within the last 120 seconds. |
| errorcode=18 | Encryption required. Use https instead of http. |
| errorcode=19 | Invalid value for the encoding parameter |
| errorcode=20 | The unicode parameter must be «true» or «false» |
| errorcode=21 | Mobile number is blacklisted. The mobile number is known to be invalid for receiving SMS or has been previously seen in connection with misuse. |
| errorcode=22 | flash parameter must be «true» or «false» |
| errorcode=23 | protocolid must be an integer between 0 and 255 |
| errorcode=24 | validity must be a positive integer |
| errorcode=25 | ref cannot exceed 100 characters |
| errorcode=26 | scheduled must be an ISO 8601 formatted datetime in the future |
Please note that new error codes may be added in future versions.
2.3 DELIVERY STATUS FOR SENT TEXTS
Status of sent messages will be continually posted to the URL that you wish to receive on. The service is not compulsory, but for those who desire it.
| Parameter | Description | Legal Values | Comment |
| status | New status on SMS | -1, 4, 5 | See below |
| origid | ID Reference Number | Same number as confirmation ID when the message was sent | Unique number for each text message |
| ref | Your reference | text up to 100 characters | The «ref» that was supplied when the text was sent |
| phoneno | Mobile number the text was sent to | E164 phone number | Only included when «ref» was supplied |
Sample status: https://customer.no/sms?status=4&origid=14509
Sample status with ref: https://customer.no/sms?status=4&origid=14509&ref=abc&phoneno=%2B4799999999
Status -1:
The message is received by the carrier but not delivered to the mobile phone. Note: this status can come after status 4 if the message is delivered immediately.
Status 4:
The message has been received by the recipient’s mobile phone. It is not known whether the recipient has read the message
Status 5:
The message has failed. In most cases this is due to that sending a message to a mobile phone number not in use. May also occur due to operational errors among telecom operators.
Lack of status means that the message is on its way. The most common reason for not attaining the status is that the recipient has turned off his cell phone, or located in an area without coverage. It happens that one does not get any status even if the message is actually delivered.
2.4 OUTBOUND MESSAGES – BULK
To send a text message to multiple recipients, use an HTTP Post to the following URL: https://www.pling.as/psk/push_bulk.php
The request body must be a valid JSON document (http://json.org) with the following structure:
| Parameter | Description | Allowed values | Comment |
| serviceid | Server identifier | Unique customer ID | Required; number |
| phoneno | Recipients’ mobile numbers. | International telephone number with country code. 004799999999 | Required; string array |
| txt | Message text to be sent | Text containing only characters in the GSM character set (GSM 03.38). | Required. A message consists of 160 characters. If a message contains more, it counts as multiple SMS. Each SMS is then a length of 153 characters. Max is 1530. |
| fromid | Unik avsender ID | An assigned number / serial number from Front or assigned sender text, maximum 11 characters. | Required; string |
| unicode | Allow sending of Unicode texts | true, false | Optional; boolean. By default, all texts are sent using the GSM character set (GSM 03.38), and texts with non-supported characters are rejected. When “unicode” is true, all characters (emoji, etc.) are allowed. The text will only be sent as Unicode if it contains characters not found in the GSM character set. |
| ref | Your ID or reference | text, max 100 characters or an integer | Optional. If ref is included in the request, the ref and phoneno will be included in the delivery status report |
| scheduled | Date and time to send the text | ISO 8601 datetime, eg. 2024-01-30T14:40:00Z | Optional. Must be in the future Default value: immediate. UTC is assumed if no time zone is supplied. |
| validity | Validity period in minutes | positive integer | Optional. Default value: 1 week in minutes. Validity period is how long the carrier should attempt to deliver the text before failing when the recipient is not connected to the mobile network (phone turned off, no coverage, SIM card removed, etc.). The carrier’s maximal validity period is used when it is shorter than the supplied value. |
| flash | Flash message | true, false | Optional. Default value: false. Attempt to send the text as Flash SMS that is displayed directly on the main screen without user interaction. Not supported by all carriers. |
| protocolid | GSM Protocol Identifier (TP-PID) | 0 – 255 | Optional. Default value: 0. Attempt to send with GSM Protocol Identifier (TP-PID), which can be used to set Replace Type 1-7 (65-71), for example. |
The server will accept the request as long as there is at least one valid recipient and the other parameters are valid.
The server responds with HTTP status code 201 (created) if the message has been accepted. All other status codes indicate that the message was not accepted, and the message will not be sent. The response body includes an error code, description and lists with any invalid or duplicate mobile numbers as a JSON document.
Examples
Example bulk request:
{
«serviceid»: 1234,
«phoneno»: [«004799999999», «004799999998»],
«txt»: «Test æøå Æøå»,
«fromid»: «My Company»
}
Example bulk request with emoji:
{
«serviceid»: 1234,
«phoneno»: [«004799999999», «004799999998»],
«txt»: «Test 🤣»,
«unicode»: true,
«fromid»: «My Company»
}
Example response body:
{
Example bulk request with all parameters:
{
«serviceid»: 1234,
«phoneno»: [«004799999999», «004799999998»],
«txt»: «Test 🤣»,
«unicode»: true,
«fromid»: «Mitt Firma»,
«ref»: «3d56c6bd-ffcc-49bb-a815-81b21f082606»,
«scheduled»: «2024-01-30T13:50:00Z»,
«validity»: 60,
«flash»: false,
«protocolid»: 0
}
«errorcode»: 0,
«description»: «OK»,
«invalidPhoneno»: [],
«duplicatePhoneno»: []
}
Please note that the response does not include a reference number (ID) for the messages that will be sent. Please include a «ref» with bulk outbound messages to receive delivery status reports that contain a «ref» and «phoneno» to identify the text. (see §2.2 – 2.3).
2.5 INCOMING MESSAGES (ONLY GATEWAY PROFF and PSK)
The SMS Gateway can be configured at https://login.pling.as/pling/gateway (login required). The URL where received texts are delivered can be configured there, along with the API to be used. To ensure optimal security and comply with privacy regulations, we recommend that the URL uses HTTPS and only accepts requests from Front’s SMS Gateway IP addresses (currently 18.197.36.176, 18.197.110.183 and 18.197.138.46).
2.5.1 INCOMING MESSAGES – HTTP POST JSON API
When the HTTP POST JSON API is configured, incoming messages are delivered to the configured URL as a JSON document using HTTP POST.
Message JSON
The message is posted as a JSON document (http://json.org/) with the following fields:
| Parameter | Type | Description |
| id | Number | Front’s unique identifier for the message |
| to | String | Telephone number to which the message was sent in either E164 format (e.g. «+47594400»), national format for short code (e.g. «26114») or short code with sub-number (e.g. «26114123456789») |
| from | String | Telephone number from which the message was sent in E164 format (e.g. «+4799999999»). In rare instances this can be a nationally formatted number (e.g. «26114») or a text (e.g. «HelloWorld») of up to 11 characters. |
| text | String | The message body. In the case of a multimedia message, the subject (if present) and any plain text files included in the message will be concatenated with a newline separator to form the text. Refer to SMIL file for the proper display of the individual text files. |
| sent | String | The ISO 8601 formatted timestamp when the message was sent or first received by Front (e.g. «2020-12-31T23:59:59Z») |
| counter | Number | A counter value that is incremented for each message received at your SMS Gateway. This can be useful for detecting missing messages, etc. |
| keyword | String | The first word in the message, which is often used when routing messages sent to a short number to the appropriate recipient. |
| files | Array | The files included in a multimedia message (MMS). See below for the definition of the file object. This is an empty array for a normal text (SMS). * |
* Please note that support for multimedia messages (MMS) is an additional service that is not enabled by default on your account. In this case, the «files» field can be safely ignored, including the File JSON definition below. Please contact Front if you require MMS functionality.
File JSON
Each file in the files array consists of an object with following fields:
| Parameter | Type | Description |
| id | Number | Front’s unique identifier for the file |
| contentType | String | The MIME type of the file as specified in the MMS |
| fileName | String | The file name as specified in the MMS |
| fileData | String | The file’s binary data: Base64 encoding. |
Expected Response
Any HTTP response sent with a 2xx (success) status code will be interpreted as successful delivery of the message. For example, 200 (OK), 201 (Created), 202 (Accepted) and 204 (No Content) are all acceptable HTTP Status codes.
An HTTP response sent with any other status code is considered an unsuccessful delivery of the message. Also, the lack of a response within 60 seconds is treated as a timeout and is also considered an unsuccessful delivery.
Examples
Example of a text (SMS) received at short code:
{
«id»: 999999,
«to»: «26114»,
«from»: «+479999999»,
«text»: «Test 123»,
«sent»: «2019-12-31T23:59:59Z»,
«counter»: 7166,
«keyword»: «TEST»,
«files»: []
}
Example of a multimedia message (MMS) received at long code:
{
«id»: 999999,
«to»: «+4759440000»,
«from»: «+479999999»,
«text»: «Test 123»,
«sent»: «2019-12-31T23:59:59Z»,
«counter»: 7166,
«keyword»: «TEST»,
«files»: [
{
«id»: 4747,
«contentType»: «text/xml;Name=smil.xml;Charset=UTF-8»,
«fileName»: «smil.xml»,
«fileData»: «PD94bWwgdmVyc2lvbj0iMS4wIj48c21pbD…»
},
{
«id»: 4748,
«contentType»: «text/plain;Name=text_75329.txt;Charset=UTF-8»,
«fileName»: «text_175329.txt»,
«fileData»: «VGVzdCAxMjM=»
},
{
«id»: 4749,
«contentType»: «image/jpeg;Name=image01.jpg»,
«fileName»: «image01.jpg»,
«fileData»: «w4PCv8ODwpjDg8K/w4PCoAAQSkZJRgABAQ…»
}]
}
2.5.2 INCOMING MESSAGES – HTTP GET API
When the HTTP GET API is configured, incoming messages are delivered to the configured using an HTTP GET request with the message data as query string values. The parameter values are percent encoded using the latin1 (ISO-8859-1) character set. Characters that cannot be encoding as latin1 are converted to «?» before being encoded.
The following parameters are used in the HTTP GET API for incoming messages:
| Parameter | Description |
| fromid | Telephone number to which the message was sent in either as an international number (e.g. «47594400»), a short code (e.g. «26114») or the sub-number for short code with sub-number (e.g. «123456789» for «26114123456789») |
| phonenr | Telephone number from which the message was sent in international format with leading zeros (e.g. «004799999999»). In rare instances this can be a nationally formatted number (e.g. «26114») or a text (e.g. «HelloWorld») of up to 11 characters. |
| txt | The text of the message |
| time | Time message was received, unix code |
| countnr | A counter value that is incremented for each message received at your SMS Gateway. This can be useful for detecting missing messages, etc. |
| code | The first word in the message, which is often used when routing messages sent to a short number to the appropriate recipient. |
The expected response for a successfully processed request is the text:
true
Example of an incoming message using the HTTP GET API:
3 Document History
v2.20 (2016-19-06): OUTBOUND MESSAGES – BULK added.
v2.21 (2017-03-15): DELIVERY STATUS OF OUTGOING PUSH MESSAGES updated with correct max length for error code 14. Error code 15 and 16 added.
v2.22 (2017-03-15): Duplicate message check. New SMS Gateways will be configured with a duplicate message check. Information about error code 17 added.
v2.23 (2020-03-09): Increased maximum length for message text to 1024 characters.
v2.24 (2020-04-29)
- Improved descriptions in section 1
- Added support for HTTP POST of JSON document when sending single text
- Added unicode parameter to allow sending Unicode texts
- Added encoding parameter when sending texts using HTTP GET
- Added more examples of sending texts
- Added information about error codes 18, 19, 20
- Added HTTP POST JSON API for incoming messages
- Improve description of the parameters for the HTTP GET API for incoming messages
v2.25 (2021-12-15): New error code when mobile number is blacklisted.
v2.26 (2022-02-01): Remove mobile number from registration form
v3.02 (2023-07-11)
- Added ref, scheduled, validity, flash and protocolid to outbound messages.
- Added ref and phoneno to delivery status reports (only when ref is supplied when sending)
v3.03 (2023-08-17): Increased maximum length for message text to 1530 characters.
