Spirius SMS Gateway REST interface is the recommended way to add messaging capabilities to your applications. It is easy to use but still offer the same performance and reliability as its predecessors. The API allows you to send and receive SMS messages as well as tracking delivery of sent messages.

The following URLs can be used by to access the REST API

This API supports two different authentication schemes:

• HTTP Basic Authentication
• HMAC-SHA256

HTTPS encryption is used to protect communications between your application and Spirius SMS Gateway.

In addition to the authentication schemes, Spirius SMS Gateway allows users to lock usage to a single IPv4 address, or to a list of IPv4 addresses. This setting is found in the Account Settings section of the customer portal

Note that HMAC-SHA256 based authentication is the most secure method offered. No password or token is sent over the wire and replay of requests is mitigated thanks to a timestamp being part of the signature.

Basic Authentication

In basic HTTP authentication, a request contains a header field in the form of Authorization: Basic <credentials>, where credentials is the Base64 encoding of username and password joined by a single colon.

For example, given username bob and password secret, the string to Base64 encode is bob:secret and the final result for the header is Authorization: Basic Ym9iOnNlY3JldAo=.

Basic authentication is simple to implement and most HTTP clients have support for this feature. Since Spirius SMS gateway uses HTTPS, the credentials are always encrypted.

HMAC-SHA256

Spirius SMS Gateway supports the use of HMAC (hash-based message authentication code) to verify that a request is coming from an expected source and has not been tampered with. The client generates a unique HMAC representing its request to the server and sends that HMAC to the server, along with a timestamp and all the arguments and values it was going to send anyway. The SMS Gateway API gets the request and re-generates its own unique HMAC based on the submitted values using the same methods the client used. The SMS Gateway API will then compare the two HMACs. If they are equal, then the server trusts the client, and processes the request.

Following code snippet demonstrates how to generate HMAC signatures:

import base64
import json
import hmac
import time
import hashlib

# Settings
encoding = "utf-8"
auth_version = "SpiriusSmsV1"
api_key = "963e3454-1626-11ec-b249-67af30055a2c".encode(encoding)
path = "/sms/mt/send"

# Create message with parameters
data = {
  "message": "Hello world!",
  "to": "+46123456790",
  "from": "SPIRIUS",
}
request_body = json.dumps(data)

# Build HMAC
http_verb = "POST"
unix_timestamp = int(time.time())
body_hash = hashlib.sha1(request_body.encode(encoding))
msg_to_sign = "\n".join([
  auth_version,
  str(unix_timestamp),
  http_verb,
  path,
  body_hash.hexdigest()
]).encode(encoding)

# Create signature
digest = hmac.new(
  key=api_key,
  msg=msg_to_sign,
  digestmod=hashlib.sha256
).digest()

signature = base64.b64encode(digest).decode(encoding)
print(signature)

Complete code examples for sending requests with HMAC signatures are available on GitHub.

Further settings when deploying HMAC-SHA based authentication

Things to consider

• Disable Basic authentication in the customer portal by checking "Enforce HMAC signature"
• Make sure your machine uses NTP (or SNTP) to prevent messages to be rejected because of clock drift.

Clients are setup with a rate limit that defines the maximum number of HTTP requests that can be sent per second. When the rate limit is exceeded requests will be rejected with a HTTP status 429 “Too many requests” response. Once the client drops below the limit, SMS Gateway will again start processing requests.

A single HTTP request listing 50 recipients will count as 1 request for HTTP protocol rate limiting purposes, but the 50 messages will be subject to throttling and only sent out with the maximum speed (in SMS/second) defined by the rate limit of the client.

The same kind of throttling also applies to concatenated messages. A single message with a text long enough to require three concatenated SMS to carry the message contents, will be counted as three SMS the current second.

JavaScript Object Notation is used for HTTP bodies in both requests and replies.

Receiver phone numbers (MSISDN) must be specified in international E.164 format with leading + (e.g. +46123456789)

If configured, SMS Gateway will initiate HTTP requests to the client whenever a new MO message or status notification arrives. Webhook URLs are preset in the system when the account is setup and can be changed at any time using the customer portal.

Note that the webhook URL configured in the account settings may be overridden using the dlrCallbackUrl parameter of the Send SMS endpoint.

Webhooks support HTTPS encryption and Basic Authentication. This allows you to password protect the URLs on your web server so that only you and Spirius SMS Gateway can access them. You may provide a username and password using the following URL format.

https://username:password@www.myserver.com/sms/dlr

Webook requests must be responded to using a HTTP status 200 or 202 to acknowledge reception of the call and thereby stop retransmissions. Retransmissions will initially occur once every minute. After 15 minutes the retry frequency will start to drop and after 1 week the attempts will cease.

These endpoints are related to sending SMS and tracking delivery of sent messages.

A single SMS can contain maximum 160 characters, or maximum 70 characters if it contains emojis or any other character that is not part of the GSM-7 character set. When sending longer messages, up to 10 SMS will be concatenated to carry the message content. The maximum limit is imposed by mobile networks. Requests to send larger messages than what can fit within 10 concatenated SMS will be rejected with HTTP status 400.

Note A concatenated SMS can contain less characters than said above (usually 153) because some space is needed for the concatenation header. To find out how many SMS that will be used, the dryRun parameter can be used and then check numberOfSms in the response.

The encoding used in the SMS (i.e. GSM-7 or UCS-2) is automatically chosen by the SMS Gateway depending on the message content.

The number of SMS needed to carry the message payload is returned from the Send SMS endpoint on all HTTP 202 Accepted responses (this is true for dry-runs as well).

Using SMS Gateway, it is possible to receive MO (Mobile Originated) messages sent to virtual numbers. To obtain MO messages, the user has two options: using a webhook or repeatedly calling List all messages followed by Pop specific message when a new message arrives. Webhook is the recommended way to receive MO messages.

When a message has been delivered to the client, it will be deleted from SMS Gateway.