SMS Server Tools

SMS file format

Text messages

An SMS file is a text file that contains the message and a header. You have to store all SM you want to send in these files in the outgoing directory. The filename does not matter but it has to be unique. You may use the mktemp command to generate unique filenames.

Easy example:
To: 491721234567

Hello, this is the sms.

Write the phone number in international format without the leading +. When you like to send a message to a short number (for example to order a ringtone), then preceed it with an "s".

More complex example:
From: Stefan
To: 491721234567
Flash: yes

Hello Stefan, how are you?

You can add as many header lines, as you like. When the program finds an unknown header, it simply ignores that line. You can use the following header lines:

From Senders name or phone number. This field has currently no function to the software.
To Receivers phone number in international format without the leading +. When you like to send a message to a short number (for example to order a ringtone), then preceed it with an "s".
Flash Boolean value. If yes, then the message appears directly on the phones display. Most phones support this feature, but not all.
Alphabet Tells the program what character set is used in this sms file. Possible values are

ISO
Latin
Ansi
Normal 8 bit character set, also called Ansi or Latin-1.All three keywords do the same. If the text is longer than 160 characters, then the program can split it automatically.
GSM 7 bit character set, as described in the GSM specification, with one exception: The @ character is represented by the character code 0xB7. If the text is longer than 160 characters, the program can split it automatically.
UCS
Chinese
Unicode
UCS2 character set, maximum 70 characters. All three values do the same. The header must be written with an 8 bit character set but the message text part must be written with the 16 bit Unicode (big endian) character set. Please checkout the scripts directory, it contains some useful scripts for file format conversion.

The program checks only the first 3 characters of that line, therefore keywords like ISO-8859-15 or UCS-2 will also work fine.

Note: In case of boolean values you can use true, yes, on or 1 for positive values. All other words are interpreted as negative.

Binary SMS, Operator Logos, Ringtones

If the message has binary content it will be sent as 8 Bit. The binary data begins after the empty line and goes until end of file. Binary messages are limited to 140 bytes.

Example:

To: 491721234567
Alphabet: binary
UDH: true

gs2389gnsakj92fs2ujtiegbhewqu2ir9jsdgufh3gjeruqgh87zt243htgerugsqh
3gert324543t43g5jwht934zt743gfjsbfjwr793thruewgfh7328hgtwhg87324hf
hwer32873gert324543t43g5jwht934zt743g

You can use the following header lines:

From Senders name or phone number. This field has currently no function to the software.
To Senders name or phone number. This field has currently no function to the software.
Alphabet binary
Binary true, whis means the same as Alphabet: binary. This is for compatibility to older versions.
UDH Boolean value.Set it to yes, if the data contains an User Data Header (see GSM 03.38 specification). The default is yes, because most binary messages contain an UDH.

Received messages

The received SMS are stored in the same format as described above but they have some additional header lines. For example:

From: 491721234567
From_SMSC: 491722270333
Sent: 00-02-21 22:26:23
Received: 00-02-21 22:26:29
Subject: modem1
Alphabet: ISO8859-15

This is the Text that I have sent with my mobile phone to the computer.

From Senders phone number.
From_SMSC The SMS service centre, that sent you this message.
Subject The name of the modem that received this message.
Sent Time when the message was sent.
Received Time when the message was received by the program.
Alphabet Tells the character set of the message text.

The filenames of received SMS look like modem1.xyzxyz. They begin with the name of the modem that received the message, followed by a dot, followed by six random characters.

Status Reports

You can request and receive status reports, if the SMSC and your modem support this feature. Example:

Some header lines, as described above

SMS STATUS REPORT
Message_id: 117
Discharge_timestamp: 00-02-21 22:27:01
Status: 0,Ok,short message received by the SME

Message_id This is the ID number of the previously sent message, where this status report belongs to. The SMSC gives each sent message such a number. You can use eventhandler scripts, if you need to store the ID's of sent messages.
Discharge_timestamp This is the time, when the message was successfully delivered or when it was discarded by the SMSC.
Status The status of the message. Please take a look into the source code src/getsms.c if you need a list of all possible status codes.

More header lines

The program supports some more header lines, that can be used to override settings from the configuration file.

SMSC Phone number of the SMSC
Provider
Queue
Name of the provider, can be used to override the normal sorting algorithm configured by [provider] and [queues] in the config file. Both keywords do the same.
Report Boolean value. Controls if a status report is requested for this message.
Autosplit Boolean value. Controls if the program shall split the message automatically in case it is larger than 160 characters.


Note 1)
In GSM alphabet, the @ character has the value 0x00. This value is not a valid string character in C programming language, therefore my software uses the replacement 0xB7. All other characters match the GSM specification.