/
XML HTTP API

XML HTTP API

Owned by Jan Varga (Unlicensed)
Last updated: Feb 17, 2014 by Peter Humphries (Deactivated)Version comment

The XML HTTP API has been deprecated.
Please ensure that all new customers us the Web Services API
The XML HTTP API is described here for customers who are already using it.

Service Location

 

/gateway/xmlReceiver

XML Document Format

The XML should be of this example format

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE msg_core SYSTEM "msg_core.dtd">

<DOCUMENT MODE="normal">
	<SENDER password="xxxxx">
		<ADDRESS type="EMAIL" role="FROM"
		 value="name@company.com"></ADDRESS>
	</SENDER>

	<REPLYTO>
		<ADDRESS type="EMAIL" role="REPLYTO"
		 value="name@company.com"></ADDRESS>
	</REPLYTO>

	<SMS>
		<HEADER>SMS From</HEADER>
		<FOOTER>my signature</FOOTER>
	</SMS>

	<MESSAGE >
		<ADDRESS type="SMS" role="TO" value="0410507753" status="INITIATOR" priority="1"></ADDRESS>

		<SUBJECT>
			Example
		</SUBJECT>

		<BODY type="TEXT">
			<PAYLOAD>
				Test SMS Message using XML.
			</PAYLOAD>
		</BODY>
	</MESSAGE>

</DOCUMENT>

Notes

Root element

<DOCUMENT/>

attribute mode should be set to NORMAL, optional.

Sender information (for authentication purpose):

<SENDER/>

password must be set.

<ADDRESS/>

  • role must have value FROM.
  • value: your account name provided by Amethon.
  • type should be set according to the value (usually EMAIL).

Reply to information (for response/confirmation purpose):
As for SENDER above but role = REPLYTO

SMS meta information

<SMS/>

 

<HEADER/>

this is the source address of the message
(this field should be set to the value
provided to you by Amethon)

<FOOTER/>

optional text to be appended to each message

Message

<MESSAGE/>

id is for custom message id, optional.

<ADDRESS/>

id is for custom address id, optional.

  • role must have value TO.
  • type should be set to SMS.
  • value should contain the recipient phone number (in international format).

<BODY/>

(see examples)

<PAYLOAD/>

(see examples)

CDATA

  • Everything inside a CDATA section is ignored by the parser.
  • If your text contains a lot of "<" or "&" characters - as program code often does - the XML element can be defined as a CDATA section.
  • A CDATA section starts with "<![CDATA[" and ends with "]]>":
  • take a look at CDATA http://www.w3schools.com/xml/xml_cdata.asp

eg

<?xml version="1.0" encoding="ISO-8859-1"?> 
<!DOCTYPE DOCUMENT SYSTEM "http://localhost:8080/gateway/msg_core.dtd"> 
<DOCUMENT mode="NORMAL"> 
  <SENDER password="xxx"> <ADDRESS type="EMAIL" role="FROM" value="networkmonitoring@fasttrack.net.au"></ADDRESS> </SENDER>
  <REPLYTO> <ADDRESS type="EMAIL" role="REPLYTO" value="ls@fasttrack.net.au"></ADDRESS> </REPLYTO>
  <MESSAGE> 
  <ADDRESS type="SMS" role="TO" value="0410507753" status="INITIATOR" priority="1"></ADDRESS> 
  <BODY type="TEXT"> 
    <PAYLOAD type="TEXT" encoding="ASCII"> <![CDATA[" and ends with "]]> 
    </PAYLOAD> 
  </BODY>
</MESSAGE> </DOCUMENT>

Examples:

Single SMS

The following is an example of sending one message to a single person

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE DOCUMENT SYSTEM "http://localhost:8080/gateway/msg_core.dtd">

<DOCUMENT mode="NORMAL">

	<SENDER password="xxxx">
		<ADDRESS type="EMAIL" role="FROM" value="account@company.com"/>
	</SENDER>

	<MESSAGE>
		<ADDRESS type="EMAIL" role="REPLYTO" value="mailto:sms@company.com?subject=SMS Reply ID#765"/>
		<ADDRESS type="SMS" role="TO" value="61410123123" status="INITIATOR" priority="1"/>
		<BODY type="TEXT">
			<PAYLOAD type="TEXT" encoding="ASCII">This is an SMS from the gateway.
			</PAYLOAD>
		</BODY>
	</MESSAGE>

</DOCUMENT>

One to Many

The following is an example of sending one message to many targets. This example will send the message "Test SMS Message using XML" to the following phone numbers: 0410507753, 0402469846 and 0418235612

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE DOCUMENT SYSTEM "http://localhost:8080/gateway/msg_core.dtd">

<DOCUMENT mode="NORMAL">

	<SENDER password="xxxx">
		<ADDRESS type="EMAIL" role="FROM" value="account@company.com"/>
	</SENDER>

	<MESSAGE priority="3">
		<ADDRESS type="SMS" role="TO" value="0410507753" status="INITIATOR" priority="1"></ADDRESS>
		<ADDRESS type="SMS" role="TO" value="0402469846" status="INITIATOR" priority="1"></ADDRESS>
		<ADDRESS type="SMS" role="TO" value="0418235612" status="INITIATOR" priority="1"></ADDRESS>
		<SUBJECT>
			Multicast test
		</SUBJECT>

		<BODY type="TEXT">
			<PAYLOAD>
				Test SMS Message using XML.
			</PAYLOAD>
		</BODY>
	</MESSAGE>

