allow_reply
Description :
Specifies a whether the server will forward replies to the message. The message will be stored but never forwarded. This does not apply to status reports or delivery reports.
Use :
allow_reply=<0/1>
0 means do not allow replies
1 (default) means allow replies
Example :
allow_reply="0"
concatenation_level
Description :
An optional parameter, which specifies the level to which a long message will be concatenated.
Use :
concatenation_level=<numerical ID>
where <numerical ID> is one of the following
Id |
Meaning |
0 |
No concatenation message will be cropped at 160 characters |
1 (default if not specified) |
Break-Apart: Messages are broken into multiple 160 messages |
Example :
concatenation_level="1"
delivery_report
Description :
Specified whether a delivery report should be generated.
Use :
delivery_report=<numerical ID>
where <numerical ID> is one of the following
Id |
Meaning |
0 |
None |
1 |
Generate a report |
Notes :
default it 0 (if unspecified).
Please note that specifying 1 does not produce a ME delivery report, but rather whether or not the message was delivered to the network. Additionally any failure to deliver to the network will result in a "failed" report being generated.
Example :
delivery_report="1"
extension
Description :
Specifies the extension that the SMS came from. This is used purely for itemised billing purpose.
Use :
extension=<extension>
Example :
extension="123456"
or
extension="John Smith"
or
extension="john@smith.com"
See also :
uid
password
Description :
Specifies the password associated with the user account.
Use :
password=<password>
Example :
password="secret01"
See also :
user
reply
Description :
Specifies the reply path that any replies to an SMS should take.
Use :
reply=<transport>:<data>
where <transport>:<data> can be
SSL:<user account>
EMAIL:<email address>
EMAIL_W_SUBJECT:<email address>:<subject ID>
HTTP:<URL>
Where <user account> is any valid user account on the SMS gateway (usually the one sending the SMS).
Where <email address> is any valid SMTP destination email address
Where <subject ID> is an arbitrary subject line that will be sent with delivery report, status reports and replies. The <subject ID> will be concatenated with the relevant subject line using brackets. e.g. If <subject ID> was "test" then on a reply the subject line would be "SMS Reply (test)".
Where <URL> is a fully qualified http URL. Full compatibility with https certificates has not been established.
Notes :
A message body contain only 1 reply header.
If a message does not have a reply tag then it will discard replies.
EMAIL and EMAIL_W_SUBJECT returns a friendly response while EMAIL_VERBOSE returns developer level responses.
Example :
reply="SSL:myaccount"
or
reply:"EMAIL:my_reply_email@myisp.com"
or
reply="EMAIL_W_SUBJECT:my_reply_email@myisp.com:some subject line"
or
reply="HTTP:http://www.mydomain.com/somepage.jsp"
See also :
user
HTTP Pushes
reply_cc
Description :
An optional parameter that allows you to set an additional reply path for replies to be cc'ed to. This tag does NOT include status report and delivery reports.
Use :
Parameters are the same as the reply tag
Example :
reply_cc="EMAIL:my_reply_email@myisp.com"
See also :
reply
HTTP Pushes
type
Description :
Specifies the reply type.
Use :
type=<reply type>
where <reply type> means the following
Id |
Meaning |
1 |
Received Message: A normal incoming reply |
5 |
Send Failure (SOFT_REPORT) Generated by delivery_report tag |
4 |
Send Succeeded (SOFT_REPORT) Generated by delivery_report tag |
7 |
SMS_STATUS Report – Delivery Failed Generated by status_report tag |
6 |
SMS_STATUS Report Delivery Report – Delivery Success Generated by status_report tag |
8 |
SMS_STATUS Report Delivery Report – Temporary Error Generated by status_report tag |
Notes :
A reply type of 4 or 5 indicates a status of whether or not the message was delivered to the GSM network or not.
Example :
type ="0"
send_at
Description :
Specifies a date at which the SMS must leave the gateway. This tag is used to schedule a message on the server. The message will wait on the server and be sent from the server at time send_at. A maximum schedule period may be imposed on message by the server and is tentatively set at 14 days. Messages, which try to be scheduled with a date greater than 14 days in advance, will receive a PARSE ERROR from the server describing the error.
Use :
send_at=:<GMT date and time>
where <GMT date and time> is a date and time of the format YYYY-MM-DD HH:MM:SS
See also :
send_before
* You can override send_at at the child node <SMS_Send>
send_before
Description :
Specifies a date by which the SMS must have left the gateway. It is used to specify the latest time by which a scheduled message must be handed onto the global GSM network.
Use :
send_before=:<GMT date and time>
where <GMT date and time> is a date and time of the format YYYY-MM-DD HH:MM:SS
Notes :
This tag does not imply deliver before a certain time.
Example :
send_before="2002-12-25 17:55:00"
See also :
send_at
* You can override send_before at the child node <SMS_Send>
send_between_end
Description :
This tag form the end time for when a message can be sent between. For instance, if you want a message to only go out between 15h00 and 19h00 then the send_between_end value would be 1140 (19 x 60).
Use :
send_between_end=<minutes from 00h00>
Notes :
requires
- time_zone
- send_between_start
Example :
send_between_end='1140' //19h00
See also :
time_zone
send_between_start
send_between_start
Description :
This tag form the start time for when a message can be sent between. For instance, if you want a message to only go out between 15h00 and 19h00 then the send_between_start value would be 900 (15 x 60).
Use :
send_between_start=<minutes from 00h00>
Notes :
requires
- time_zone
- send_between_end
Example :
send_between_start='900' //15h00
See also :
time_zone
send_between_end
send_on_weekends
Description :
This tag is used to specify whether this message can be sent on a weekend. The weekend is considered to be from Friday 17h00 to Monday 08h00. The time it is sent from the gateway is dependent on the value of the time_zone tag.
Use :
send_on_weekends=<0/1>
0=No
1=Yes
Example :
send_on_weekends='1' //this message can be sent on the weekend
send_on_weekends='0' //this message should not be sent on the weekend
See also :
time_zone
send_status
Description :
Specifies the status of a message as it is sent.
0 |
OK |
1 |
Authentication Failed |
2 |
Account Closed |
3 |
Generic Failure |
4 |
Destination Address blocked |
5 |
No Credits |
6 |
Reserved |
7 |
Reserved |
8 |
Decryption Failed |
9 |
Account Not Found |
10 |
Client UID Duplicated (i.e. same uid, destination address and account as another SMS). |
sms_entry_ID
Description :
Specifies an ID of the message as generated on the server. Used for checking for duplicates when doing a receive.
Use :
sms_entry_ID=<numerical ID>
Example :
sms_entry_ID="1234567"
status_report
Description :
An optional parameter, which specifies that a ME SMS_STATUS_REPORT request should be added to this message. This report is generated by the network. This tag refers to the status of the message while on the network and is different to the delivery_report tag.
Use :
status_report=<0/1>
Default is 0. 1 meaning TRUE
Notes :
There may be additional costs associated with using this tag
Example :
status_report="1" (generated a status report from the network)
See also :
delivery_report
time_zone
Description :
This tag is used with the following tags
- send_on_weekends
- send_between_start
- send_between_end
It is used to calculate the correct times to send an SMS.
Use :
time_zone=<time zone in minutes from GMT>
Example :
time_zone='120' //GMT + 2
time_zone='-60' //GMT - 1
See also :
send_on_weekends
send_between_start
send_between_end
to
Description :
Specifies a number that should be sent to.
Use :
to=<cellular number>
Notes :
The cellular number should contain a full country code and a +.
The cellular number should be in the following format +<country code><network code><number>
As of 02/03/2004 we will be enforcing the following rules.
- By default numbers not formatted correctly WILL NOT BE SENT and you WILL BE CHARGED. The correct format for a message is +<country code><network code><number>. e.g. +27821234567. There are no exceptions.
- Where possible we will try and anticipate what could go wrong with the formatting and apply the following rules (these are just guideline and should NOT be relied upon)
- numbers not starting with a + will have a + attached. If the number starts with a 0 it will not be sent. e.g. 2782123 will become +2782123, however numbers like 082123 or 09441234567 will NOT BE SENT.
- numbers with punctuation (excluding +), spaces and letter will be stripped. e.g. "+27 82 123" will become +2782123; "+27 select number" will become +27.
Example :
to="+27821231234"
to_name
Description :
Specifies the "friendly" name of the recipient
Use :
to_name=<friendly name>
Notes :
Used in replies to specify who the message came from
i.e. Instead of "You have a message from +55 555 1234" the message will read "You have a message from +55 555 1234 (John Smith)"
Example :
to_name="John Smith"
uid
Description :
Specifies a unique identifier from the clients system that would uniquely identify the SMS. The tag is used in a reply message to specify to which SMS the reply pertains.
If a message from a client is received with a duplicate uid to the same destination number, then the message is marked as duplicate and not sent.
Use :
uid=<uid>
Where <uid> is an alpha numeric value.
Notes :
The uid needs only be unique on the client system.
Example :
uid="12345"
or
uid="xyz123"
user
Description :
Specifies the user account to send from. This is for authentication.
Use :
user=<user account>
Where <user account> is any valid user account on the SMS gateway
Notes :
A message body contain only 1 user header
Example :
user="myaccount01"
See also :
password
XML Elements
If should be noted that the root for the XML document is an XML element which is different from the version tag. There can only be one root element per document.
A (n) after a tag denotes that there can or should be more than 1 of these children nodes.
Sending Elements
Tag |
Properties |
Optional |
SENDBATCH |
|
N |
|
allow_reply |
Y |
|
concatenation_level |
Y |
|
delivery_report |
Y |
|
extension |
Y |
|
password |
N1 |
|
reply |
N1 |
|
reply_cc |
Y |
|
send_at |
Y |
|
send_before |
Y |
|
status_report |
Y |
|
user |
N1 |
SMSLIST |
|
N |
SMS_SEND(n) |
allow_reply |
Y |
|
concatenation_level |
Y |
|
delivery_report |
Y |
|
extension |
Y |
|
password |
N1 |
|
reply |
N1 |
|
reply_cc |
Y |
|
send_at |
Y |
|
send_before |
Y |
|
status_report |
Y |
|
to |
N |
|
to_name |
Y |
|
uid |
N |
|
user |
N1 |
N1: The property must either be set in the SEND_BATCH defaults or on every SMS_SEND element.
To send a message with the XML you would format the XML like this.
<XML>
<SENDBATCH>
<SMSLIST>
<SMS_SEND user=”user” password=”password” to=”+271230000001” uid=”1” reply=”EMAIL:john@smith.com”>
This is a test message
</SMS_SEND>
</SMSLIST>
</SENDBATCH>
</XML>
To send to more than one number you could send like this.
<XML>
<SENDBATCH>
<SMSLIST>
<SMS_SEND user=”user” password=”password” to=”+271230000001” uid=”1” reply=”EMAIL:john@smith.com”>
This is a test message
</SMS_SEND>
<SMS_SEND user=user password=password to=”+271230000002” uid=”2” reply=”EMAIL:john@smith.com”>
This is a test message
</SMS_SEND>
<SMS_SEND user=”user” password=”password” to=”+271230000003” uid=”3” reply=”EMAIL:john@smith.com”>
This is a test message
</SMS_SEND>
</SMSLIST>
</SENDBATCH>
</XML>
This is rather inefficient, so by using defaults you could in the SEND_BATCH tag you can decrease the total data needed to send like this:
<XML>
<SENDBATCH user=”user” password=”password” reply=”EMAIL:john@smith.com”>This is a test
<SMSLIST>
<SMS_SEND to=”+271230000001” uid=”1”/>
<SMS_SEND to=”+271230000002” uid=”2”/>
<SMS_SEND to=”+271230000003” uid=”3”/>
</SMSLIST>
</SENDBATCH>
</XML>
Send Response Elements
Tag |
Properties |
Optional |
SENDBATCHRESPONSE |
|
N |
SMS_SEND_RESPONSE(n) |
|
|
|
uid |
N |
|
to |
N |
|
send_status |
N |
After a SENDBATCH the response would be like this
<XML>
<SENDBATCHRESPONSE>
<SMS_SEND_RESPONSE uid=”1” to=”+275550000001” send_status=”1”>authentication failed</SMS_SEND_RESPONSE>
<SMS_SEND_RESPONSE uid=”2” to=”+275550000002” send_status=”2”>Duplicate UID</SMS_SEND_RESPONSE>
<SMS_SEND_RESPONSE uid=”3” to=”+275550000003” send_status=”3”>OK</SMS_SEND_RESPONSE>
</SENDBATCHRESPONSE>
</XML>
Receive Elements
Tag |
Properties |
Optional |
RECEIVE |
|
N |
|
user |
N |
|
password |
N |
To receive messages off the server the XML should be formatted as such
<XML>
<RECEIVE user=”12345678” password=”password”></RECEIVE>
<XML>
or
<XML>
<RECEIVE user=”12345678” password=”password”/>
<XML>
if you want to receive for multiple accounts the XML can be formatted as such
<XML>
<RECEIVE user=”12345678” password=”password”></RECEIVE>
<RECEIVE user=”87654321” password=”drowssap”></RECEIVE>
</XML>
Receive Response Elements
Tag |
Properties |
Optional |
RECEIVE_RESPONSE |
|
N |
|
User |
N |
|
Status |
N |
SMS_RECEIVE(n) |
|
Y |
|
Uid |
N |
|
To |
N |
|
Type |
N |
The response after a receive can be as follows
<XML>
<RECEIVE_RESPONSE user=12345678>
<SMS_RECEIVE uid=”1” to=”+275550000001” type=”6”/>
<SMS_RECEIVE uid=”2” to=”+275550000002” type=”1”>thanks for the message</SMS_RECEIVE>
</RECEIVE_RESPONSE>
</XML>
Parse Errors Element
When an XML response is sent back it may contain a PARSE_ERRORS element, which has an indication of why the XML sent failed to parse.
The hierarchy is as follows
Tag |
Properties |
Optional |
PARSE_ERRORS |
|
N |
PARSE_ERROR(n) |
|
N |
The response after a receive can be as follows
<XML>
<PARSE_ERRORS>
<PARSE_ERROR>MALFORMED XML</PARSE_ERROR>
</PARSE_ERRORS>
</XML>
or
<XML>
<PARSE_ERRORS>
<PARSE_ERROR>NO SMSs IN SEND LIST</PARSE_ERROR>
</PARSE_ERRORS>
</XML>
See also :
Testing
HTTP Pushes
By sending an SMS with the following tag
reply=’HTTP:http://myserver.com/somepage.jsp’
you are requesting the server to “push” the responses from the server to your web site. The data the SMS Gateway will be associated with the form data xmldata. It will take the form as per a RECEIVE request i.e.
<XML>
<RECEIVE_RESPONSE user=12345678>
<SMS_RECEIVE uid="1" to="+275550000001" type="6"/>
<SMS_RECEIVE uid="2" to="+275550000002" type="1">thanks for the message</SMS_RECEIVE>
</RECEIVE_RESPONSE>
</XML>
To minimise time the server will expect a reply back in the form of XML as such
<XML>
<POST_RESPONSE post_status=<status>/>
</XML>
where
is 0 for failure and !0 for true.
eg.
//success
<XML>
<POST_RESPONSE post_status=”1”/>
</XML>
Any bad XML or HTTP errors will be considered a failure as will any failure to connect to the server. The server will retry 5 times before deeming a message as undeliverable.
Please note:
- If you are using WCF you may need to create a custom WebContentTypeMapper to tell WCF
that the reponse type is XML.
- When the server posts data to the URL provided, the data is not encoded as
form data, it is sent as type "text/xml".