Here you will find a short introduction to what we consider to be the best integrations to our system.
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.
1 2 3 4 5 6 7
1 2 3 4 5 6 7 8
1 2 3 4 5 6 7 8
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 good advice to log whatever the body was if/when the response status code is not in the
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 without it retries and can run wild and retry on an error that can never succeed, such as sending to the recipient
Internet connected systems are difficult to make 100% reliable, so it can happen that your servers cannot reach our servers, this can result in general connection errors, but also in various errors in the
5xx range - depending exactly on what and where the issue exactly is.
In this event we generally recommend throttling a little, and paying attention to our status page for updates, if the status page does not indicate that we have a current issue, then we can recommend reach out to our support chat. And again we can recommend having an automated system to keep track of failed requests to our service.
For the meaning of specific error codes we recommend referring 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 query for updates when no changes have happened.
1 2 3 4 5 6 7 8 9 10 11
1 2 3 4 5 6 7 8 9 10 11
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.