SMS-for-Applications - XML

Retarus SMS-for-Applications is an interface that enables you to send text messages quickly and easily from all types of business applications. Its usage is similar to any other web service.

This technical documentation was created for our customers’ project teams, software development departments, and consultants responsible for implementing the service. It describes all default parameters and additional possible settings. Moreover, the document outlines the different ways of securing data transmission within this service and gives you an overview of further options.

Document and application version

The present version of this documentation describes all of the current functions of Retarus SMS-for-Applications.

How it works

The text message to be sent is transmitted to the Retarus SMS for Applications service by means of an XML file. This XML file consists of the message as well as the recipients’ mobile phone numbers and all necessary transmission parameters. Immediately after receiving and checking the XML file, the message is delivered automatically to all indicated phone numbers.

Interface definition

Retarus SMS for Applications provides data transmission via HTTPS by default. Currently there are no other transmission protocols available. The job data is transferred by means of an HTTPS POST request.

XML tags

The XML tag identifiers are not “case sensitive” – i.e., our systems do not differentiate between upper- and lower-case letters. However, start tags and end tags always have to be identical.

General XML tags

The tags in the table below can be used for any document that will be processed. Each job’s tags are embedded in a <data> tag and are required to end with a corresponding end tag (e.g., </data>). Unless specified otherwise, all tags and attributes are to be used only once within the same job.

Tag name	Field	Description/usage/parameter
data	m	This tag indicates the start and the end of a job. It should only be used once within the same job - i.e., you have to create a new XML file for each job.
message	m	This tag contains the message text that has to be sent. The maximum length of the text depends on the selected character set: for GSM7 157 characters for UTF-16 67 characters
numbers	M	This tag serves as the hierarchical grouping of the individual mobile phone numbers that follow it.
number	M	This tag indicates the recipient’s mobile phone number. It may be used several times within the same job.
userId	M	Your personal access code to Retarus SMS for Applications. The User ID will automatically be sent to you after service installation is complete.
password	M	The password that corresponds to your User ID.
property	O	Some attributes of the property enable you to configure parts of the SMS transmission (see the table below and How it works). Defaults are written in italics.

M indicates a “must” field, and O indicates an optional field that can be configured for additional features.

Because multi-part SMS is possible, the maximum length of the message text depends on both the selected character set and the value in the Max SMS count field in the EAS application configuration. If the field is set to 2, the respective figures are 306 and 134 characters. The upper limit for the Max SMS count is 20, and the default is 3. Messages that exceed the limits applicable to the configured value in the Max SMS count field will be cut off.

The following table describes the attributes for property tags located in the maximum model XML job file (see XML file types). Default values are written in italics.

Property Name	Description/Usage
encoding	Identifies the character set to be used in the text message. Available parameters are: utf-16 default (= GSM7-bit encoding)
sender	This attribute may be used in order to define a sender ID. All default settings can be defined when configuring the application. A description of all limitations and available parameters is available in the appendix.
category	This attribute may contain a cost center in order to simplify your accounting processes. It is limited to 70 characters. The default settings are taken from the application configuration.
statusRequested	This attribute may be used in order to request the delivery status of every single text message. This optional function has additional fees. Available settings: true false
flash	This parameter indicates that an SMS pops up directly on the recipient‘s display without having to be recalled from the cache. This optional function has additional fees. Available settings: true false
id	This field enables you to send a unique system reference which will be included in your status reports. This will simplify the process of assigning the status reports to their corresponding transmission jobs. The length of the field is limited to 256 characters in accordance with ISO-8859-1.

Configuring the application

When configuring the application certain values are preset, which means that you will only have to specify the tags within the XML file if they differ from the default settings.

Value	Corresponding tag/property
Cost center – the default setting indicates your main cost center.	property/category
Sender ID – the default sender ID for your SMS transmissions	property/sender

XML file types

XML job file (maximum model)

The following example illustrates the structure of XML files.

This XML model comprises a job with the maximum amount of possible commands.

XML

<?xml version='1.0' encoding='UTF-8'?>
<data>
	<message>Please find included the requested information ....</message>
	<numbers>
		<number>004917612345678</number>
		<number>004917623456789</number>
		<number>004917634567890</number>
</numbers>
	<userId>myLogin</userId>
	<password>myPassword</password>
	<property name='encoding'>standard</property>
	<property name='sender'>YOUR SENDER</property>
	<property name='category'>YOUR CATEGORY</property>
	<property name='statusRequested'>true</property>
	<property name='flash'>false</property>
	<property name='id'>ID</property>
