Front SMS Gateway API (Product description)

Last ned som PDF -

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.

ParameterDescriptionAccepted valuesComment
serviceidServer identifierUnique customer IDRequired
phonenoTelephone number for the recipient.International phone number with country code 004799999999Required
txtThe 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 1024 characters.
fromidUnique Sender IDAn assigned number / serial number of Front or assigned sender text, maximum 11 characters.Required – Unique number to receive a response or text.
pricePremium (overcharged) messagesIn 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.
unicodeAllow sending of Unicode textstrue, falseOptional. 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.
encodingURL percent encoding character setiso-8859-1, utf8, utf-8Optional. 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).

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 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»: true

}

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:

https://www.pling.as/psk/push.php?serviceid=1234&encoding=utf8&phoneno=004799999999&fromid=26114123450000&txt=Test%20%C3%A6%C3%B8%C3%A5%20%C3%86%C3%98%C3%85

Example of sending a text containing an emoji using HTTP GET with UTF-8 percent encoding:

https://www.pling.as/psk/push.php?serviceid=1234&encoding=utf8&unicode=true&phoneno=004799999999&fromid=26114123450000&txt=Test%20%F0%9F%A4%A3

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 codeDescription
errorcode=0OK (Message is sent)
errorcode=1Illegal mobile number
errorcode=2Message sent from illegal IP address
errorcode=3Invalid fromid
errorcode=4Illegal value SMS
errorcode=5No remaining SMS messages on account
errorcode=6Not access to premium (overcharged) texts
errorcode=7Your account has been blocked by Front, or incorrect serviceid
errorcode=8serviceid is blank / parameter is missing
errorcode=9phoneno is blank / missing parameter
errorcode=10txt is blank / missing parameter
errorcode=11fromid is blank / missing parameter
errorcode=12Illegal mobile number premium (overcharged) text
errorcode=13Invalid password
errorcode=14The message is too long (max 1024 characters)
errorcode=15The premium message is too long (max 160 characters). Only relevant for premium messages (price > 0)
errorcode=16The 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=17Duplicate message. Message with same fromid, phoneno and txt has been sent within the last 120 seconds.
errorcode=18Encryption required. Use https instead of http.
errorcode=19Invalid value for the encoding parameter
errorcode=20The unicode parameter must be «true» or «false»
errorcode=21Mobile number is blacklisted. The mobile number is known to be invalid for receiving SMS or has been previously seen in connection with misuse.

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.

ParameterDescriptionLegal ValuesComment
statusNew status on SMS-1, 4, 5See below
origidID Reference NumberSame number as confirmation ID when the message was sentUnique number for each text message

            Sample status:  http://www.customer.no/sms/?status=4&origid=145099

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:

ParameterDescriptionAllowed valuesComment             
serviceidServer identifierUnique customer IDRequired; number
phonenoRecipients’ mobile numbers.International telephone number with country code. 004799999999Required; string array
txtMessage text to be sentText 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 1024.
fromidUnik avsender IDAn assigned number / serial number from Front or assigned sender text, maximum 11 characters.Required; string
unicodeAllow sending of Unicode textstrue, falseOptional; 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.

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:

{

  «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. Bulk messages are therefore not appropriate to use if one desires delivery status of the outbound messages. (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:

ParameterTypeDescription
idNumberFront’s unique identifier for the message
toStringTelephone 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»)
fromStringTelephone 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.
textStringThe 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.
sentStringThe ISO 8601 formatted timestamp when the message was sent or first received by Front (e.g. «2020-12-31T23:59:59Z»)
counterNumberA counter value that is incremented for each message received at your SMS Gateway. This can be useful for detecting missing messages, etc.
keywordStringThe first word in the message, which is often used when routing messages sent to a short number to the appropriate recipient.
filesArrayThe 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:

ParameterTypeDescription
idNumberFront’s unique identifier for the file
contentTypeStringThe MIME type of the file as specified in the MMS
fileNameStringThe file name as specified in the MMS
fileDataStringThe 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»: «PD94bWwgdmVyc2lvbj0iMS4wIj48c21pbD48L3Nta…»

  },

  {

    «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/w4PCoAAQSkZJRgABAQEASABIA…»

  }]

}

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:

ParameterDescription
fromidTelephone 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»)
phonenrTelephone 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.
txtThe text of the message
timeTime message was received, unix code
countnrA counter value that is incremented for each message received at your SMS Gateway. This can be useful for detecting missing messages, etc.
codeThe 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:

https://www.customer.no/innkommende/?fromid=123450000&phonenr=004799999999&txt=Test%20%E6%F8%E5%20%C6%D8%C5&time=1077181484&countnr=157&code=TEST

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