Skip to content

Integration Guide

Here we (the developers of GatewayAPI), will give a short introduction of what we would consider best integration to our systems.

Create Account

To use the GatewayAPI to send SMSes with you first 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 is various different APIs that you can call to submit SMSes into our systems, the recommended API for almost all uses is the REST API. Even if you are unfamiliar with REST, any HTTP client for your language of choice and a json serializer should be able get 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 as we use different HTTP Status Codes to mean different things. Most commonly we use:

  • 200: Your request was successfully completed and your SMSes has been accepted onto our queue for further processing. 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 on about specifically what caused the request to be rejected. Consulting our documentation, and the limitations section can be helpful in figuring out what you can do to construct requests correctly.

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 a SMS has been submitted into our systems, we process and route it to figure our exactly where it is going based on the phone number. When a message has been sent from our systems 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 your messages we recommend seting up a webhook, either on your account or on each request. This will make our systems call your servers with the latest status of the SMS.

Alternatively, if your systems is unable to receive webhook events, you can setup polling of individual SMS statuses, but keep in mind that polling is by its nature more inefficient and if possible to put some kind of ratelimiting and backoff mechanisms in place, as each there is no reason to query for updates when no changes has 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, it does cost some money to send SMSes, so adding credits is required before you can successfully send any, this can be achieved via our dashboard.

If you wish, you can setup a few automatic systems that help you ensure your account has credits at all times. Unless otherwise limited, we recommend setting up the automatic recurring payments on your account, this will make our systems attempt an automated charge on your credit card, with an amount you specify whenever your account drops below a credit limit you specify. Alternatively, you can also setup automatic notifications, which also triggers at a credit limit you specify, but instead of starting a payment process, it only notifies you.