Custom Search

This site is hosted by Kekekasvi.com.

Menu
Home
Basic information:
Slideshow, watch this first
License
How to compile/install
- Instructions for Windows
How to configure
- Configuring providers
Localizing
How to run/use
SMS file format
- User Data Header
Additional information:
Version history (3.x)
Hardware compatibility
Status monitor, Statistics file
Event handler, Alarm handler
Blacklist and Whitelist
Support:
Frequently asked questions
SMSTools3 Community
Get SMS Server Tools 3:
Download

Sponsored links
Search
Search
Visitor locations

SMS file format
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:
To: 491721234567
Flash: yes
Alphabet: ISO
Hello Stefan, how are you?
NOTE: Headers are case-sensitive.
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". With version >= 3.1 the number
can be given using grouped format, like 358 12 345 6789.
To_TOA Available from version >= 3.1.5. Can be used to define receivers Type Of
Address. This is also called "numbering plan". Possible values are
Unknown No type is defined. Short numbers
preceeded with "s" uses this value by
default.
International Number is international. This is default for
other than short numbers.
National Number is national. No country code is
included. Some short numbers only work
with this value.
See Using Type Of Address selection for more details.
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.
GSM 7 bit character set, as described in the GSM
specification.
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.
SMS Server Tools 3 6/5/2014
http://smstools3.kekekasvi.com/index.php?p=fileformat 1 / 6
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 User data header in hex-dump format. See udh.html and GSM 03.38. From
version >= 3.1 also binary message can have UDH-DATA defined.
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 [providers] 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.
0 disabled
1 enabled, no part-number
2 enabled, text numbers
3 enabled, concatenated format (not supported by
some phones)
Priority Available from version >= 3.0. Possible value is:
High Message 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 ...
167
12 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.
After version >= 3.1 additional TIME: number definition can be used. After
a time has reached, hang up is done. If a call is answered before a time is
reached, normal sound playing is done. NOTE that this time counting
starts after a command is given to the modem and there will be some
delay before receiving device starts ringing. You should test this with your
own handset to find a reasonable time which works fine in the network
you are using. Example:
TONE: TIME: 15 2 #
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.
SMS Server Tools 3 6/5/2014
http://smstools3.kekekasvi.com/index.php?p=fileformat 2 / 6
After version 3.1.3 VTS command usage can be selected with
voicecall_vts_list setting, see the How to configure for more details.
After version 3.1.5 there is a new voicecall_ignore_modem_response
setting for problematic devices, see the How to configure for more details.
Also notice voicecall_hangup_ath setting if AT+CHUP does not hangup call
on your device.
After version 3.1.7 there is a voicecall_cpas setting available. If your
device returns OK immediately after a dial command, with this setting
AT+CPAS can be used to detect when a call is answered. With this
setting TIME: has no effect.
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 keywords 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
LENGTH Set 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.
Include Filename. Available from >= 3.1.
Some parts of a message can be read from different file. If an included file
contains only text part, it should begin with one empty line.
Macro Definition. Available from >= 3.1.
Syntax is: Macro: name=value. Multiple macros can be defined. All name's
found in the message body are replaced with a value.
System_message Boolean value. Available from version >= 3.1.
With this setting message is sent as a system message. This kind of
message has fixed values 0x40 for Protocol Identifier and 0xF4 for Digital
Coding Scheme. A message cannot have User Data Header. Maximum
length of a message is 140 bytes.
After version >= 3.1.7, value for this setting can be 2 or ToSIM for
communicating with SIM applications. SMS is sent as SS (no show) and
stored (sent) to SIM. Currently this only works with binary messages.
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_id ID number of a sent message.
Sent Time 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.
SMS Server Tools 3 6/5/2014
http://smstools3.kekekasvi.com/index.php?p=fileformat 3 / 6
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)
01 : Push Transaction Id
06 : PDU Type Push, (WAP-230-WSP Table 34)
LENGTH // Headers Length will be placed to this position
AE : Push Header Content-Type: application/vnd.wap.sic 0x2E | 0x80
# (http://www.wapforum.org/wina/wsp-content-type.htm)
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.
SMS Server Tools 3 6/5/2014
http://smstools3.kekekasvi.com/index.php?p=fileformat 4 / 6
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.
Length Available from >= 3.1. Length of text / data. With Unicode text number of
Unicode characters. If non-Unicode text message is stored using UTF-8,
number of bytes may differ.
Flash Available from >= 3.1. Boolean value. This header exists if a message was
received as a flash (immediate display). Note that usually phone devices do not
save flash messages, they can be saved manually if necessary.
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.
Using Type Of Address selection
When SMSTools sends a message, it must tell to the Service Center what kind of number is
used as a destination number. This is called "Type Of Address". There are three possible
values: "unknown", "international" and "national".
By default SMSTools assumes that:
Any number without "s" is an international number.
Numbers with "s" are "short" numbers and unknown Type Of Address is used.
However, all "short" numbers do not work with "unknown" type. This is an operator depended
issue and varies by country. Because of this, version >= 3.1.5 has a new header To_TOA
which can be used to manually define Type Of Address.
Type Of Address selection can be automated using two global settings in the configuration
file: international_prefixes and national_prefixes. Both settings are comma separated list of
numbers.
If international_prefixes is defined, Type Of Address is international only if number matches
to the list. If it does not match, national Type Of Address is used.
If national_prefixes is defined, Type Of Address is national if number matches to the list.
SMS Server Tools 3 6/5/2014
http://smstools3.kekekasvi.com/index.php?p=fileformat 5 / 6
And last, if there is To_TOA defined in the message file, this setting is used as it overrides
everything else.
For example:
System is located in Finland and it's used to send messages mainly to Finland, Sweden
and United Kingdom. Both international and national number formats are used (for
finnish numbers) and local short numbers should use national Type Of Address. Global
configuration setting international_prefixes = 358,46,44 is enough for normal operation.
With this setup, if SMS should be sent to Germany, it can be done with To_TOA:
international header.
Another example:
Still in Finland. Any mobile phone number should work without additional headers.
Messages to the short numbers use "s" or will have To_TOA header if necessary. Global
configuration setting national_prefixes = 04, 05 or shortly national_prefixes = 0 is
enough as finnish mobile numbers start with 04 or 05. Messages to those numbers are
sent using national Type Of Address, any other number will use international type.
Privacy Policy SMS Server Tools 3 Copyright Keijo Kasvi.
SMS Server Tools 3 6/5/2014
http://smstools3.kekekasvi.com/index.php?p=fileformat 6 / 6