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

delivery_report

Description :
Specified whether a delivery report should be generated.

Use :
delivery_report=<numerical ID>
where <numerical ID> is one of the following

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

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.

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.

1. 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.
2. 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)
   1. 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.
   2. 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

<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>
		  

<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>
		  

<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

<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

<XML>
	<RECEIVE user=”12345678” password=”password”></RECEIVE>
<XML>
		  

<XML>
	<RECEIVE user=”12345678” password=”password”/>
<XML>
		  

<XML>
	<RECEIVE user=”12345678” password=”password”></RECEIVE>
	<RECEIVE user=”87654321” password=”drowssap”></RECEIVE>
</XML>
		  

Receive Response Elements

<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

<XML>
	<PARSE_ERRORS>
		<PARSE_ERROR>MALFORMED XML</PARSE_ERROR>
	</PARSE_ERRORS>
</XML>
		  

<XML>
	<PARSE_ERRORS>
		<PARSE_ERROR>NO SMSs IN SEND LIST</PARSE_ERROR>
	</PARSE_ERRORS>
</XML>
		  

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>
			

<XML>
	<POST_RESPONSE post_status=<status>/>
</XML>
			

<XML>
	<POST_RESPONSE post_status=”1”/>
</XML>
			

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".