WataCrackaz AutoSMS Toolbar for Firefox Send SMS messages to cell phones worldwide.

AutoSMS API

The AutoSMS API provides developers and webmasters access to the architecture that powers AutoSMS. You are able to leverage all the features for SMS messaging in your own application, and focus your time on other aspects of the user experience you are trying to provide. Below is an outline of the requirements to use the API with explanations and examples.

API Calls

Calls to the API are accomplished by calling standard URL's via HTTP. This gives enormous flexibility to you as a developer as it allows you to utilize almost any development platform to leverage AutoSMS. The only requirement is that the platform must provide a web front end or be “session aware”. Most if not all web development platforms provide this by default, however if you are using a platform that is not web enabled you may have to mimic the User Agent and Session Management functionality of a standard web browser.

API calls are all made by requesting a single URL (http://www.watacrackaz.com/autosms/autosms.php) with varying parameters. The 3 main API calls are below:

Getting a list of supported carriers:
?getcarriers=1

Requesting an authentication code from the server:
?getcode=1

Sending a message to a cellphone:
?blob=<version>||<code>||<carrier>||<number>||<message>

Logically the steps above would need to be performed sequentially, with perhaps the exception of getcarriers=1, as this information could be cached after the first call for subsequent use.

Sending a message using API calls:

You can paste all example API calls directly into your browser's address bar to see the results. In fact, this is recommended as you design your application to ensure that you are providing the correct information and that you are getting the expected responses.

Get the supported carriers:
http://www.watacrackaz.com/autosms/autosms.php?getcarriers=1

This call returns a double-pipe (||) delimited list of single pipe (|) separated Region-Carrier pairs. In other words, Each carrier is paired with the region it falls under, (eg. USA|T-Mobile USA), then each resulting item is concatenated to a string of other carriers (eg. USA|Sprint USA||USA|T-Mobile USA). This grouping was done to facilitate organizing and filtering based on region. The region is also found in the name of the carrier. This is provided for clarity as the developer may choose not to display the Region separately which may lead to unnecessary ambiguity as the same carrier can operate in separate regions.

Once you have gathered the supported carriers you may choose to present the list to a user for selection or perhaps do an unattended selection based on information previously gathered. This will depend on your particular application.

Get the authentication code:
http://www.watacrackaz.com/autosms/autosms.php?getcode=1

Once you have gotten the list of carriers, your next step is to request a code from the server. This code is used as a Captcha to ensure AutoSMS is not abused by automated systems. The code is provided as a PNG image which has to be read by a user and sent back as input to AutoSMS when a message is being sent. It is this feature that requires your platform be session aware. If your platform is not able to maintain a session between the AutoSMS server and your application, when the code is sent back you will receive an error message as AutoSMS would not be able to compare your input with the original data. It should be noted that the code is a mixture of alphanumeric characters. There are no upper case letters and the code must be provided as is. Also, this code may be modified at any time to provide better security for the system. For example, this authentication system might provide an arithmetic expression where the result of the problem must be provided as input. The getcode API call establishes the session between the application and the AutoSMS server.

Send your message:
http://www.watacrackaz.com/autosms/autosms.php?blob=0.4||ab123||T-Mobile+USA||3095555555||My+first+message+with+the+AutoSMS+API

The string above is a complete and correct call to the Send API. It fills the variable _blob_ with a double-pipe delimited string which gives all the information needed to send a message using AutoSMS. Lets take a closer look at what it comprises:

0.4 – This is the version number of the string being used. As features change in the send API call, this number will be incremented. Though every effort is made to ensure that older versions of the API remain supported, at times it becomes necessary to phase them out, especially in the case of security updates which cannot be implemented with these versions.

abc123 – This is the authentication code which was read from the image provided through the getcode=1 API call. Information about this code is given under getcode API call example.

T-Mobile+USA – This is the carrier which was taken from the list given by getcarriers=1. You will notice that the region-carrier pair has been broken leaving just the carrier text. This must be followed in all cases otherwise an error message will be generated. Note the “+” sign found in the string. This is because the string has been escaped. That is, non URL friendly characters, such as spaces, are replaced with a URL friendly replacement, in this case the “+” sign. Depending on your development platform, you may have to escape the string manually with a string replacement function call or regex, however it is possible that this is automatically done for you whenever you call a URL using your platform's provided mechanism. Run a few tests to decipher what you own requirements are.

3095555555 – This is the telephone number of the cellphone you are sending the message to. AutoSMS tries as best as possible to mimic the scheme used for number entry when doing standard text messaging. That is, requiring an area code for some, a country code for others, and in some cases just the plain phone number. If a number is entered incorrectly based on the carrier's requirements, an error message will be returned detailing how the number should be formatted.

My+first+message... – This is the actual message being sent to the cellphone. Notice that the message has been escaped in a similar fashion to the Carrier string. As such the same platform specific rules apply. The character limit for messages is 120. Anything above this limit will be reduced to the first 120 characters so it is best to inform your users and limit input to ensure messages are not forcibly reduced.

Error Messages:

Each call to AutoSMS's API has a predefined format and expected parameters. If either of these conditions are not met, AutoSMS will respond with an error message outlining what went wrong. In many cases these error messages should be displayed to the user (eg. almost all error messages generated by the send API) for them to take appropriate action. However there are some that require action on the part of the developer and are usually only a factor during the design phase. Error messages are 2 or 3 part double-pipe delimited strings. These strings are comprised of, in the case of a 2 part string, the category of the message (“error”) and the message to be displayed; in a 3 part string, it contains the category (“upgrade”), the url for relevant actions regarding the message, and the message to display.

Developer error messages:

The following error messages require action on the part of the developer and require changes to the input being provided.

Upgrade error:

upgrade||http://www.watacrackaz.com/autosms/||Your version of AutoSMS is no longer supported. You may get the upgrade by visiting http://www.watacrackaz.com/autosms/

The message above is received if a call is made to the API file without any parameters, incorrect parameters, or if the provided parameters are empty (NULL). The double-pipe delimited string gives a message specifying an upgrade requirement. This was meant solely for the Toolbar, the very first AutoSMS client, however it applies to any application which misuses the API and (most likely) calls for an upgrade to that particular system to meet the (new) requirements. The message is also returned if the send API call being used is using an outdated format as noted by the version number.

All user error messages:

During design it is important to catch all errors that may be construed as user errors, but are in fact caused by errors in the application code. All user errors should be reviewed to ensure that the information being provided is as the user enters in, as such mitigating the possibilities of incorrectly reported user errors.

User error messages:

The following error messages should be displayed to the user whenever they are received. It is possible that the message is as a result of errors in the application, however for the purposes of this document they are deemed as user input errors which can be corrected from the client's front end.

error||Error: Please select a carrier, enter a telephone number\n and the message you wish to send

This error message is received if a user attempts to send a message without providing all required information. They should review their input ensuring that all requires data is provided.

error||Error: Please enter the code as shown

This error message informs the user that the code that was entered to send a message was incorrect. This message will also be received if the code was not provided or if the application making the call has not established a session between itself and the AutoSMS server.

error||Please enter the telephone number in the format [Areacode][Phone Number]
error||The telephone number should be 11 digits

These messages (or some variation of them) are generated if the user enters the telephone number in the incorrect format. The number should be reviewed and re-entered.

Success:

When a message is successfully sent to a cellphone via an API call, a single message is generated by the server. This is the only instance where the message returned is not a double-pipe delimited string. This message should be displayed to the user to confirm the successful passing of the message to the selected carrier. It must be noted that messages sent via AutoSMS are subject to the rules and priorities specified by each individual carrier, as a result there is no guarantee of timely delivery of the message. You may want to communicate this to your users.

A working implementation:

Putting together everything outlined above, a working implementation is being provided of an AutoSMS client which can be embedded in any website. This implementation if broken into two files. The first, asmshead.php must be placed between the header of your HTML document (between <HEAD> and </HEAD>). Following that, asms.php can be placed wherever you would like the widget to appear within the body of your document (between <BODY> and </BODY>). This implementation uses Javascript and Ajax to do most of the heavy lifting. The Carrier selection box was populated using PHP for contrast, but could also have been done easily using Javascript and Ajax.

The files are available here: apiexample.zip