</DOCUMENT>

Many to Many

The following is an example of sending many messages to many targets. This example will send "Test SMS Message using XML (Batch - 1)." to 0410507753 and "Test SMS Message using XML (Batch - 2)." to 0402469846.

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE DOCUMENT SYSTEM "http://localhost:8080/gateway/msg_core.dtd">

<DOCUMENT mode="NORMAL">

	<SENDER password="xxxx">
		<ADDRESS type="EMAIL" role="FROM" value="account@company.com"/>
	</SENDER>

	<MESSAGE priority="3">
		<ADDRESS type="SMS" role="TO" value="0410507753" status="INITIATOR" priority="1"></ADDRESS>
		<SUBJECT>
			Batch Test
		</SUBJECT>

		<BODY type="TEXT">
			<PAYLOAD>
				Test SMS Message using XML (Batch - 1).
			</PAYLOAD>
		</BODY>
	</MESSAGE>

	<MESSAGE priority="2">
		<ADDRESS type="SMS" role="TO" value="0402469846" status="INITIATOR" priority="1"></ADDRESS>
		<SUBJECT>
			Batch Test
		</SUBJECT>

		<BODY type="TEXT">
			<PAYLOAD>
				Test SMS Message using XML (Batch - 2).
			</PAYLOAD>
		</BODY>
	</MESSAGE>

</DOCUMENT>

XML Elements

Element

Attributes

Type

Required

DEFAULT/(DESCRIPTION)

<DOCUMENT>
- <SENDER>
- <REPLYTO>?
- <SMS>?
- <MESSAGE>+

ID

STRING

No

(assigned by message core)

 

TIMESTAMP

STRING

No

(assigned by message core)

 

MODE

STRING
[NORMAL
|TEST]

No

NORMAL
(when MODE is set to TEST, message will not be delivered)

 

VERSION

STRING

No

 

 

STATUS

STRING
[ACCEPTED
|REJECTED]

No

 

 

REASON

STRING

No

 

<SENDER>
- <ADDRESS>

PASSWORD

STRING

No

(this is your Amethon password)

 

 

 

 

(the attributes TYPE, ROLE and VALUE in <ADDRESS> must be provided as follow:
TYPE = "EMAIL"
ROLE = "FROM"
VALUE = email address)

<REPLYTO>
- <ADDRESS>

 

 

 

(the attributes TYPE, ROLE and VALUE in <ADDRESS> must be provided as follow:
TYPE = "EMAIL"
ROLE = "REPLYTO"
VALUE = email address)

<SMS>
- <HEADER>
- <FOOTER>

 

 

 

(SMS specific features)

<HEADER>

 

STRING

No

(up to 11 ASCII characters that can be used instead of the senders mobile phone number (or instead of amethon.com). Dependent on carrier)

<FOOTER>

 

STRING

No

(appended to each message. Note that long messages will be truncated to accommodate the footer)

<MESSAGE>
- <ADDRESS>+
- <SUBJECT>?
- <BODY>

ID

STRING

No

 

 

PRIORITY

NUMBER

No

 

 

 

 

 

(the attributes TYPE, ROLE and VALUE in <ADDRESS> must be provided as follow:
TYPE = "SMS"
ROLE = "TO"
VALUE = recipient phone number starting 04)

<ADDRESS>

ID

STRING

No

 

 

TYPE

STRING
[SMS
|EMAIL
|FAX]

Yes

 

 

ROLE

STRING
[FROM
|TO
|CC
|BCC
|REPLYTO
|FORWARD]

Yes

 

 

VALUE

STRING

Yes

 

 

TIMESTAMP

STRING

No

 

 

STATUS

STRING
[INIT
|ACK
|DELIVERED]

No

 

 

REASON

STRING

No

 

 

PRIORITY

NUMBER

No

 

<SUBJECT>

 

STRING

No

(email subject(not used for SMS))

<BODY>
- <PAYLOAD>

TYPE

STRING
[TEXT
|IMAGE]

Yes

TEXT

<PAYLOAD>

 

STRING

Yes

(body payload – the actual data. text of message to send. Note max message + footer = 160 chars)

 

type

STRING
[TEXT
|RINGTONE
|LOGO
|MOTOROLA
|OTT
|RTTTL
|GIF
|BITMAP]

Yes

 

 

encoding

STRING
[ASCII
|BASE64
|HEX]

Yes

 

 

width

NUMBER

For LOGO, GIF & BITMAP

Width in pixels. Normally 72 for Nokia phones

 

height

NUMBER

 

Height in pixels. Normally 14 for LOGO or 28 for PICTURE message

 

depth

NUMBER

 

Bits per pixel. Normally 1

 

mcc

NUMBER

For LOGO

Country code:
For example:
505: Australia

 

mnc

NUMBER

 

Network code:
For example:
01: Telstra
02: Optus
03: Vodafone

 

-