SMS Server Tools 3

Home

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
Alphabet: ISO

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. This is the default.
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.
binary The short message contains 8-bit binary data, no text.

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

UDH Only binary messages: Boolean value, tells if the message data contains a user data header. Default is true.
UDH-DATA Only text messages: User data header in hex-dump format. See udh.html and GSM 03.38.
SMSC Phone number of the SMSC. From version >= 3.1 this setting is ignored if there is no smsc set in the config file.
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. Without this line, the setting from config file is used.
Autosplit Controls if and how the program splits large text messages. Without this line, the setting from config file is used. The program does not split binary messages, Unicode messages and text messages with UDH.
0disabled
1enabled, no part-number
2enabled, text numbers
3enabled, concatenated format (not supported by some phones)
Priority Available from version >= 3.0. Possible value is:
highMessage is handled first when moving to spooler and when taking from spooler to sending
Validity Available from version >= 3.0. Defines a message validity period. Without this line, the setting from config file is used.

You can specify value as a number following one of the keywords: min, hour, day, week, month or year. Validity period will be rounded down to the nearest possible value.

If you do not use any of those keywords, value will have the following meaning:
0 ... 143(value + 1) * 5 minutes (i.e. 5 minutes intervals up to 12 hours)
144 ... 16712 hours + ((value - 143) * 30 minutes) (i.e. 30 min intervals up to 24 hours)
168 ... 196(value - 166) * 1 day (i.e. 1 day intervals up to 30 days)
197 ... 255(value - 192) * 1 week (i.e. 1 week intervals up to 63 weeks)
Incorrect values are ignored.
Voicecall Boolean value. Available from version >= 3.0.

With this feature the smsd will make a voice call to the receivers phone number given in To: header. If the receiver answers to the call, some DTMF tones are played.
The message text must start with TONE: keyword. After this there can be number and space, which is number of times to repeat the tone sending. Supported tones are #,*,0...9 and the tone list must be comma separated.
For example:
TONE:   1,2,3,4,5,6,7,8,9,0
- this plays all digits, and it's repeated 3 times which is the default.

TONE:   5   #,#,#
- this plays three #'s, and it's repeated 5 times.

TONE:
- some default tones are played 3 times.

Before using this feature to serious alarm purposes, you should test if this works with you modem/phone. Also notice that automatic redialing should be turned off in the phone's settings.

Hex Boolean value. Available from version >= 3.0.

Together with Alphabet: binary setting the binary data can be presented in hexadecimal format.
One byte should be presented with two hexadecimal characters, for example 0F. Text can have empty lines and comment lines starting with /, ', # or : character. Also after hexadecimal bytes there can be a comment character marking the rest of line as a comment.

Special keyword available:
STRING:A normal string can be presented (without needing to type it in hex)
INLINESTRING:As STRING:, but Inline String token and termination null are automatically added
LENGTHSet this keyword to the place where the following bytes should be counted. Next LENGTH keyword will place the counted number to the place where the first keyword was. Nesting is not possible.
See example below for more details.

Replace Numeric code 1...7. Available from >= 3.0.9.

If a receiving device and SIM supports "Replace Short Message Type n" -feature, a previously received message with the same code is replaced with a new message. Only the messages sent from the same originating address can be replaced. If there is nothing to replace, a message is stored in the normal way.

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

Available from >= 3.0. After a message is sent, there will be automatically generated Message_id header line if a status report was requested. With version >= 3.1 there will also be Sent timestamp:
Message_idID number of a sent message.
SentTime when the message was sent by the program.

Available from >= 3.0.6.
Modem Name of the modem which was used to send this message.

Available from >= 3.0.9.
IMSI International Mobile Subscriber Identity from the SIM, if this request is supported.

Binary data

The data begins after the empty line and goes until end of file. No conversion is applied to the data. Data messages are limited to 140 bytes.

Example:

To: 491721234567
Alphabet: binary
UDH: true

gs2389gnsakj92"§Z/%$§"($)$(%ÄÖÜ?))((HJHG&(()/&§")(LJUFDZ)=W)==/685tgui
3ge^!"§$EGHWZFT&Z%8785ttghjjhdjkgfjsbfjwr793thruewgfh7328hgtwhg87324hf
hwer32873g&%§=)(/&%$%&/(/&%$§%&hdsgrwwq(/&%$fgzw543t43g5jwht934zt743g

Another example, available from version >= 3.0:

To: 491721234567
Alphabet: binary
Hex: yes

// This is a sample Wap Push message:

06 : user Data Header Length (6 Octets)
05 : Identifer Element (16 Bit port addressing)
04 : Length of Parameter values (4 Octets)
# WAP Push connectionless session service (client side), Protocol: WSP/Datagram:
0B 84 : push dest port (2948)
# WAP connectionless session service Protocol: WSP/Datagram:
23 F0 : push originator port (9200)

03 : Push Transaction Id
06 : PDU Type Push, (WAP-230-WSP Table 34)
LENGTH // Headers Length will be placed to this position
// Content type: Encoding-Version 1.3
03 AE8184 456E636F64696E672D56657273696F6E 00 312E33 00
// Push headers:
AF 82 B4 85
LENGTH // This stops the counting and places the number

02 : WBXML version 1.2
05 : SL 1.0 Public Identifier
04 : Charset = iso-8859-1
00 : String table length
45 : s1, with content
C6 : indication, with content and attributes
0D : Token for "href=http://www."
### There should not be extra spaces after keyword:
INLINESTRING:xyz
85 : Token for ".com/"
03 : Inline string follows
STRING:ppaid/123/abc.wml
00 : End of string
11 : si-id
INLINESTRING:1
01 : close of indication attribute list
INLINESTRING:Wap push demo from smstools3.
01 : End of indication element
01 : END of si element

# Specifications can be found from here:
# http://www.openmobilealliance.org/tech/affiliates/wap/wapindex.html

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: ISO
UDH: false

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

From Senders phone number.
From_TOA Available from >= 3.0.9. Type Of Address definition of senders phone number.
For example: "91 international, ISDN/telephone".
From_SMSC The SMS service centre, that sent you this message.
Subject The name of the modem that received this message.
IMSI Available from >= 3.0.9. International Mobile Subscriber Identity from the SIM, if this request is supported.
Report Available from >= 3.0.9. Tells if a status report is going to be returned to the SME.
Replace Available from >= 3.0.9. Replace Short Message Type 1..7 number, if defined.
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.
UDH Boolean value. Tells if the message contains a user data header.
UDH-DATA This is the UDH in hex-dump format if the message contains an UDH. See udh.html and GSM 03.38.

From version >= 3.0.9 there can be additional headers in case of some problems:
Error Tells if there was fatal errors and a message was not decoded.
Text part of message will tell more details and has no usual content.
Warning Tells if there was minor proglems in the message data.

The filenames of received messages 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:

From: 491721234567
From_SMSC: 491722270333
Sent: 00-02-21 22:26:23
Received: 00-02-21 22:26:29
Subject: modem1
Alphabet: ISO
UDH: false

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.
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/pdu.c if you need a list of all possible status codes.