4 The SMS module for Asterisk was developed by Adrian Kennard, and is an
5 implementation of the ETSI specification for landline SMS, ETSI ES 201
6 912, which is available from www.etsi.org. Landline SMS is starting to
7 be available in various parts of Europe, and is available from BT in
8 the UK. However, Asterisk would allow gateways to be created in other
9 locations such as the US, and use of SMS capable phones such as the
10 Magic Messenger. SMS works using analogue or ISDN lines.
14 Short Message Service (SMS), or texting is very popular between mobile
15 phones. A message can be sent between two phones, and normally
16 contains 160 characters. There are ways in which various types of data
17 can be encoded in a text message such as ring tones, and small
18 graphic, etc. Text messaging is being used for voting and
19 competitions, and also SPAM...
20 Sending a message involves the mobile phone contacting a message
21 centre (SMSC) and passing the message to it. The message centre then
22 contacts the destination mobile to deliver the message. The SMSC is
23 responsible for storing the message and trying to send it until the
24 destination mobile is available, or a timeout.
25 Landline SMS works in basically the same way. You would normally have
26 a suitable text capable landline phone, or a separate texting box such
27 as a Magic Messenger on your phone line. This sends a message to a
28 message centre your telco provides by making a normal call and sending
29 the data using 1200 Baud FSK signaling according to the ETSI spec. To
30 receive a message the message centre calls the line with a specific
31 calling number, and the text capable phone answers the call and
32 receives the data using 1200 Baud FSK signaling. This works
33 particularly well in the UK as the calling line identity is sent
34 before the first ring, so no phones in the house would ring when a
37 Typical use with Asterisk
39 Sending messages from an Asterisk box can be used for a variety of
40 reasons, including notification from any monitoring systems, email
42 Receiving messages to an Asterisk box is typically used just to email
43 the messages to someone appropriate - we email and texts that are
44 received to our direct numbers to the appropriate person. Received
45 messages could also be used to control applications, manage
46 competitions, votes, post items to IRC, anything.
47 Using a terminal such as a magic messenger, an Asterisk box could ask
48 as a message centre sending messages to the terminal, which will beep
49 and pop up the message (and remember 100 or so messages in its
58 Short Message Service Centre
59 The system responsible for storing and forwarding messages
62 A message on its way from a mobile or landline device to the SMSC
65 A message on its way from the SMSC to the mobile or landline device
68 A message coming in to the Asterisk box
71 A message going out of the Asterisk box
75 When sending a message to a landline, you simply send to the landline
76 number. In the UK, all of the mobile operators (bar one) understand
77 sending messages to landlines and pass the messages to the BTText
78 system for delivery to the landline.
79 The specification for landline SMS allows for the possibility of more
80 than one device on a single landline. These can be configured with Sub
81 addresses which are a single digit. To send a message to a specific
82 device the message is sent to the landline number with an extra digit
83 appended to the end. The telco can define a default sub address (9 in
84 the UK) which is used when the extra digit is not appended to the end.
85 When the call comes in, part of the calling line ID is the sub
86 address, so that only one device on the line answers the call and
88 Sub addresses also work for outgoing messages. Part of the number
89 called by the device to send a message is its sub address. Sending
90 from the default sub address (9 in the UK) means the message is
91 delivered with the sender being the normal landline number. Sending
92 from any other sub address makes the sender the landline number with
93 an extra digit on the end.
94 Using Asterisk, you can make use of the sub addresses for sending and
95 receiving messages. Using DDI (DID, i.e. multiple numbers on the line
96 on ISDN) you can also make use of many different numbers for SMS.
100 app_sms.c is included in the Asterisk source apps directory and is
101 included in the object list (app_sms.so) in apps/Makefile.
102 smsq.c is a stand alone helper application which is used to send SMSs
103 from the command line. It uses the popt library. A line for your make
106 cc -O -o smsq smsq.c -lpopt
110 The following contexts are recommended.
111 ; Mobile Terminated, RX. This is used when an incoming call from the SMS arrive
112 s, with the queue (called number and sub address) in ${EXTEN}
113 ; Running an app after receipt of the text allows the app to find all messages
114 in the queue and handle them, e.g. email them.
115 ; The app may be something like smsq --process=somecommand --queue=${EXTEN}
116 to run a command for each received message
117 ; See below for usage
119 exten = _X.,1, SMS(${EXTEN}|a)
120 exten = _X.,2,System("someapptohandleincomingsms ${EXTEN}")
122 ; Mobile originated, RX. This is receiving a message from a device, e.g. a Magi
123 c Messenger on a sip extension
124 ; Running an app after receipt of the text allows the app to find all messages
125 in the queue and handle then, e.g. sending them to the public SMSC
126 ; The app may be something like smsq --process=somecommand --queue=${EXTEN}
127 to run a command for each received message
128 ; See below for example usage
130 exten = _X.,1, SMS(${EXTEN}|sa)
131 exten = _X.,2,System("someapptohandlelocalsms ${EXTEN}")
134 smsmtrx is normally accessed by an incoming call from the SMSC. In the
135 UK this call is from a CLI of 080058752X0 where X is the sub address.
136 As such a typical usage in the extensions.conf at the point of
137 handling an incoming call is:-
138 exten = _X./8005875290,1,Goto(smsmtrx,${EXTEN},1)
139 exten = _X./_80058752[0-8]0,1,Goto(smsmtrx,${EXTEN}-${CALLERIDNUM:8:1},1)
141 Alternatively, if you have the correct national prefix on incoming
142 CLI, e.g. using zaphfc, you might use:-
143 exten = _X./08005875290,1,Goto(smsmtrx,${EXTEN},1)
144 exten = _X./_080058752[0-8]0,1,Goto(smsmtrx,${EXTEN}-${CALLERIDNUM:9:1},1)
146 smsmorx is normally accessed by a call from a local sip device
147 connected to a Magic Messenger. It could however by that you are
148 operating Asterisk as a message centre for calls from outside. Either
149 way, you look at the called number and goto smsmorx. In the UK, the
150 SMSC number that would be dialed is 1709400X where X is the caller sub
151 address. As such typical usage in extension.config at the point of
152 handling a call from a sip phone is:-
153 exten = 17094009,1,Goto(smsmorx,${CALLERIDNUM},1)
154 exten = _1709400[0-8],1,Goto(smsmorx,${CALLERIDNUM}-{EXTEN:7:1},1)
158 smsq is a simple helper application designed to make it easy to send
159 messages from a command line. it is intended to run on the Asterisk
160 box and have direct access to the queue directories for SMS and for
162 In its simplest form you can send an SMS by a command such as
163 smsq 0123456789 This is a test to 0123456789
164 This would create a queue file for a mobile originated TX message in
165 queue 0 to send the text "This is a test to 0123456789" to 0123456789.
166 It would then place a file in the /var/spool/asterisk/outgoing
167 directory to initiate a call to 17094009 (the default message centre
168 in smsq) attached to application SMS with argument of the queue name
170 Normally smsq will queue a message ready to send, and will then create
171 a file in the Asterisk outgoing directory causing Asterisk to actually
172 connect to the message centre or device and actually send the pending
174 Using --process, smsq can however be used on received queues to run a
175 command for each file (matching the queue if specified) with various
176 environment variables set based on the message (see below);
185 Specify a specific queue
186 In no specified, messages are queued under queue "0"
189 Specify destination address
192 Specify originating address
193 This also implies that we are generating a mobile terminated message
196 Specify the actual message
199 Specify a file to be read for the context of the message
200 A blank filename (e.g. --ud-file= on its own) means read stdin. Very
201 useful when using via ssh where command line parsing could mess up the
205 Mobile terminated message to be generated
207 Mobile originated message to be generated
214 Generate a message in the receive queue
216 Treat the file as UTF-8 encoded (default)
218 Treat the file as raw 8 bit UCS-1 data, not UTF-8 encoded
220 Treat the file as raw 16 bit bigendian USC-2 data
222 Specific a command to process for each file in the queue
223 Implies --rx and --mt if not otherwise specified.
224 Sets environment variables for every possible variable, and also ud,
225 ud8 (USC-1 hex), and ud16 (USC-2 hex) for each call. Removes files.
227 Specify the channel for motx calls
228 May contain X to use sub address based on queue name or may be full
230 Default is Local/1709400X
232 Specify the caller ID for motx calls
233 The default is the queue name without -X suffix
235 Wait time for motx call
238 Retry time for motx call
241 Retries for motx call
244 Specify the channel for mttx calls
245 Default is Local/ and the queue name without -X suffix
247 Specify the callerid for mttx calls
248 May include X to use sub address based on queue name or may be full
250 Default is 080058752X0
252 Wait time for mttx call
255 Retry time for mttx call
258 Retries for mttx call
260 --default-sub-address
261 The default sub address assumed (e.g. for X in CLI and dialled numbers
262 as above) when none added (-X) to queue
266 Create queue, but do not dial to send message
268 Do not wait if a call appears to be in progress
269 This could have a small window where a message is queued but not
270 sent, so regular calls to smsq should be done to pick up any missed
273 How many concurrent calls to allow (per queue), default 1
283 Specific hex string of user data header specified (not including the
285 May be a blank string to indicate header is included in the user data
286 already but user data header indication to be set.
288 Status report requested
290 Return path requested
292 Specify validity period (seconds)
294 Specify timestamp (YYYY-MM-DDTHH:MM:SS)
296 Spool dir (in which sms and outgoing are found)
297 Default /var/spool/asterisk
299 Other arguments starting '-' or '--' are invalid and will cause an
300 error. Any trailing arguments are processed as follows:-
301 * If the message is mobile originating and no destination address
302 has been specified, then the first argument is assumed to be a
304 * If the message is mobile terminating and no destination address
305 has been specified, then the first argument is assumed to be the
307 * If there is no user data, or user data file specified, then any
308 following arguments are assumed to be the message, which are
310 * If no user data is specified, then no message is sent. However,
311 unless --no-dial is specified, smsq checks for pending messages
312 and generates an outgoing anyway
314 Note that when smsq attempts to make a file in
315 /var/spool/asterisk/outgoing, it checks if there is already a call
316 queued for that queue. It will try several filenames, up to the
317 --concurrent setting. If these files exist, then this means Asterisk
318 is already queued to send all messages for that queue, and so Asterisk
319 should pick up the message just queued. However, this alone could
320 create a race condition, so if the files exist then smsq will wait up
321 to 3 seconds to confirm it still exists or if the queued messages have
322 been sent already. The --no-wait turns off this behaviour. Basically,
323 this means that if you have a lot of messages to send all at once,
324 Asterisk will not make unlimited concurrent calls to the same message
325 centre or device for the same queue. This is because it is generally
326 more efficient to make one call and send all of the messages one after
328 smsq can be used with no arguments, or with a queue name only, and it
329 will check for any pending messages and cause an outgoing if there are
330 any. It only sets up one outgoing call at a time based on the first
331 queued message it finds. A outgoing call will normally send all queued
332 messages for that queue. One way to use smsq would be to run with no
333 queue name (so any queue) every minute or every few seconds to send
334 pending message. This is not normally necessary unless --no-dial is
335 selected. Note that smsq does only check motx or mttx depending on the
336 options selected, so it would need to be called twice as a general
338 UTF-8 is used to parse command line arguments for user data, and is
339 the default when reading a file. If an invalid UTF-8 sequence is
340 found, it is treated as UCS-1 data (i.e, as is).
341 The --process option causes smsq to scan the specified queue (default
342 is mtrx) for messages (matching the queue specified, or any if queue
343 not specified) and run a command and delete the file. The command is
344 run with a number of environment variables set as follows. Note that
345 these are unset if not needed and not just taken from the calling
346 environment. This allows simple processing of incoming messages
349 Set if a queue specified
351 srr is set (to blank) if srr defined and has value 1.
353 rp is set (to blank) if rp defined and has value 1.
355 User data, UTF-8 encoding, including any control characters, but with
357 Useful for the content of emails, for example, as it includes any
360 User data, escaped UTF-8, including all characters, but control
361 characters \n, \r, \t, \f, \xxx and \ is escaped as \\
362 Useful guaranteed one line printable text, so useful in Subject lines
365 Hex UCS-1 coding of user data (2 hex digits per character)
366 Present only if all user data is in range U+0000 to U+00FF
368 Hex UCS-2 coding of user data (4 hex digits per character)
370 Other fields set using their field name, e.g. mr, pid, dcs, etc. udh
375 By default all queues are held in a director /var/spool/asterisk/sms.
376 Within this directory are sub directories mtrx, mttx, morx, motx which
377 hold the received messages and the messages ready to send. Also,
378 /var/log/asterisk/sms is a log file of all messages handled.
379 The file name in each queue directory starts with the queue parameter
380 to SMS which is normally the CLI used for an outgoing message or the
381 called number on an incoming message, and may have -X (X being sub
382 address) appended. If no queue ID is known, then 0 is used by smsq by
383 default. After this is a dot, and then any text. Files are scanned for
384 matching queue ID and a dot at the start. This means temporary files
385 being created can be given a different name not starting with a queue
386 (we recommend a . on the start of the file name for temp files).
387 Files in these queues are in the form of a simple text file where each
388 line starts with a keyword and an = and then data. udh and ud have
389 options for hex encoding, see below.
390 UTF-8. The user data (ud) field is treated as being UTF-8 encoded
391 unless the DCS is specified indicating 8 bit format. If 8 bit format
392 is specified then the user data is sent as is.
393 The keywords are as follows:-
395 oa Originating address
396 The phone number from which the message came
397 Present on mobile terminated messages and is the CLI for morx messages
400 The phone number to which the message is sent
401 Present on mobile originated messages
403 The service centre time stamp
404 Format YYYY-MM-DDTHH:MM:SS
405 Present on mobile terminated messages
407 One byte decimal protocol ID
408 See GSM specs for more details
411 One byte decimal data coding scheme
412 If omitted, a sensible default is used (see below)
413 See GSM specs for more details
415 One byte decimal message reference
416 Present on mobile originated messages, added by default if absent
418 0 or 1 for status report request
419 Does not work in UK yet, not implemented in app_sms yet
422 See GSM specs for details
424 Validity period in seconds
425 Does not work in UK yet
427 Hex string of user data header prepended to the SMS contents,
428 excluding initial length byte.
429 Consistent with ud, this is specified as udh# rather than udh=
430 If blank, this means that the udhi flag will be set but any user data
431 header must be in the ud field
433 User data, may be text, or hex, see below
435 udh is specified as as udh# followed by hex (2 hex digits per byte).
436 If present, then the user data header indicator bit is set, and the
437 length plus the user data header is added to the start of the user
438 data, with padding if necessary (to septet boundary in 7 bit format).
439 User data can hold an USC character codes U+0000 to U+FFFF. Any other
440 characters are coded as U+FEFF
441 ud can be specified as ud= followed by UTF-8 encoded text if it
442 contains no control characters, i.e. only (U+0020 to U+FFFF). Any
443 invalid UTF-8 sequences are treated as is (U+0080-U+00FF).
444 ud can also be specified as ud# followed by hex (2 hex digits per
445 byte) containing characters U+0000 to U+00FF only.
446 ud can also be specified as ud## followed by hex (4 hex digits per
447 byte) containing UCS-2 characters.
448 When written by app_sms (e.g. incoming messages), the file is written
449 with ud= if it can be (no control characters). If it cannot, the a
450 comment line ;ud= is used to show the user data for human readability
451 and ud# or ud## is used.
455 The SMS specification allows for delivery reports. These are requested
456 using the srr bit. However, as these do not work in the UK yet they
457 are not fully implemented in this application. If anyone has a telco
458 that does implement these, please let me know. BT in the UK have a non
459 standard way to do this by starting the message with *0#, and so this
460 application may have a UK specific bodge in the near future to handle
462 The main changes that are proposed for delivery report handling are :-
463 * New queues for sent messages, one file for each destination
464 address and message reference.
465 * New field in message format, user reference, allowing applications
466 to tie up their original message with a report.
467 * Handling of the delivery confirmation/rejection and connecting to
468 the outgoing message - the received message file would then have
469 fields for the original outgoing message and user reference
470 allowing applications to handle confirmations better.