Quick Start Guide
Welcome to the Gateway API Quick Start Guide.
Welcome to the Gateway API Quick Start Guide. The aim of this guide is to give you a broad understanding of the capabilities of the Gateway API and the various ways in which you can interact with it. We will take you, step-by-step, through the process and explain where to find all the information you need in order to create SMS capable software.
The Gateway API provides you, the software developer, with the necessary building blocks to integrate SMS messaging into your application or website. At the simpler end of the scale, you may need to send a single SMS message on command. As you will see, this is both easy and quick to achieve with a minimal amount of coding necessary. At the other end of the scale, you may be aiming to create a fully-featured, two-way capable system that both sends and responds to incoming messages.
Some typical usage examples of the Gateway API include the following:
- Send an SMS message to one or more recipients
- Query the delivery status of a previously sent message
- Collate any replies that have been received for a previously sent message
- Collate any messages that have been sent to an inbound number or short code service
- Have inbound messages automatically pushed to your server where your application can process or display them in real-time
- Get a list of numbers that have subscribed to a short code or long number service
- Various aspects of any SMS surveys that are set up on your account
Before you begin
If you don’t already have one, you will need to register for an account. An account allows you to manage payment information and also provides access to the wider array of functionality that is available outside of the Gateway API. Trial accounts are available pre-loaded with free credits to allow you to test the service.
Lastly, you will need to acquire some credentials that will be used to authenticate yourself to the Gateway API. The Gateway API requires both external login and password parameters. However, these are not the same as your email and password that is used to log into your account or the website. To find your credentials, please log into your account and click the Admin card button at the top-right of the screen. Your credentials will be listed under the Gateway API Settings section. When communicating with the Gateway API, please remember to use these credentials and not your account’s username and password.
Ways to connect
At its core, the Gateway API is a web service that has been implemented using the Simple Object Access Protocol (SOAP). To aid adoption and to improve compatibility where SOAP may not be supported, we have implemented two alternative technologies HTTP and SMTP.
Ultimately, the choice about which technology you use will come down to the options available within your particular programming language or environment. Also, your familiarity with a particular technology may also factor into your decision about which to use.
Web Service (SOAP)
Where a programming language or environment provides support for SOAP, this will be the preferred option. Many IDEs will automatically generate the necessary proxy classes, therefore providing a more robust and integrated solution, while generally requiring less code to be written.
Please see the following for examples of how to connect to the Gateway API using SOAP:
The HTTP(s) Service provides exactly the same functionality as the SOAP web service. However it allows you to communicate by sending simple HTTP GET or POST requests. This opens up the possibility to use the Gateway API from programming languages that don’t provide a SOAP client. At its simplest, the HTTP Service can be enacted by sending a GET request to our URL with your parameters on the querystring. Although this is simple and easy to implement, it is generally recommended that you send your requests as POST commands. This will ensure that sensitive data does not appear on the querystring.
Please see the following for examples of how to connect to the Gateway API using HTTP:
The SMTP Service is notably different from the other two ways of interacting with the Gateway API. Instead of communicating directly with a service, you will instead compose and send an email containing the details of the SMS message you wish to send. We will then receive the email and transform it into an outbound SMS message. The SMTP Service allows any application that has the capability to send emails to also send SMS messages. Due to the limited number of fields present in an email header, the SMTP Service has a reduced set of functionality and only provides basic sending and receiving of SMS messages.
Making use of the documentation
The Developer Centre documentation provides everything you need to know about using the Gateway API. The methods page for a particular service is a good place to start as it provides an overview of the operations that are available along with a short description of each. Clicking on any of the methods will take you to a page that discusses that method in detail. The detail page will explain the correct usage along with any potential pitfalls and will provide a full parameter list. You can click any of the parameters for extra information if you’re not sure what it is for:
Testing the Gateway API
Sending SMS messages will consume credits or otherwise incur billing on your account. This can cause issues when testing your application, particularly if you use an automated test suite. To counter this problem, the Gateway API provides a TestSendSMS method. This method is analogous to the normal SendSMS method however it does not actually send a physical SMS message and therefore does not incur any charges. The TestSendSMS method will behave in exactly the same way in respect to the responses that it returns to you. This provides a convenient way to test that your requests are valid and to ensure that you are handling the various responses correctly.
The Gateway API provides several web based test interfaces that allow you make method calls directly from the Developer Centre website. This can be a useful exercise before you start writing any code because it allows you to experiment with the service to discover its functionality and behaviour. However, please note that these test interfaces link in to the actual live service, therefore it will send SMS messages and bill your account accordingly (unless using the TestSendSMS method as described above).
The test interfaces can be found here:
To use the Web Service, HTTP Connector or SMTP Service, simply sign up for a Free Trial, complete the two-minute form and we’ll open an account by return. We can have you up and running in less than 15 minutes.