Simple HTTP API

This document describes how to use the HTTP Interface of the Atea Mobil SMS Gateway. This document is intended for developers only, and basic knowledge of the HTTP protocol is required.

The HTTP (HyperText Transfer Protocol) Interface of the Atea Mobil SMS Gateway service is suitable for applications that already have HTTP client features built-in. The interface is “firewall-friendly” since standard HTTP protocol and port number 443 is used for client connections.

However, the HTTP interface is only recommended for submitting and receiving single messages, and IS NOT INTENDED to be used for bulk messaging.

Gateway connect information

HTTPS interface URL

SSL Certificates

All Atea Mobil services are secured using a wildcard SSL Server certificate with CN=*.anywhere.vc.

Technical information

Using a single HTTP POST operation, the client may submit a SMS of any type to the Atea Mobil SMS Gateway. Similarly, when receiving a SMS, the Gateway will initiate a HTTP POST operation to an URL defined by the customer.

The Gateway is HTTP version 1.1 compliant, but when delivering SMS from the Gateway to the customer, HTTP 1.0 is used for backward compatibility. When POSTing, all parameters should be url-encoded and use the utf-8 characterset.

A HTTP GET Request may also be used for sending, but is of limited use since a GET operation cannot hold more than 255 characters.

Submitting SMS

This POST operation is initiated by the customer, and the response is returned from the Gateway to the customer over the same HTTP session. In terms of a client-server relationship, the customer here acts as a client and the Gateway as a server.

Request

A valid submission of a HTTP POST may look like this:

    POST /simple HTTP/1.1
    Content-Type: text/plain
    Host: mobil.anywhere.vc

    USER=Username&PW=Password&RCV=+4744556677&SND=SenderID&TXT=Message
    with new line :-)

A valid submission using HTTP GET may look like this:

    https://mobil.anywhere.vc/simple?USER=Username&PW=Password&RCV=+4744556677&SND=SenderID&TXT=Message%0Awith new line! :-)

Response

The following response will be valid for the request above:

    HTTP/1.1 200 OK
    Date: Mon, 05 Feb 2018 11:15:40 GMT
    Content-Type: text/plain; charset=utf-8
    Content-Length: 124

    0
    OK

The response will consist of two lines. First line is a numeric statuscode and the second is a corresponding description. A successful submission of the message will have a result code of 0. Any other result means that the submission has failed permanently and should be resubmitted

HTTP Parameters

Client identification (USER and PW)

• Mandatory for sending: Yes
• Mandatory for receiving: Yes

These two parameters are used to identify the client user account on the Gateway. Both username(user) and password(pw) will be assigned to you by the Gateway operator when you sign up for an account.

Text body/message (TXT)

• Mandatory for sending: Yes
• Mandatory for receiving: Not supported

This parameter contains the message text itself. For sending, the message length should not exceed 160 characters unless you would like to use concatenated SMS messages. Messages exceeding 160 characters will be split up into a maximum of 6 SMS messages, each of 134 characters. Thus, the maximum length is 6*134=804 characters. This is done automatically by the SMS Gateway. Messages of more than 804 characters will be truncated. The message must/will be URL-encoded.

Example:

    TXT=Message%0Awith new line! :-)

Receiver Number (RCV)

• Mandatory for sending: Yes
• Mandatory for receiving: Yes

The receiver must be a GSM cellular phone with SMS capabilities. The number must be prefixed with the country code for the recipients country and entered without any spaces and with or without the "+". For example, “RCV=90554886" is not valid, but "RCV=+4790554886" and "RCV=4790554886" is valid. The Gateway will perform basic validation of the number given upon sending. It is not possible to provide multiple receiver numbers.

Sender Number (SND)

• Mandatory for sending: Yes
• Mandatory for receiving: Not supported

Number of sender to be displayed on receiver’s handset when sending and the originating number when receiving. Numeric entered without any spaces and with or without the "+" sign, max 15 digits. Alphanumeric up to 11 characters can also be used when sending. Please note that no special/national characters are allowed for alphanumeric sendernumber. Only the characters a-z, A-Z, 0-9 and !”#%&’()*+-./?><; are allowed.

Message class (CLASS)

• Mandatory for sending: Yes
• Mandatory for receiving: Not supported

In order to send text messages as Flash messages (displayed directly on the handset screen), the Message Class must be set to the value 0 (zero). Otherwise, do not supply this parameter when sending as other values will have no effect.

Examples

Windows PowerShell

A valid submission using HTTP POST from Windows PowerShell may look like this:

    $RCV = "+4744556677"
    $SND = "DEMO"
    $TXT = "Message"

Invoke-WebRequest -UseBasicParsing https://mobil.anywhere.vc/simple -ContentType "text/html; charset=utf-8" -Method POST -Body "USER=Username&PW=Password&RCV=$RCV&SND=$SND&TXT=$TXT"