This help file describes the Gateway Definition File protocol which is used to tell Mercury how to log onto a site, send a message and then log off again. The intended audience are those people who wish to modify or create new definition files.
Please note that all versions of mercurysms up to and including 0.1.3 do not support the following variables:
US_AREA, US_EXCHANGE, US_NUMBER, MY_NUMBER, MY_US_AREA, MY_US_EXCHANGE and MY_US_NUMBER.
mercurysms will be updated as soon as a script is developed to take advantage of these new variables.
The Gateway Definition File (or GDF) format is in the style of a standard Microsoft INI file. That is, a list of keys and values grouped by a section:
[section1] key1=value1 key2=value2 [section2] key1=value2 key4=value4
Both keys and values can be the same in different sections, but you cannot have two keys with the same name in the same section. Keys and sections are case insensitive but values are not.
The GDF should be saved with an .ini extension and a unique filename. There should be no two GDF's with the same name.
There are two descriptive sections of a Gateway Definition File and then as many addition sections to define how to log on and off:
Because many gateways require multiple requests to log in, send and log out again, these sections can be appended with :x where x is a value from 1 upwards. Therefore a typical gateway which requires 2 requests to log in, 3 to send and 1 to log out would have the following sections:
[gateway] [author] [login:1] [login:2] [send:1] [send:2] [send:3] [logout:1]
Please note that even if a gateway has only one step, it should still have a :1 appended to it.
[gateway]
The Gateway section provides some details about the gateway such as its name, where it is located and how to find it.
name=
Mandatory. The name of the gateway. Where there are multiple gateways around the world, it is recommended to place a country identifier in brackets afterwards.
location=
Optional. The location of the gateway around the world.
url=
Mandatory. The website address of the gateway.
comment=
Optional. A short comment either describing the gateway or pointing out some relevant fact about that gateway. For example "only sends text messages to mobiles starting with 0795" or "Free text messages to Vodafone customers only".
characters=
Mandatory. The maximum number of characters per message that the gateway allows. The SMS protocol maximum is 160 but many gateways do not allow this full amount. Often this is because they append an advertisement to the end of each message. Mercury uses this to calculate how many texts a message will take up and where to split long messages. Don't get it wrong otherwise messages will be broken up oddly and generally cost users a lot more than they were expecting.
Below is an example of a gateway section:
[gateway] name=CheapoSMS (UK) location=United Kingdom url=http://www.cheaposms.co.uk comment=Send 15 free text messages a day to UK mobiles only characters=150
The Author section provides information about the author of the gateway, including his or her contact details. Whilst many of these options are optional, it is considered bad form not to leave some clue as to how to contact the author.
name=
Optional. The name of the author. Nicknames are acceptable but a proper name would be preferrable.
email=
Optional. The email address of the author. Whilst this is optional, it is considered polite to include this especially if someone wishes to contact you regarding it.
homepage=
Optional. The author's homepage, if he or she has one and wants to publicise it.
version=
Mandatory. The version number of the gateway definition file. This should be of the format "x.y" where x is the major version number and y is the minor version number. General convention is, before release to work with a version number less than 1.0 and then use 1.0 as the first release. Mercury uses this version number to determine if the gateway file a user has is the latest version. The minor version number is not a decimal point, therefore 1.22 comes after 1.10 which itself comes after 1.9.
released=
Mandatory. The release date of the defintion file. This is in the format "date/month/year", for example 14/11/2002 is November 14th 2002. Some text messaging programs may use this and the version number to determine whether or not the definition file they have is the latest version.
supported_numbers=
Optional. A comma seperated list of valid country codes (plus numbers) that can be used with this gateway. Ranges can be specified with a dash. For example 14,25,37-42 means that country codes +14, +25, +37, +38, +39, +40, +41 and +42 can use this gateway. You can also include additional numbers to limit it further, for example 447 will only allow you to send numbers to UK residents with mobile (as all mobiles start with 07).
Below is an example of an author section:
[author] name=Fred Bloggs email=fred@bloggs.com homepage=http://www.fredbloggs.com version=1.0 released=06/05/2002 supported_numbers=44,33,49
[login:x]
The login section details how to log into the SMS gateway. Because some gateways require that multiple steps be taken to perform this action, "x" is the step number. Therefore [login:1] indicates the first set of actions for logging in. Should it be required then [login:2] will be executed immediately after [login:1] has completed sucessfully.
If the gateway does not require a login or sends both the username and password at the same time it sends the details of each of the text messages then do not include this section.
url=
Mandatory. The url that should be visited including any GET arguments. For example http://www.cheaposms.com/send.cgi?loggedin=true. For POST arguments, you should use the data option detailed below.
referal=
Optional. The url that the gateway should be told was visited prior to the one specified above. Whilst this is optional, it is a good idea to include this otherwise it can be obvious that someone is using software to send text messages.
data=
Arguments that should be POST'ed to the server. These are not shown on the address line of web browsers. If you wish to send those types of arguments, then see the url tag. An example of posted data would be action=login&page=1&status=go which would pass three variables (action, page and status) with the three associated values (login, 1 and go).
response_ok=
Optional. Text to search for that indicates that the action was perfomed sucessfully. This is case insensitive (ie. "hello" is matched to "HeLLo" as well as "Hello"). If no response_ok is specified, then the action will automatically be assumed to have been sucessful unless any other response patterns are matched.
response_bad_login=
Optional. Text to search for that indicates that an incorrect username and/or password was used. This is case insensitive (ie. "hello" is matched to "HeLLo" as well as "Hello"). Please note that this option should be used when the gateway does not indicate what was incorrect. If the gateway does indicate what was incorrect, then use reponse_bad_username or response_bad_password instead.
response_bad_username=
Optional. Text to search for that indicates that an incorrect username was used. This is case insensitive (ie. "hello" is matched to "HeLLo" as well as "Hello"). If the gateway does not indicate whether or not the username was incorrect, merely that they failed to log in, then use response_bad_login instead.
response_bad_password=
Optional. Text to search for that indicates that an incorrect password was used for that username. This is case insensitive (ie. "hello" is matched to "HeLLo" as well as "Hello"). If the gateway does not indicate whether or not the password was incorrect, merely that they failed to log in, then use response_bad_login instead.
response_no_credit=
Optional. Text to search for that indicates that a user has run out of credit. Should this error occur then they are recommended to either purchase more credit or wait until their credit is restored. This is case insensitive (ie. "hello" is matched to "HeLLo" as well as "Hello").
response_bad_number=
Text to search for that indicates that badly formatted number was used. This could be due to missing digits or because they are trying to send a message to a mobile phone in a country not supported by the gateway. This is case insensitive (ie. "hello" is matched to "HeLLo" as well as "Hello").
[send:x]
Mandatory. The send section details how text messages should be sent to the gateway. It has the same key's as the login section. If this section is not included then no text messages will be sent.
[logout:x]
This section details how to log out of the gateway. Most applications will forget all cookies and history after the final send but it is considered a good idea to inform the gateway that the user has logged out. If you don't include a logout, the it may be possible for others to log into a previously used account after a message has been sent.
There are several variables that can (and often need) to be used to pass numbers and messages. All variables are passed url encoded (ie. space becomes "%20" and "+" becomes "%2B" and so on) and can be used in any of the sections listed above (including the responses). When you use a variable, it is replaced with the value that is associated with it before any parsing is performed.
<USERNAME>
The username for logging onto the gateway.
<PASSWORD>
The password for logging onto the gateway.
<NUMBER>
The mobile phone number of the recipient excluding country code.
<COUNTRY_CODE>
The country code of the mobile phone number of the recipient.
<FULL_NUMBER>
This is the equivilant of sending +<COUNTRY_CODE><NUMBER>.
<US_AREA>
This is the first three digits of the recipients number assuming they are based in the United States.
<US_EXCHANGE>
This is the next three digits after <US_AREA> of the recipients number assuming they are based in the United States.
<US_NUMBER>
This is the last four digits of the recipients number assuming they are based in the United States.
<MY_NUMBER>
The senders own mobile phone number.
<MY_COUNTRY_CODE>
The country code of the senders own mobile phone number.
<MY_FULL_NUMBER>
This is the equivilant of sending +<MY_COUNTRY_CODE><MY_NUMBER>.
<MY_US_AREA>
This is the first three digits of the senders number assuming they are based in the United States.
<MY_US_EXCHANGE>
This is the next three digits after <MY_US_AREA> of the senders number assuming they are based in the United States.
<MY_US_NUMBER>
This is the last four digits of the senders number assuming they are based in the United States.
<MESSAGE>
The text message.
<CHARS_USED>
The number of characters used in the message.
<CHARS_LEFT>
The number of characters not used in the message. This is the max_characters setting in the [gateway] section minus the number of characters used.
<TIMESTAMP>
The number of seconds since midnight 1st January 1970. This is sometimes used by servers to keep track of the date a message was sent.
The definition file format allow provision for custom variables. These always start with VAR_ and are in upper case. They are called just like the variables above.
Custom variables persist across different send iterations. If you define a custom variable in one section (eg. [send:1]) it cannot be used until the next section (eg. [send:2]), but will be available for all subsequent sections (eg. [logout:1]).
To define a variable use the following:
VAR_VARIABLENAME=some text to %VAR_VARIABLENAME% match
where VARIABLENAME is the variable name you wish to use (which will be called as <VAR_VARIABLENAME>) and %VAR_VARIABLENAME% is the bit in the HTML that should contain that.
Please note that before processing the HTML the application will strip out all newlines and double spaces (unless surrounded in quotes). Therefore the example above will return "here!" for all of the following:
some text to here! match
some text to here! match
some text to here! match
However, if the text is in speech marks, then it won't be compressed. So:
hello there "how are" you?
will go to:
hello there "how are" you?
Some examples:
VAR_SENDID=cheapo.sms/id=%VAR_SENDID%&name
This will look for the line cheapo.sms/id=[something]&name and extract that something storing them in VAR_SENDID.
VAR_USERNAME=Welcome %VAR_USERNAME% to CheapoSMS
This will look for Welcome [something] to CheapoSMS and extract the something to store in VAR_USERNAME.
Some points to note:
These variables relate directly to the number of messages a user has left to send through this gateway. Although it is optional for the gateway file to try and extract these values, this information is of great help to users who wish to manage their quote. As such, it is encouraged to use them where possible.
VAR_QUOTALEFT
The quota of messages the user has left.
VAR_QUOTAUSED
The quota of messages the user has used.
VAR_QUOTATOTAL
The total number of messages available to the user.
[login:1] url=http://www.cheaposms.com/compose.cgi [login:2] url=http://www.cheaposms.com/send.cgi referal=http://www.cheaposms.com/compose.cgiis probably pointless and slows down sending time as [login:2] on it's own would suffice.
[send:1] .... [send:2] .... [send:4] ....will mean that [send:4] and upwards will be ignored as there is no [send:3]
The application supports the handling of cookies automatically. If one is set by the site, then it will be stored and used whenever necessary. In addition the application will honour any requests by the site to delete a cookie.
Please note that the application will handle cookies as per the appropriate RFC's. In other words, it is not possible for a site to view, modify or delete cookies which are not associated with it.
Some sites require a cookie to be sent on a particular page before you can continue submitting any data. In order to do this, create a simple request to that page and then proceed to submitting the data. In this case, the first request will get the necessary cookie required for the second stage.
Sometimes it is necessary to perform small computations or actions on the client side before making a request. These are called functions and are always prefixed with function_.
function_add=VAR_OUTPUT,variable1,variable2
Adds two (or more) values together (variable1 and variable2 in this example, but can be additional values) and stores the resulting answer in VAR_OUTPUT.
Both variables can be either numbers or already defined custom variables. Some examples are below:
function_add=VAR_TOTAL,4,12,225
This will create a variable VAR_TOTAL and give it the value 241.
function_add=VAR_ID,77,<CHARS_USED>
This will create a variable VAR_ID which will be the number of characters used in a message + 77.
VAR_FREE=you have %VAR_FREE% free message(s) VAR_PAID=you have %VAR_PAID% paid message(s) function_add=VAR_QUOTATOTAL,<VAR_FREE>,<VAR_PAID>
This will create two variables VAR_FREE and VAR_PAID and then add them together for the value of VAR_QUOTATOTAL.
function_sleep=
Causes the application to pause for a number of seconds before continuing. This is useful for some gateways which do not want you to send messages too quickly. To prevent abuse, the script will not sleep for more than 20 seconds. The below example will sleep for 5 seconds:
function_sleep=5
Below is a sample gateway file for a fictitious company "CheapoSMS.co.uk". Note that in this example, you need to confirm you want to send the message before it is sent. Therefore [send:1] sends the message and [send:2] confirms that they do want to send it.
In addition, there is an ID number which needs to be passed to the [send:2] function, this needs to be extracted from the page that [send:1] calls. This is stored as <VAR_SENDID>.
Finally, note that the [logout:1] section assumes that the act of logging out will never fail (how can you fail to log out?) and, as such, does not bother looking for any return value.
[gateway] name=CheapoSMS (UK) location=United Kingdom url=http://www.cheaposms.co.uk comment=Send 15 free text messages a day to UK mobiles only characters=150 supported_numbers=447 [author] name=Fred Bloggs email=fred@bloggs.com homepage=http://www.fredbloggs.com version=1.0 released=06/05/2002 [login:1] url=http://www.cheaposms.co.uk/login.cgi referer=http://www.cheaposms.co.uk data=name=<USERNAME>&pass=<PASSWORD> response_bad_login=Incorrect username/password! response_ok=Hello there <USERNAME>! [send:1] url=http://www.cheaposms.co.uk/send.cgi referer=http://www.cheaposms.co.uk/compose.cgi data=msg=<MESSAGE>&to=<NUMBER> response_ok=Please confirm you wish to send this message to <NUMBER> response_bad_number=Invalid or non-uk number response_no_credit=You have sent too many messages today! VAR_SENDID=input type="hidden" name="id" value="%VAR_SENDID%"> [send:2] url=http://www.cheaposms.co.uk/confirm.cgi?&id=<VAR_SENDID> referer=http://www.cheaposms.co.uk/send.cgi VAR_QUOTALEFT=You have %VAR_QUOTELEFT% messages left today response_ok=Message sent! [logout:1] url=http://www.cheaposms.co.uk/logout.cgi referer=http://www.cheaposms.co.uk/send.cgi
Below are the details on what has been changed in this document over time.
6th May 2002 (1.0)
11th May 2002 (1.1)
9th March 2004 (1.2)
31st March 2004 (1.3)
13th April 2004 (1.4)
13th September 2005 (2.0)