Skip to content

Integration Guide

Here you will find a short introduction to what we consider to be the best integrations to our system.

Create Account

In order to use GatewayAPI to send SMS messages, you need to create an account. Creating an account will provide you with credentials that you can use to call our APIs with.

Calling the API

There are various different APIs that you can call to submit SMS messages to our systems. The recommended API for almost all uses is the REST API. Even if you are unfamiliar with REST, any HTTP client with your language of choice and a json serializer should be able to get you up and running.

No guarantee for static IP address

We do not guarantee a static API address for inbound traffic towards our API. Please use DNS to resolve the domain and avoid using an IP address as it is subject to change with no further warning.

Authentication

When calling the SMS API, your requests need to use one of our authentication methods, as found in this authentication section. If in doubt, you can use the authentication token method.

Examples

1
2
3
4
5
6
7
{
    "message": "Hello World",
    "sender": "Demo Corp",
    "recipients": [
        {"msisdn": 4512345678}
    ]
}

1
2
3
4
5
6
7
8
{
    "message": "Hello World",
    "sender": "Demo Corp",
    "recipients": [
        {"msisdn": 4512345678},
        {"msisdn": 4587654321}
    ]
}

1
2
3
4
5
6
7
8
{
    "message": "Hello World",
    "sender": "Demo Corp",
    "recipients": [
        {"msisdn": 4512345678}
    ],
    "callback_url": "https://example.com/callback"
}

Pay Attention to Responses

When making a request, it is important that you keep an eye on the returned response. The list below covers the most commonly used HTTP status codes:

  • 200: Your request was successfully completed and your SMS messages have been accepted for further processing. Note that this does not mean that the SMS messages were sent, but only that we were able to try to send them.
  • 400: The request could not be read, perhaps the payload is incomplete.
  • 401: The API was unable to authenticate the request.
  • 422: The payload of the request does not adhere to our schema or other limitations implemented in the API. The response JSON should contain some information about what specifically caused the request to be rejected. Please consult the documentation of the specific API and our limitations section that provides details on how to construct requests.

In general, it is recommended to log whatever the body was if/when the response status code is not in the 2xx range. Automatic retries are alright, but it is recommended to use some form of backoff algorithm, especially when the response is in the 4xx range, and we recommend having some form of automatic monitoring of failed requests and retries, as otherwise retries can run wild and retry forever on an error that can never succeed, such as sending to the recipient null.

Internet-connected systems are difficult to make 100% reliable, so it can happen that your servers cannot reach our servers, and this can result in general connection errors, but also in various errors in the 5xx range - depending exactly on what and where the issue is.

In this event we generally recommend throttling a little, as well as paying attention to our status page for updates. If the status page does not indicate that we have a current issue, then we recommend reaching out to our support chat. And once again we recommend having an automated system to keep track of failed requests to our service.

To understand the meaning of specific error codes, we refer to some of the many commonly available HTTP documentation sites, such as MDN Web Docs.

Receive Status Events

After an SMS has been submitted to our system, we process and route it to figure out exactly where it is going based on the phone number. When a message has been sent from our system to the local operators, the SMS will transfer between various states, such as enroute, delivered, rejected or perhaps even undeliverable.

If you wish to receive automatic updates on the status of your messages, we recommend setting up a webhook, either on your account or on each request. This will make our system call your servers with the latest status of the SMS.

Alternatively, if your systems are unable to receive webhook events, you can set up polling of individual SMS states. Keep in mind, though, that polling by its nature is less efficient. If possible, we recommend putting some kind of rate limiting and backoff mechanisms in place, as there is no reason to inquire about updates when no changes have happened.

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
    "id": 1000001,
    "msisdn": 4587654321,
    "time": 1450000000,
    "status": "DELIVERED",
    "error": null,
    "code": null,
    "userref": "foobar",
    "country_code": "DK",
    "country_prefix": 45
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
    "id": 1000001,
    "msisdn": 4587654321,
    "time": 1450000000,
    "status": "REJECTED",
    "error": "Invalid recipient number",
    "code": "0x1093",
    "userref": "foobar",
    "country_code": "DK",
    "country_prefix": 45
}

Payments

While inexpensive, there is a small fee associated with sending an SMS message. Therefore, it is required to add credits before you can successfully send any messages, which can be achieved via our dashboard.

We recommend enabling automatic payments to help you ensure your that account has enough credits at all times. Whenever the credits on your account drops below a limit you specify, our systems will attempt an automated transaction of a value you also specify.

Alternatively, you can enable automatic notifications, which trigger at a credit limit you specify, so instead of starting a payment process, it only notifies you.