Importing rev 7939 from 1.2
[asterisk/asterisk.git] / doc / README.app_sms
1
2                                * Application SMS
3
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.
11
12 Background
13
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
35    message arrives.
36
37 Typical use with Asterisk
38
39    Sending messages from an Asterisk box can be used for a variety of
40    reasons, including notification from any monitoring systems, email
41    subject lines, etc.
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
50    memory).
51
52 Terminology
53
54    SMS
55    Short Message Service
56    i.e. text messages
57    SMSC
58    Short Message Service Centre
59    The system responsible for storing and forwarding messages
60    MO
61    Mobile Originated
62    A message on its way from a mobile or landline device to the SMSC
63    MT
64    Mobile Terminated
65    A message on its way from the SMSC to the mobile or landline device
66    RX
67    Receive
68    A message coming in to the Asterisk box
69    TX
70    Transmit
71    A message going out of the Asterisk box
72
73 Sub address
74
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
87    receives the message.
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.
97
98 Build / installation
99
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
104    file is:-
105 smsq: smsq.c
106         cc -O -o smsq smsq.c -lpopt
107
108 extensions.conf
109
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
118 [smsmtrx]
119 exten = _X.,1, SMS(${EXTEN}|a)
120 exten = _X.,2,System("someapptohandleincomingsms ${EXTEN}")
121 exten = _X.,3,Hangup
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
129 [smsmorx]
130 exten = _X.,1, SMS(${EXTEN}|sa)
131 exten = _X.,2,System("someapptohandlelocalsms ${EXTEN}")
132 exten = _X.,3,Hangup
133
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)
140
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)
145
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)
155
156 Using smsq
157
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
161    Asterisk.
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
169    (0).
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
173    message(s).
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);
177    smsq options:-
178
179    --help
180    Show help text
181    --usage
182    Show usage
183    --queue
184    -q
185    Specify a specific queue
186    In no specified, messages are queued under queue "0"
187    --da
188    -d
189    Specify destination address
190    --oa
191    -o
192    Specify originating address
193    This also implies that we are generating a mobile terminated message
194    --ud
195    -m
196    Specify the actual message
197    --ud-file
198    -f
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
202    message.
203    --mt
204    -t
205    Mobile terminated message to be generated
206    --mo
207    Mobile originated message to be generated
208    Default
209    --tx
210    Transmit message
211    Default
212    --rx
213    -r
214    Generate a message in the receive queue
215    --UTF-8
216    Treat the file as UTF-8 encoded (default)
217    --UCS-1
218    Treat the file as raw 8 bit UCS-1 data, not UTF-8 encoded
219    --UCS-2
220    Treat the file as raw 16 bit bigendian USC-2 data
221    --process
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.
226    --motx-channel
227    Specify the channel for motx calls
228    May contain X to use sub address based on queue name or may be full
229    number
230    Default is Local/1709400X
231    --motx-callerid
232    Specify the caller ID for motx calls
233    The default is the queue name without -X suffix
234    --motx-wait
235    Wait time for motx call
236    Default 10
237    --motx-delay
238    Retry time for motx call
239    Default 1
240    --motx-retries
241    Retries for motx call
242    Default 10
243    --mttx-channel
244    Specify the channel for mttx calls
245    Default is Local/ and the queue name without -X suffix
246    --mtttx-callerid
247    Specify the callerid for mttx calls
248    May include X to use sub address based on queue name or may be full
249    number
250    Default is 080058752X0
251    --mttx-wait
252    Wait time for mttx call
253    Default 10
254    --mttx-delay
255    Retry time for mttx call
256    Default 30
257    --mttx-retries
258    Retries for mttx call
259    Default 100
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
263    Default 9
264    --no-dial
265    -x
266    Create queue, but do not dial to send message
267    --no-wait
268    Do not wait if a call appears to be in progress
269    This could have a small window where a mesdsage is queued but not
270    sent, so regular calls to smsq should be done to pick up any missed
271    messages
272    --concurrent
273    How many concurrent calls to allow (per queue), default 1
274    --mr
275    -n
276    Message reference
277    --pid
278    -p
279    Protocol ID
280    --dcs
281    Data coding scheme
282    --udh
283    Specific hex string of user data header specified (not including the
284    initial length byte)
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.
287    --srr
288    Status report requested
289    --rp
290    Return path requested
291    --vp
292    Specify validity period (seconds)
293    --scts
294    Specify timestamp (YYYY-MM-DDTHH:MM:SS)
295    --spool-dir
296    Spool dir (in which sms and outgoing are found)
297    Default /var/spool/asterisk
298
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
303        destination address
304      * If the message is mobile terminating and no destination address
305        has been specified, then the first argument is assumed to be the
306        queue name
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
309        concatenated.
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
313
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    --concorrent setting. If these files exists, 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
327    the other.
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
337    check.
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
347
348    $queue
349    Set if a queue specified
350    $?srr
351    srr is set (to blank) if srr defined and has value 1.
352    $?rp
353    rp is set (to blank) if rp defined and has value 1.
354    $ud
355    User data, UTF-8 encoding, including any control characters, but with
356    nulls stripped out
357    Useful for the content of emails, for example, as it includes any
358    newlines, etc.
359    $ude
360    User data, escaped UTF-8, including all characters, but control
361    characters \n, \r, \t, \f, \xxx and \ is escaped as \\
362    Useful fGuaranteed one line printable text, so useful in Subject lines
363    of emails, etc
364    $ud8
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
367    $ud16
368    Hex UCS-2 coding of user data (4 hex digits per chartacter)
369    other
370    Other fields set using their field name, e.g. mr, pid, dcs, etc. udh
371    is a hex byte string
372
373 File formats
374
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 formart. If 8 bit format
392    is specified then the user data is sent as is.
393    The keywords are as follows:-
394
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
398    da
399    Destination Address
400    The phone number to which the message is sent
401    Present on mobile originated messages
402    scts
403    The service centre time stamp
404    Format YYYY-MM-DDTHH:MM:SS
405    Present on mobile terminated messages
406    pid
407    One byte decimal protocol ID
408    See GSM specs for more details
409    Normally 0 or absent
410    dcs
411    One byte decimal data coding scheme
412    If omitted, a sensible default is used (see below)
413    See GSM specs for more details
414    mr
415    One byte decimal message reference
416    Present on mobile originated messages, added by default if absent
417    srr
418    0 or 1 for status report request
419    Does not work in UK yet, not implemented in app_sms yet
420    rp
421    0 or 1 return path
422    See GSM specs for details
423    vp
424    Validity period in seconds
425    Does not work in UK yet
426    udh
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
432    ud
433    User data, may be text, or hex, see below
434
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.
452
453 Delivery reports
454
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
461    these.
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.