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.

Authentication

When calling the SMS API, your requests needs to be using one of our authentication methods, as found on authentication. 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. Note that this does not mean that the SMSes were sent, but only that we are able to try and 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 good advice 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.

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 query for 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, which can be achieved via our dashboard.

We recommend enabling automatic payments to help you ensure your account always 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 specify.

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