</data>

XML job file (minimal model)

The following example shows an XML file comprised of the minimum required parameters.

XML

<?xml version='1.0' encoding='ISO-8859-1'?>
<data>
	<message> Please find included the requested information....</message>
	<numbers>
		<number>004917612345678</number>
</numbers>
	<userId>myLogin</userId>
	<password>myPassword</password>
</data>

XML status report (maximum model)

This example shows a status report including all available information.

XML

<?xml version='1.0' encoding='ISO-8859-1'?>
<data>
	<system-id>R.20080121-132532.224-0fbozrnltTSJ2Y651G</system-id>
	<status>SUCCESSFUL</status>
	<id>Request A 1435</id>
	<numbers>
		<number status="SUC_ACC">004917612345678</number>
		<number status="SUC_ACC">004917623456789</number>
		<number status="SUC_ACC">004917634567890</number>
	</numbers>
</data>

XML status report (minimum model)

This example shows a status report that contains only minimal information. In this specific case, the job was rejected by the system.

XML

<?xml version='1.0' encoding='ISO-8859-1'?>
<data>
	<status>FAILED</status>
</data>

Character sets

Character set I corresponds to the GSM7-bit default character set. The characters in Character set II count as two characters.

Character set I

HEX	0	1	2	3	4	5	6	7
DEC
0	@	∆	[SPACE]	0	¡	P	¿	p
		16	32	48	64	80	96	112
1	£	_	!	1	A	Q	a	q
	1	17	33	49	65	81	97	113
2	$	Φ	"	2	B	R	b	r
	2	18	34	50	66	82	98	114
3	¥	Γ	#	3	C	S	c	s
	3	19	35	51	67	83	99	115
4	è	Λ	¤	4	D	T	d	t
	4	20	36	52	68	84	100	116
5	é	Ω	%	5	E	U	e	u
	5	21	37	53	69	85	101	117
6	ù	Π	&	6	F	V	f	v
	6	22	38	54	70	86	102	118
7	ì	Ψ	'	7	G	W	g	w
	7	23	39	55	71	87	103	119
8	ò	Σ	(	8	H	X	h	x
	8	24	40	56	72	88	104	120
9	ç	Θ	)	9	I	Y	i	y
	9	25	41	57	73	89	105	121
A	[CR]	Ξ	*	:	J	Z	j	z
	10	26	42	58	74	90	106	122
B	Ø	[ESC]	+	;	K	Ä	k	ä
	11	27	43	59	75	91	107	123
C	ø	Æ	,	<	L	Ö	l	ö
	12	28	44	60	76	92	108	124
D	[LF]	æ	-	=	M	Ñ	m	ñ
	13	29	45	61	77	93	109	125
E	Å	ß	.	>	N	Ü	n	ü
	14	30	46	62	78	94	110	126
F	å	É	/	?	O	§	o	à
	15	31	47	63	79	95	111	127

Character set II

HEX	0	1	2	3	4	5	6	7
DEC
0
		16	32	48	64	80	96	112
1
	1	17	33	49	65	81	97	113
2
	2	18	34	50	66	82	98	114
3
	3	19	35	51	67	83	99	115
4		^
	4	20	36	52	68	84	100	116
5							€
	5	21	37	53	69	85	101	117
6
	6	22	38	54	70	86	102	118
7
	7	23	39	55	71	87	103	119
8			}
	8	24	40	56	72	88	104	120
9			{
	9	25	41	57	73	89	105	121
A
	10	26	42	58	74	90	106	122
B				[
	11	27	43	59	75	91	107	123
C				~
	12	28	44	60	76	92	108	124
D				]
	13	29	45	61	77	93	109	125
E
	14	30	46	62	78	94	110	126
F			\
	15	31	47	63	79	95	111	127

The following characters have to be masked when they are utilized within an XML file:

<
>
&
"
'

Left angle bracket
Right angle bracket
Ampersand
Quote
Apostrophe

<
>
&
"
'

Retarus gateway server

https://sms4a.retarus.com/XmlSms/sms/

Specifying the Sender ID

The Sender ID may include a numeric value as well as alphanumeric text.

When using only numerals (e.g., a mobile phone number), the following specifications should be considered:

The usage of alphanumeric characters has to match the following specifications:

In this case, the Sender ID has to start and end with an alphabetic character.

Incorrect characters will replaced with the character 'X'.