Welcome to the Developer Toolkit Quick Start Guide. The aim of this guide is to give you a broad understanding of the capabilities of the Developer Toolkit 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 Developer Toolkit provides you, the software developer, with the necessary building blocks to integrate SMS text 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 Developer Toolkit include the following:
- Send an SMS message to one or more recipients.
- Query the delivery status of a previously sent message.
- Collect any replies that have been received for a previously sent message.
- Collect 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.
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 Developer Toolkit. 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 Developer Toolkit. The Developer Toolkit requires both externalLogin 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 Panel button at the top-right of the screen. Your credentials will be listed under the Developer Toolkit Settings section. When communicating with the Developer Toolkit, please remember to use these credentials and not your account’s username and password.
At its core, the Developer Toolkit 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 and comfort with a particular technology may also factor in your decision about which to use.
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 Developer Toolkit 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 Developer Toolkit 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 Developer Toolkit using HTTP.
The SMTP Service is notably different from the other two ways of interacting with the Developer Toolkit. 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.
Please click here for more information about the SMTP Service.
The Developer Centre documentation provides everything you need to know about using the Developer Toolkit. 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.
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 Developer Toolkit 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 Developer Toolkit 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 click on "Free Trial button", 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.