SMS Server Tools 3

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. 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. 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.

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.
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.

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.