Fix some tex errors
[asterisk/asterisk.git] / doc / tex / app-sms.tex
1 \section{Introduction}
2
3    The SMS module for Asterisk was developed by Adrian Kennard, and is an
4    implementation of the ETSI specification for landline SMS, ETSI ES 201
5    912, which is available from \url{www.etsi.org}. Landline SMS is starting to
6    be available in various parts of Europe, and is available from BT in
7    the UK. However, Asterisk would allow gateways to be created in other
8    locations such as the US, and use of SMS capable phones such as the
9    Magic Messenger. SMS works using analogue or ISDN lines.
10
11 \section{Background}
12
13    Short Message Service (SMS), or texting is very popular between mobile
14    phones. A message can be sent between two phones, and normally
15    contains 160 characters. There are ways in which various types of data
16    can be encoded in a text message such as ring tones, and small
17    graphic, etc. Text messaging is being used for voting and
18    competitions, and also SPAM...
19
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
26    Landline SMS works in basically the same way. You would normally have
27    a suitable text capable landline phone, or a separate texting box such
28    as a Magic Messenger on your phone line. This sends a message to a
29    message centre your telco provides by making a normal call and sending
30    the data using 1200 Baud FSK signaling according to the ETSI spec. To
31    receive a message the message centre calls the line with a specific
32    calling number, and the text capable phone answers the call and
33    receives the data using 1200 Baud FSK signaling. This works
34    particularly well in the UK as the calling line identity is sent
35    before the first ring, so no phones in the house would ring when a
36    message arrives.
37
38 \section{Typical use with Asterisk}
39
40    Sending messages from an Asterisk box can be used for a variety of
41    reasons, including notification from any monitoring systems, email
42    subject lines, etc.
43
44    Receiving messages to an Asterisk box is typically used just to email
45    the messages to someone appropriate - we email and texts that are
46    received to our direct numbers to the appropriate person. Received
47    messages could also be used to control applications, manage
48    competitions, votes, post items to IRC, anything.
49
50    Using a terminal such as a magic messenger, an Asterisk box could ask
51    as a message centre sending messages to the terminal, which will beep
52    and pop up the message (and remember 100 or so messages in its
53    memory).
54
55 \section{Terminology}
56
57 \begin{itemize}
58    \item SMS -
59    Short Message Service
60    i.e. text messages
61
62    \item SMSC -
63    Short Message Service Centre
64    The system responsible for storing and forwarding messages
65
66    \item MO -
67    Mobile Originated
68    A message on its way from a mobile or landline device to the SMSC
69
70    \item MT -
71    Mobile Terminated
72    A message on its way from the SMSC to the mobile or landline device
73
74    \item RX -
75    Receive
76    A message coming in to the Asterisk box
77
78    \item TX -
79    Transmit
80    A message going out of the Asterisk box
81 \end{itemize}
82
83 \section{Sub address}
84
85    When sending a message to a landline, you simply send to the landline
86    number. In the UK, all of the mobile operators (bar one) understand
87    sending messages to landlines and pass the messages to the BTText
88    system for delivery to the landline.
89
90    The specification for landline SMS allows for the possibility of more
91    than one device on a single landline. These can be configured with Sub
92    addresses which are a single digit. To send a message to a specific
93    device the message is sent to the landline number with an extra digit
94    appended to the end. The telco can define a default sub address (9 in
95    the UK) which is used when the extra digit is not appended to the end.
96    When the call comes in, part of the calling line ID is the sub
97    address, so that only one device on the line answers the call and
98    receives the message.
99
100    Sub addresses also work for outgoing messages. Part of the number
101    called by the device to send a message is its sub address. Sending
102    from the default sub address (9 in the UK) means the message is
103    delivered with the sender being the normal landline number. Sending
104    from any other sub address makes the sender the landline number with
105    an extra digit on the end.
106
107    Using Asterisk, you can make use of the sub addresses for sending and
108    receiving messages. Using DDI (DID, i.e. multiple numbers on the line
109    on ISDN) you can also make use of many different numbers for SMS.
110
111 \section{extensions.conf}
112
113    The following contexts are recommended.
114
115 \begin{astlisting}
116 \begin{verbatim}
117 ; Mobile Terminated, RX. This is used when an incoming call from the SMS arrive
118 s, with the queue (called number and sub address) in ${EXTEN}
119 ; Running an app after receipt of the text allows the app to find all messages
120 in the queue and handle them, e.g. email them.
121 ; The app may be something like   smsq --process=somecommand --queue=${EXTEN}
122 to run a command for each received message
123 ; See below for usage
124 [smsmtrx]
125 exten = _X.,1, SMS(${EXTEN},a)
126 exten = _X.,2,System("someapptohandleincomingsms ${EXTEN}")
127 exten = _X.,3,Hangup
128 ; Mobile originated, RX. This is receiving a message from a device, e.g.
129 ; a Magic Messenger on a sip extension
130 ; Running an app after receipt of the text allows the app to find all messages
131 ; in the queue and handle then, e.g. sending them to the public SMSC
132 ; The app may be something like   smsq --process=somecommand --queue=${EXTEN}
133 ; to run a command for each received message
134 ; See below for example usage
135 [smsmorx]
136 exten = _X.,1, SMS(${EXTEN},sa)
137 exten = _X.,2,System("someapptohandlelocalsms ${EXTEN}")
138 exten = _X.,3,Hangup
139 \end{verbatim}
140 \end{astlisting}
141
142    smsmtrx is normally accessed by an incoming call from the SMSC. In the
143    UK this call is from a CLI of 080058752X0 where X is the sub address.
144    As such a typical usage in the extensions.conf at the point of
145    handling an incoming call is:
146 \begin{astlisting}
147 \begin{verbatim}
148 exten = _X./8005875290,1,Goto(smsmtrx,${EXTEN},1)
149 exten = _X./_80058752[0-8]0,1,Goto(smsmtrx,${EXTEN}-${CALLERID(num):8:1},1)
150 \end{verbatim}
151 \end{astlisting}
152
153    Alternatively, if you have the correct national prefix on incoming
154    CLI, e.g. using dahdi\_hfc, you might use:
155 \begin{astlisting}
156 \begin{verbatim}
157 exten = _X./08005875290,1,Goto(smsmtrx,${EXTEN},1)
158 exten = _X./_080058752[0-8]0,1,Goto(smsmtrx,${EXTEN}-${CALLERID(num):9:1},1)
159 \end{verbatim}
160 \end{astlisting}
161
162    smsmorx is normally accessed by a call from a local sip device
163    connected to a Magic Messenger. It could however by that you are
164    operating Asterisk as a message centre for calls from outside. Either
165    way, you look at the called number and goto smsmorx. In the UK, the
166    SMSC number that would be dialed is 1709400X where X is the caller sub
167    address. As such typical usage in extension.config at the point of
168    handling a call from a sip phone is:
169 \begin{astlisting}
170 \begin{verbatim}
171 exten = 17094009,1,Goto(smsmorx,${CALLERID(num)},1)
172 exten = _1709400[0-8],1,Goto(smsmorx,${CALLERID(num)}-{EXTEN:7:1},1)
173 \end{verbatim}
174 \end{astlisting}
175
176 \section{Using smsq}
177
178    smsq is a simple helper application designed to make it easy to send
179    messages from a command line. it is intended to run on the Asterisk
180    box and have direct access to the queue directories for SMS and for
181    Asterisk.
182
183    In its simplest form you can send an SMS by a command such as
184    smsq 0123456789 This is a test to 0123456789
185    This would create a queue file for a mobile originated TX message in
186    queue 0 to send the text "This is a test to 0123456789" to 0123456789.
187    It would then place a file in the \path{/var/spool/asterisk/outgoing}
188    directory to initiate a call to 17094009 (the default message centre
189    in smsq) attached to application SMS with argument of the queue name
190    (0).
191
192    Normally smsq will queue a message ready to send, and will then create
193    a file in the Asterisk outgoing directory causing Asterisk to actually
194    connect to the message centre or device and actually send the pending
195    message(s).
196
197    Using \verb!--process!, smsq can however be used on received queues to run a
198    command for each file (matching the queue if specified) with various
199    environment variables set based on the message (see below);
200    smsq options:
201 \begin{verbatim}
202    --help
203    Show help text
204    --usage
205    Show usage
206    --queue
207    -q
208    Specify a specific queue
209    In no specified, messages are queued under queue "0"
210    --da
211    -d
212    Specify destination address
213    --oa
214    -o
215    Specify originating address
216    This also implies that we are generating a mobile terminated message
217    --ud
218    -m
219    Specify the actual message
220    --ud-file
221    -f
222    Specify a file to be read for the context of the message
223    A blank filename (e.g. --ud-file= on its own) means read stdin. Very
224    useful when using via ssh where command line parsing could mess up the
225    message.
226    --mt
227    -t
228    Mobile terminated message to be generated
229    --mo
230    Mobile originated message to be generated
231    Default
232    --tx
233    Transmit message
234    Default
235    --rx
236    -r
237    Generate a message in the receive queue
238    --UTF-8
239    Treat the file as UTF-8 encoded (default)
240    --UCS-1
241    Treat the file as raw 8 bit UCS-1 data, not UTF-8 encoded
242    --UCS-2
243    Treat the file as raw 16 bit bigendian USC-2 data
244    --process
245    Specific a command to process for each file in the queue
246    Implies --rx and --mt if not otherwise specified.
247    Sets environment variables for every possible variable, and also ud,
248    ud8 (USC-1 hex), and ud16 (USC-2 hex) for each call. Removes files.
249    --motx-channel
250    Specify the channel for motx calls
251    May contain X to use sub address based on queue name or may be full
252    number
253    Default is Local/1709400X
254    --motx-callerid
255    Specify the caller ID for motx calls
256    The default is the queue name without -X suffix
257    --motx-wait
258    Wait time for motx call
259    Default 10
260    --motx-delay
261    Retry time for motx call
262    Default 1
263    --motx-retries
264    Retries for motx call
265    Default 10
266    --mttx-channel
267    Specify the channel for mttx calls
268    Default is Local/ and the queue name without -X suffix
269    --mtttx-callerid
270    Specify the callerid for mttx calls
271    May include X to use sub address based on queue name or may be full
272    number
273    Default is 080058752X0
274    --mttx-wait
275    Wait time for mttx call
276    Default 10
277    --mttx-delay
278    Retry time for mttx call
279    Default 30
280    --mttx-retries
281    Retries for mttx call
282    Default 100
283    --default-sub-address
284    The default sub address assumed (e.g. for X in CLI and dialled numbers
285    as above) when none added (-X) to queue
286    Default 9
287    --no-dial
288    -x
289    Create queue, but do not dial to send message
290    --no-wait
291    Do not wait if a call appears to be in progress
292    This could have a small window where a message is queued but not
293    sent, so regular calls to smsq should be done to pick up any missed
294    messages
295    --concurrent
296    How many concurrent calls to allow (per queue), default 1
297    --mr
298    -n
299    Message reference
300    --pid
301    -p
302    Protocol ID
303    --dcs
304    Data coding scheme
305    --udh
306    Specific hex string of user data header specified (not including the
307    initial length byte)
308    May be a blank string to indicate header is included in the user data
309    already but user data header indication to be set.
310    --srr
311    Status report requested
312    --rp
313    Return path requested
314    --vp
315    Specify validity period (seconds)
316    --scts
317    Specify timestamp (YYYY-MM-DDTHH:MM:SS)
318    --spool-dir
319    Spool dir (in which sms and outgoing are found)
320    Default /var/spool/asterisk
321 \end{verbatim}
322
323    Other arguments starting '-' or '\verb!--!' are invalid and will cause an
324    error. Any trailing arguments are processed as follows:-
325
326 \begin{itemize}
327
328      \item If the message is mobile originating and no destination address
329        has been specified, then the first argument is assumed to be a
330        destination address
331
332      \item If the message is mobile terminating and no destination address
333        has been specified, then the first argument is assumed to be the
334        queue name
335
336      \item If there is no user data, or user data file specified, then any
337        following arguments are assumed to be the message, which are
338        concatenated.
339
340      \item If no user data is specified, then no message is sent. However,
341        unless \verb!--no-dial! is specified, smsq checks for pending messages
342        and generates an outgoing anyway
343 \end{itemize}
344
345
346    Note that when smsq attempts to make a file in
347    \path{/var/spool/asterisk/outgoing}, it checks if there is already a call
348    queued for that queue. It will try several filenames, up to the
349    \verb!--concurrent! setting. If these files exist, then this means Asterisk
350    is already queued to send all messages for that queue, and so Asterisk
351    should pick up the message just queued. However, this alone could
352    create a race condition, so if the files exist then smsq will wait up
353    to 3 seconds to confirm it still exists or if the queued messages have
354    been sent already. The \verb!--no-wait! turns off this behaviour. Basically,
355    this means that if you have a lot of messages to send all at once,
356    Asterisk will not make unlimited concurrent calls to the same message
357    centre or device for the same queue. This is because it is generally
358    more efficient to make one call and send all of the messages one after
359    the other.
360
361    smsq can be used with no arguments, or with a queue name only, and it
362    will check for any pending messages and cause an outgoing if there are
363    any. It only sets up one outgoing call at a time based on the first
364    queued message it finds. A outgoing call will normally send all queued
365    messages for that queue. One way to use smsq would be to run with no
366    queue name (so any queue) every minute or every few seconds to send
367    pending message. This is not normally necessary unless \verb!--no-dial! is
368    selected. Note that smsq does only check motx or mttx depending on the
369    options selected, so it would need to be called twice as a general
370    check.
371
372    UTF-8 is used to parse command line arguments for user data, and is
373    the default when reading a file. If an invalid UTF-8 sequence is
374    found, it is treated as UCS-1 data (i.e, as is).
375    The \verb!--process! option causes smsq to scan the specified queue (default
376    is mtrx) for messages (matching the queue specified, or any if queue
377    not specified) and run a command and delete the file. The command is
378    run with a number of environment variables set as follows. Note that
379    these are unset if not needed and not just taken from the calling
380    environment. This allows simple processing of incoming messages
381 \begin{verbatim}
382    $queue
383    Set if a queue specified
384    $?srr
385    srr is set (to blank) if srr defined and has value 1.
386    $?rp
387    rp is set (to blank) if rp defined and has value 1.
388    $ud
389    User data, UTF-8 encoding, including any control characters, but with
390    nulls stripped out
391    Useful for the content of emails, for example, as it includes any
392    newlines, etc.
393    $ude
394    User data, escaped UTF-8, including all characters, but control
395    characters \n, \r, \t, \f, \xxx and \ is escaped as \\
396    Useful guaranteed one line printable text, so useful in Subject lines
397    of emails, etc
398    $ud8
399    Hex UCS-1 coding of user data (2 hex digits per character)
400    Present only if all user data is in range U+0000 to U+00FF
401    $ud16
402    Hex UCS-2 coding of user data (4 hex digits per character)
403    other
404    Other fields set using their field name, e.g. mr, pid, dcs, etc. udh
405    is a hex byte string
406 \end{verbatim}
407
408 \section{File formats}
409
410    By default all queues are held in a director \path{/var/spool/asterisk/sms}.
411    Within this directory are sub directories mtrx, mttx, morx, motx which
412    hold the received messages and the messages ready to send. Also,
413    \path{/var/log/asterisk/sms} is a log file of all messages handled.
414
415    The file name in each queue directory starts with the queue parameter
416    to SMS which is normally the CLI used for an outgoing message or the
417    called number on an incoming message, and may have -X (X being sub
418    address) appended. If no queue ID is known, then 0 is used by smsq by
419    default. After this is a dot, and then any text. Files are scanned for
420    matching queue ID and a dot at the start. This means temporary files
421    being created can be given a different name not starting with a queue
422    (we recommend a . on the start of the file name for temp files).
423    Files in these queues are in the form of a simple text file where each
424    line starts with a keyword and an = and then data. udh and ud have
425    options for hex encoding, see below.
426
427    UTF-8. The user data (ud) field is treated as being UTF-8 encoded
428    unless the DCS is specified indicating 8 bit format. If 8 bit format
429    is specified then the user data is sent as is.
430    The keywords are as follows:
431 \begin{verbatim}
432    oa Originating address
433    The phone number from which the message came
434    Present on mobile terminated messages and is the CLI for morx messages
435    da
436    Destination Address
437    The phone number to which the message is sent
438    Present on mobile originated messages
439    scts
440    The service centre time stamp
441    Format YYYY-MM-DDTHH:MM:SS
442    Present on mobile terminated messages
443    pid
444    One byte decimal protocol ID
445    See GSM specs for more details
446    Normally 0 or absent
447    dcs
448    One byte decimal data coding scheme
449    If omitted, a sensible default is used (see below)
450    See GSM specs for more details
451    mr
452    One byte decimal message reference
453    Present on mobile originated messages, added by default if absent
454    srr
455    0 or 1 for status report request
456    Does not work in UK yet, not implemented in app_sms yet
457    rp
458    0 or 1 return path
459    See GSM specs for details
460    vp
461    Validity period in seconds
462    Does not work in UK yet
463    udh
464    Hex string of user data header prepended to the SMS contents,
465    excluding initial length byte.
466    Consistent with ud, this is specified as udh# rather than udh=
467    If blank, this means that the udhi flag will be set but any user data
468    header must be in the ud field
469    ud
470    User data, may be text, or hex, see below
471 \end{verbatim}
472
473    udh is specified as as udh\# followed by hex (2 hex digits per byte).
474    If present, then the user data header indicator bit is set, and the
475    length plus the user data header is added to the start of the user
476    data, with padding if necessary (to septet boundary in 7 bit format).
477    User data can hold an USC character codes U+0000 to U+FFFF. Any other
478    characters are coded as U+FEFF
479
480    ud can be specified as ud= followed by UTF-8 encoded text if it
481    contains no control characters, i.e. only (U+0020 to U+FFFF). Any
482    invalid UTF-8 sequences are treated as is (U+0080-U+00FF).
483
484    ud can also be specified as ud\# followed by hex (2 hex digits per
485    byte) containing characters U+0000 to U+00FF only.
486
487    ud can also be specified as ud\#\# followed by hex (4 hex digits per
488    byte) containing UCS-2 characters.
489
490    When written by app\_sms (e.g. incoming messages), the file is written
491    with ud= if it can be (no control characters). If it cannot, the a
492    comment line ;ud= is used to show the user data for human readability
493    and ud\# or ud\#\# is used.
494
495 \section{Delivery reports}
496
497    The SMS specification allows for delivery reports. These are requested
498    using the srr bit. However, as these do not work in the UK yet they
499    are not fully implemented in this application. If anyone has a telco
500    that does implement these, please let me know. BT in the UK have a non
501    standard way to do this by starting the message with *0\#, and so this
502    application may have a UK specific bodge in the near future to handle
503    these.
504
505    The main changes that are proposed for delivery report handling are :
506
507 \begin{itemize}
508      \item New queues for sent messages, one file for each destination
509        address and message reference.
510
511      \item New field in message format, user reference, allowing applications
512        to tie up their original message with a report.
513
514      \item Handling of the delivery confirmation/rejection and connecting to
515        the outgoing message - the received message file would then have
516        fields for the original outgoing message and user reference
517        allowing applications to handle confirmations better.
518 \end{itemize}