Merge anthm's monitor fixes (better default path, set variable for monitor) (bug...
[asterisk/asterisk.git] / doc / app_sms.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2 <html>
3 <head>
4 </head>
5 <body>
6 <h1>* Application SMS</h1>
7 The SMS module for asterisk was developed by Adrian Kennard, and is an
8 implementation of the ETSI specification for landline SMS, ETSI ES 201
9 912, which is available from Landline SMS is starting to
10 be available in various parts of Europe, and is available from BT in
11 the UK. However, asterisk would allow gateways to be created in other
12 locations such as the US, and use of SMS capable phones such as the
13 Magic Messenger. SMS works using analogue or ISDN lines.<br>
14 <h2>Background</h2>
15 Short Message Service (SMS), or <span style="font-style: italic;">texting</span>
16 is very popular between mobile phones. A message can be sent between
17 two phones, and normally contains 160 characters. There are ways in
18 which various types of data can be encoded in a text message such as
19 ring tones, and small graphic, etc. Text messaging is being used for
20 voting and competitions, and also SPAM...<br>
21 <br>
22 Sending a message involves the mobile phone contacting a message centre
23 (SMSC) and passing the message to it. The message centre then contacts
24 the destination mobile to deliver the message. The SMSC is responsible
25 for storing the message and trying to send it until the destination
26 mobile is available, or a timeout.<br>
27 <br>
28 Landline SMS works in basically the same way. You would normally have a
29 suitable text capable landline phone, or a separate texting box such as
30 a Magic Messenger on your phone line. This sends a message to a message
31 centre your telco provides by making a normal call and sending the data
32 using 1200 Baud FSK signaling according to the ETSI spec. To receive a
33 message the message centre calls the line with a specific calling
34 number, and the text capable phone answers the call and receives the
35 data using 1200 Baud FSK signaling. This works particularly well in the
36 UK as the calling line identity is sent before the first ring, so no
37 phones in the house would ring when a message arrives.<br>
38 <h2>Typical use with asterisk</h2>
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.<br>
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.<br>
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 memory).<br>
50 <h2>Terminology</h2>
51 <table style="text-align: left;" border="1" cellpadding="2"
52  cellspacing="2">
53   <tbody>
54     <tr>
55       <td style="vertical-align: top;">SMS<br>
56       </td>
57       <td style="vertical-align: top;">Short Message Service<br>
58       </td>
59       <td style="vertical-align: top;">i.e. text messages<br>
60       </td>
61     </tr>
62     <tr>
63       <td style="vertical-align: top;">SMSC<br>
64       </td>
65       <td style="vertical-align: top;">Short Message Service Centre<br>
66       </td>
67       <td style="vertical-align: top;">The system responsible for
68 storing and forwarding messages<br>
69       </td>
70     </tr>
71     <tr>
72       <td style="vertical-align: top;">MO<br>
73       </td>
74       <td style="vertical-align: top;">Mobile Originated<br>
75       </td>
76       <td style="vertical-align: top;">A message on its way from a
77 mobile or landline device to the SMSC<br>
78       </td>
79     </tr>
80     <tr>
81       <td style="vertical-align: top;">MT<br>
82       </td>
83       <td style="vertical-align: top;">Mobile Terminated<br>
84       </td>
85       <td style="vertical-align: top;">A message on its way from the
86 SMSC to the mobile or landline device<br>
87       </td>
88     </tr>
89     <tr>
90       <td style="vertical-align: top;">RX<br>
91       </td>
92       <td style="vertical-align: top;">Receive<br>
93       </td>
94       <td style="vertical-align: top;">A message coming in to the
95 asterisk box<br>
96       </td>
97     </tr>
98     <tr>
99       <td style="vertical-align: top;">TX<br>
100       </td>
101       <td style="vertical-align: top;">Transmit<br>
102       </td>
103       <td style="vertical-align: top;">A message going out of the
104 asterisk box<br>
105       </td>
106     </tr>
107   </tbody>
108 </table>
109 <h2>Sub address</h2>
110 When sending a message to a landline, you simply send to the landline
111 number. In the UK, all of the mobile operators (bar one) understand
112 sending messages to landlines and pass the messages to the BTText
113 system for delivery to the landline.<br>
114 <br>
115 The specification for landline SMS allows for the possibility of more
116 than one device on a single landline. These can be configured with <span
117  style="font-style: italic;">Sub addresses</span> which are a single
118 digit. To send a message to a specific device the message is sent to
119 the landline number with an extra digit appended to the end. The telco
120 can define a default sub address (9 in the UK) which is used when the
121 extra digit is not appended to the end. When the call comes in, part of
122 the calling line ID is the sub address, so that only one device on the
123 line answers the call and receives the message.<br>
124 <br>
125 Sub addresses also work for outgoing messages. Part of the number
126 called by the device to send a message is its sub address. Sending from
127 the default sub address (9 in the UK) means the message is delivered
128 with the <span style="font-style: italic;">sender </span>being the
129 normal landline number. Sending from any other sub address makes the <span
130  style="font-style: italic;">sender</span> the landline number with an
131 extra digit on the end.<br>
132 <br>
133 Using asterisk, you can make use of the sub addresses for sending and
134 receiving messages. Using DDI (DID, i.e. multiple numbers on the line
135 on ISDN) you can also make use of many different numbers for SMS.<br>
136 <h2>Build / installation</h2>
137 <span style="font-weight: bold;">app_sms.c</span> is included in the
138 latest cvs. It lives in the asterisk source <span
139  style="font-weight: bold;">apps</span> directory and is included in
140 the object list (<span style="font-weight: bold;"></span>) in
141 <span style="font-weight: bold;">apps/Makefile</span>.<br>
142 <span style="font-weight: bold;">smsq.c</span> is a stand alone helper
143 application which is used to send SMSs from the command line. It uses
144 the <span style="font-weight: bold;">popt</span> library. A line for
145 your make file is:-<br>
146 <pre>smsq: smsq.c<br>   cc -O -o smsq smsq.c -lpopt<br></pre>
147 <span style="font-family: monospace;"></span>
148 <h2>extensions.conf</h2>
149 The following contexts are recommended.<br>
150 <pre>; Mobile Terminated, RX. This is used when an incoming call from the SMS arrives, with the queue (called number and sub address) in ${EXTEN}<br>; Running an app after receipt of the text allows the app to find all messages in the queue and handle them, e.g. email them.<br>; The app may be something like   smsq --process=somecommand --queue=${EXTEN}  to run a command for each received message<br>; See below for usage<br>[smsmtrx]<br>exten = _X.,1, SMS(${EXTEN}|a)<br>exten = _X.,2,System("someapptohandleincomingsms ${EXTEN}")<br>exten = _X.,3,Hangup<br><br>; Mobile originated, RX. This is receiving a message from a device, e.g. a Magic Messenger on a sip extension<br>; Running an app after receipt of the text allows the app to find all messages in the queue and handle then, e.g. sending them to the public SMSC<br>; The app may be something like   smsq --process=somecommand --queue=${EXTEN}  to run a command for each received message<br>; See below for example usage<br>[smsmorx]<br>exten = _X.,1, SMS(${EXTEN}|sa)<br>exten = _X.,2,System("someapptohandlelocalsms ${EXTEN}")<br>exten = _X.,3,Hangup<span
151  style="font-family: sans-serif;"></span><span
152  style="font-family: sans-serif;"></span></pre>
153 <span style="font-family: sans-serif;"></span><span
154  style="font-weight: bold;">smsmtrx</span> is normally accessed by an
155 incoming call from the SMSC. In the UK this call is from a CLI of
156 080058752X0 where X is the sub address. As such a typical usage in the
157 extensions.conf at the point of handling an incoming call is:-<br>
158 <pre>exten = _X./8005875290,1,Goto(smsmtrx,${EXTEN},1)<br>exten = _X./_80058752[0-8]0,1,Goto(smsmtrx,${EXTEN}-${CALLERIDNUM:8:1},1)<br></pre>
159 Alternatively, if you have the correct national prefix on incoming CLI,
160 e.g. using zaphfc, you might use:-<br>
161 <pre>exten = _X./08005875290,1,Goto(smsmtrx,${EXTEN},1)<br>exten = _X./_080058752[0-8]0,1,Goto(smsmtrx,${EXTEN}-${CALLERIDNUM:9:1},1)</pre>
162 <span style="font-weight: bold;">smsmorx</span> is normally accessed by
163 a call from a local sip device connected to a Magic Messenger. It could
164 however by that you are operating asterisk as a message centre for
165 calls from outside. Either way, you look at the called number and goto
166 smsmorx. In the UK, the SMSC number that would be dialed is 1709400X
167 where X is the caller sub address. As such typical usage in
168 extension.config at the point of handling a call from a sip phone is:-<br>
169 <pre>exten = 17094009,1,Goto(smsmorx,${CALLERIDNUM},1)<br>exten = _1709400[0-8],1,Goto(smsmorx,${CALLERIDNUM}-{EXTEN:7:1},1)<br></pre>
170 <h2>Using smsq</h2>
171 <span style="font-weight: bold;">smsq</span> is a simple helper
172 application designed to make it easy to send messages from a command
173 line. it is intended to run on the asterisk box and have direct access
174 to the queue directories for SMS and for asterisk.<br>
175 <br>
176 In its simplest form you can send an SMS by a command such as <br>
177 <br>
178 smsq 0123456789 This is a test to 0123456789<br>
179 <br>
180 This would create a queue file for a mobile originated TX message in
181 queue 0 to send the text "This is a test to 0123456789" to 0123456789.
182 It would then place a file in the /var/spool/asterisk/outgoing
183 directory to initiate a call to 17094009 (the default message centre in
184 smsq) attached to application SMS with argument of the queue name (0).<br>
185 <br>
186 Normally smsq will queue a message ready to send, and will then create
187 a file in the asterisk outgoing directory causing asterisk to actually
188 connect to the message centre or device and actually send the pending
189 message(s).<br>
190 <br>
191 Using --process, smsq can however be used on received queues to run a
192 command for each file (matching the queue if specified) with various
193 environment variables set based on the message (see below);<br>
194 <br>
195 smsq options:-<br>
196 <br>
197 <table style="text-align: left;" border="1" cellpadding="2"
198  cellspacing="2">
199   <tbody>
200     <tr>
201       <td style="vertical-align: top;">--help</td>
202       <td style="vertical-align: top;"><br>
203       </td>
204       <td style="vertical-align: top;">Show help text<br>
205       </td>
206     </tr>
207     <tr>
208       <td style="vertical-align: top;">--usage<br>
209       </td>
210       <td style="vertical-align: top;"><br>
211       </td>
212       <td style="vertical-align: top;">Show usage<br>
213       </td>
214     </tr>
215     <tr>
216       <td style="vertical-align: top;">--queue<br>
217       </td>
218       <td style="vertical-align: top;">-q<br>
219       </td>
220       <td style="vertical-align: top;">Specify a specific queue<br>
221 In no specified, messages are queued under queue "0"<br>
222       </td>
223     </tr>
224     <tr>
225       <td style="vertical-align: top;">--da<br>
226       </td>
227       <td style="vertical-align: top;">-d<br>
228       </td>
229       <td style="vertical-align: top;">Specify destination address<br>
230       </td>
231     </tr>
232     <tr>
233       <td style="vertical-align: top;">--oa<br>
234       </td>
235       <td style="vertical-align: top;">-o<br>
236       </td>
237       <td style="vertical-align: top;">Specify originating address<br>
238 This also implies that we are generating a mobile terminated message<br>
239       </td>
240     </tr>
241     <tr>
242       <td style="vertical-align: top;">--ud<br>
243       </td>
244       <td style="vertical-align: top;">-m<br>
245       </td>
246       <td style="vertical-align: top;">Specify the actual message<br>
247       </td>
248     </tr>
249     <tr>
250       <td style="vertical-align: top;">--ud-file<br>
251       </td>
252       <td style="vertical-align: top;">-f<br>
253       </td>
254       <td style="vertical-align: top;">Specify a file to be read for
255 the context of the message<br>
256 A blank filename (e.g. --ud-file= on its own) means read stdin. Very
257 useful when using via ssh where command line parsing could mess up the
258 message.<br>
259       </td>
260     </tr>
261     <tr>
262       <td style="vertical-align: top;">--mt<br>
263       </td>
264       <td style="vertical-align: top;">-t<br>
265       </td>
266       <td style="vertical-align: top;">Mobile terminated message to be
267 generated<br>
268       </td>
269     </tr>
270     <tr>
271       <td style="vertical-align: top;">--mo<br>
272       </td>
273       <td style="vertical-align: top;"><br>
274       </td>
275       <td style="vertical-align: top;">Mobile originated message to be
276 generated<br>
277 Default<br>
278       </td>
279     </tr>
280     <tr>
281       <td style="vertical-align: top;">--tx<br>
282       </td>
283       <td style="vertical-align: top;"><br>
284       </td>
285       <td style="vertical-align: top;">Transmit message<br>
286 Default<br>
287       </td>
288     </tr>
289     <tr>
290       <td style="vertical-align: top;">--rx<br>
291       </td>
292       <td style="vertical-align: top;">-r<br>
293       </td>
294       <td style="vertical-align: top;">Generate a message in the
295 receive queue<br>
296       </td>
297     </tr>
298     <tr>
299       <td style="vertical-align: top;">--UTF-8<br>
300       </td>
301       <td style="vertical-align: top;"><br>
302       </td>
303       <td style="vertical-align: top;">Treat the file as UTF-8 encoded
304 (default) </td>
305     </tr>
306     <tr>
307       <td style="vertical-align: top;">--UCS-1<br>
308       </td>
309       <td style="vertical-align: top;"><br>
310       </td>
311       <td style="vertical-align: top;">Treat the file as raw 8 bit
312 UCS-1 data, not UTF-8 encoded<br>
313       </td>
314     </tr>
315     <tr>
316       <td style="vertical-align: top;">--UCS-2<br>
317       </td>
318       <td style="vertical-align: top;"><br>
319       </td>
320       <td style="vertical-align: top;">Treat the file as raw 16 bit
321 bigendian USC-2 data<br>
322       </td>
323     </tr>
324     <tr>
325       <td style="vertical-align: top;">--process<br>
326       </td>
327       <td style="vertical-align: top;"><br>
328       </td>
329       <td style="vertical-align: top;">Specific a command to process
330 for each file in the queue<br>
331 Implies --rx and --mt if not otherwise specified.<br>
332 Sets environment variables for every possible variable,
333 and also ud, ud8 (USC-1 hex), and ud16 (USC-2 hex) for each call.
334 Removes files.<br>
335       </td>
336     </tr>
337     <tr>
338       <td style="vertical-align: top;">--motx-channel<br>
339       </td>
340       <td style="vertical-align: top;"><br>
341       </td>
342       <td style="vertical-align: top;">Specify the channel for motx
343 calls<br>
344 May contain X to use sub address based on queue name or may be full
345 number<br>
346 Default is Local/1709400X<br>
347       </td>
348     </tr>
349     <tr>
350       <td style="vertical-align: top;">--motx-callerid<br>
351       </td>
352       <td style="vertical-align: top;"><br>
353       </td>
354       <td style="vertical-align: top;">Specify the caller ID for motx
355 calls<br>
356 The default is the queue name without -X suffix<br>
357       </td>
358     </tr>
359     <tr>
360       <td style="vertical-align: top;">--motx-wait<br>
361       </td>
362       <td style="vertical-align: top;"><br>
363       </td>
364       <td style="vertical-align: top;">Wait time for motx call<br>
365 Default 10<br>
366       </td>
367     </tr>
368     <tr>
369       <td style="vertical-align: top;">--motx-delay<br>
370       </td>
371       <td style="vertical-align: top;"><br>
372       </td>
373       <td style="vertical-align: top;">Retry time for motx call<br>
374 Default 1<br>
375       </td>
376     </tr>
377     <tr>
378       <td style="vertical-align: top;">--motx-retries<br>
379       </td>
380       <td style="vertical-align: top;"><br>
381       </td>
382       <td style="vertical-align: top;">Retries for motx call<br>
383 Default 10<br>
384       </td>
385     </tr>
386     <tr>
387       <td style="vertical-align: top;">--mttx-channel<br>
388       </td>
389       <td style="vertical-align: top;"><br>
390       </td>
391       <td style="vertical-align: top;">Specify the channel for mttx
392 calls<br>
393 Default is Local/ and the queue name without -X suffix<br>
394       </td>
395     </tr>
396     <tr>
397       <td style="vertical-align: top;">--mtttx-callerid<br>
398       </td>
399       <td style="vertical-align: top;"><br>
400       </td>
401       <td style="vertical-align: top;">Specify the callerid for mttx
402 calls<br>
403 May include X to use sub address based on queue name or may be full
404 number<br>
405 Default is 080058752X0<br>
406       </td>
407     </tr>
408     <tr>
409       <td style="vertical-align: top;">--mttx-wait<br>
410       </td>
411       <td style="vertical-align: top;"><br>
412       </td>
413       <td style="vertical-align: top;">Wait time for mttx call<br>
414 Default 10<br>
415       </td>
416     </tr>
417     <tr>
418       <td style="vertical-align: top;">--mttx-delay<br>
419       </td>
420       <td style="vertical-align: top;"><br>
421       </td>
422       <td style="vertical-align: top;">Retry time for mttx call<br>
423 Default 30<br>
424       </td>
425     </tr>
426     <tr>
427       <td style="vertical-align: top;">--mttx-retries<br>
428       </td>
429       <td style="vertical-align: top;"><br>
430       </td>
431       <td style="vertical-align: top;">Retries for mttx call<br>
432 Default 100<br>
433       </td>
434     </tr>
435     <tr>
436       <td style="vertical-align: top;">--default-sub-address<br>
437       </td>
438       <td style="vertical-align: top;"><br>
439       </td>
440       <td style="vertical-align: top;">The default sub address assumed
441 (e.g. for X in CLI and dialled numbers as above) when none added (-X)
442 to queue<br>
443 Default 9<br>
444       </td>
445     </tr>
446     <tr>
447       <td style="vertical-align: top;">--no-dial<br>
448       </td>
449       <td style="vertical-align: top;">-x<br>
450       </td>
451       <td style="vertical-align: top;">Create queue, but do not dial to
452 send message<br>
453       </td>
454     </tr>
455     <tr>
456       <td style="vertical-align: top;">--no-wait<br>
457       </td>
458       <td style="vertical-align: top;"><br>
459       </td>
460       <td style="vertical-align: top;">Do not wait if a call appears to
461 be in progress<br>
462 This could have a small window where a mesdsage is queued but not sent,
463 so regular calls to smsq should be done to pick up any missed messages<br>
464       </td>
465     </tr>
466     <tr>
467       <td style="vertical-align: top;">--concurrent<br>
468       </td>
469       <td style="vertical-align: top;"><br>
470       </td>
471       <td style="vertical-align: top;">How many concurrent calls to
472 allow (per queue), default 1<br>
473       </td>
474     </tr>
475     <tr>
476       <td style="vertical-align: top;">--mr<br>
477       </td>
478       <td style="vertical-align: top;">-n<br>
479       </td>
480       <td style="vertical-align: top;">Message reference<br>
481       </td>
482     </tr>
483     <tr>
484       <td style="vertical-align: top;">--pid<br>
485       </td>
486       <td style="vertical-align: top;">-p<br>
487       </td>
488       <td style="vertical-align: top;">Protocol ID<br>
489       </td>
490     </tr>
491     <tr>
492       <td style="vertical-align: top;">--dcs<br>
493       </td>
494       <td style="vertical-align: top;"><br>
495       </td>
496       <td style="vertical-align: top;">Data coding scheme<br>
497       </td>
498     </tr>
499     <tr>
500       <td style="vertical-align: top;">--udh<br>
501       </td>
502       <td style="vertical-align: top;"><br>
503       </td>
504       <td style="vertical-align: top;">Specific hex string of user data
505 header specified (not including the initial length byte)<br>
506 May be a blank string to indicate header is included in the user data
507 already but user data header indication to be set.<br>
508       </td>
509     </tr>
510     <tr>
511       <td style="vertical-align: top;">--srr<br>
512       </td>
513       <td style="vertical-align: top;"><br>
514       </td>
515       <td style="vertical-align: top;">Status report requested<br>
516       </td>
517     </tr>
518     <tr>
519       <td style="vertical-align: top;">--rp<br>
520       </td>
521       <td style="vertical-align: top;"><br>
522       </td>
523       <td style="vertical-align: top;">Return path requested<br>
524       </td>
525     </tr>
526     <tr>
527       <td style="vertical-align: top;">--vp<br>
528       </td>
529       <td style="vertical-align: top;"><br>
530       </td>
531       <td style="vertical-align: top;">Specify validity period (seconds)<br>
532       </td>
533     </tr>
534     <tr>
535       <td style="vertical-align: top;">--scts<br>
536       </td>
537       <td style="vertical-align: top;"><br>
538       </td>
539       <td style="vertical-align: top;">Specify timestamp
541       </td>
542     </tr>
543     <tr>
544       <td style="vertical-align: top;">--spool-dir<br>
545       </td>
546       <td style="vertical-align: top;"><br>
547       </td>
548       <td style="vertical-align: top;">Spool dir (in which sms and
549 outgoing are found)<br>
550 Default /var/spool/asterisk<br>
551       </td>
552     </tr>
553   </tbody>
554 </table>
555 <p>Other arguments starting '-' or '--' are invalid and will cause an
556 error. Any trailing arguments are processed as follows:-<br>
557 </p>
558 <ul>
559   <li>If the message is mobile originating and no destination address
560 has been specified, then the first argument is assumed to be a
561 destination address</li>
562   <li>If the message is mobile terminating and no destination address
563 has been specified, then the first argument is assumed to be the queue
564 name</li>
565   <li>If there is no user data, or user data file specified, then any
566 following arguments are assumed to be the message, which are
567 concatenated.</li>
568   <li>If no user data is specified, then no message is sent. However,
569 unless --no-dial is specified, smsq checks for pending messages and
570 generates an outgoing anyway</li>
571 </ul>
572 Note that when smsq attempts to make a file in
573 /var/spool/asterisk/outgoing, it checks if there is already a call
574 queued for that queue. It will try several filenames, up to the
575 --concorrent setting. If these files
576 exists, then this means asterisk is already queued to send all messages
577 for that queue, and so asterisk should pick up the message just queued.
578 However, this alone could create a race condition, so if the files
579 exist then smsq will wait up to 3 seconds to confirm it still exists or
580 if the queued messages have been sent already.
581 The --no-wait turns off this behaviour. Basically, this means that if
582 you have a lot of messages to send all at
583 once, asterisk will not make unlimited concurrent calls to the same
584 message centre or device for the same queue. This is because it is
585 generally more efficient to make one call and send all of the messages
586 one after the other.<br>
587 <br>
588 smsq can be used with no arguments, or with a queue name only, and it
589 will check for any pending messages and cause an outgoing if there are
590 any. It only sets up one outgoing call at a time based on the first
591 queued message it finds. A outgoing call will normally send all queued
592 messages for that queue. One way to use smsq would be to run with no
593 queue name (so any queue) every minute or every few seconds to send
594 pending message. This is not normally necessary unless --no-dial is
595 selected. Note that smsq does only check motx or mttx depending on the
596 options selected, so it would need to be called twice as a general
597 check.<br>
598 <br>
599 UTF-8 is used to parse command line arguments for user data, and is the
600 default when reading a file. If an invalid UTF-8 sequence is found, it
601 is treated as UCS-1 data (i.e, as is).<br>
602 <br>
603 The --process option causes smsq to scan the specified queue (default
604 is mtrx) for messages (matching the queue specified, or any if queue
605 not specified) and run a command and delete the file. The command is
606 run with a number of environment variables set as follows. Note that
607 these are unset if not needed and not just taken from the calling
608 environment. This allows simple processing of incoming messages<br>
609 <br>
610 <table style="text-align: left;" border="1" cellpadding="2"
611  cellspacing="2">
612   <tbody>
613     <tr>
614       <td style="vertical-align: top;">$queue<br>
615       </td>
616       <td style="vertical-align: top;">Set if a queue specified<br>
617       </td>
618     </tr>
619     <tr>
620       <td style="vertical-align: top;">$?srr<br>
621       </td>
622       <td style="vertical-align: top;">srr is set (to blank) if srr
623 defined and has value 1.<br>
624       </td>
625     </tr>
626     <tr>
627       <td style="vertical-align: top;">$?rp<br>
628       </td>
629       <td style="vertical-align: top;">rp is set (to blank) if rp
630 defined and has value 1.<br>
631       </td>
632     </tr>
633     <tr>
634       <td style="vertical-align: top;">$ud<br>
635       </td>
636       <td style="vertical-align: top;">User data, UTF-8 encoding,
637 including any control characters, but with nulls stripped out<br>
638 Useful for the content of emails, for example, as it includes any
639 newlines, etc.<br>
640       </td>
641     </tr>
642     <tr>
643       <td style="vertical-align: top;">$ude<br>
644       </td>
645       <td style="vertical-align: top;">User data, escaped UTF-8,
646 including all characters, but control characters \n, \r, \t, \f, \xxx
647 and \ is escaped as \\<br>
648 Useful fGuaranteed one line printable text, so useful in Subject lines
649 of emails, etc<br>
650       </td>
651     </tr>
652     <tr>
653       <td style="vertical-align: top;">$ud8<br>
654       </td>
655       <td style="vertical-align: top;">Hex UCS-1 coding of user data (2
656 hex digits per character)<br>
657 Present only if all user data is in range U+0000 to U+00FF<br>
658       </td>
659     </tr>
660     <tr>
661       <td style="vertical-align: top;">$ud16<br>
662       </td>
663       <td style="vertical-align: top;">Hex UCS-2 coding of user data (4
664 hex digits per chartacter)<br>
665       </td>
666     </tr>
667     <tr>
668       <td style="vertical-align: top;"><span style="font-style: italic;">other</span><br>
669       </td>
670       <td style="vertical-align: top;">Other fields set using their
671 field name, e.g. mr, pid, dcs, etc. udh is a hex byte string<br>
672       </td>
673     </tr>
674   </tbody>
675 </table>
676 <h2>File formats</h2>
677 By default all queues are held in a director /var/spool/asterisk/sms.
678 Within this directory are sub directories mtrx, mttx, morx, motx which
679 hold the received messages and the messages ready to send. Also,
680 /var/log/asterisk/sms is a log file of all messages handled.<br>
681 <br>
682 The file name in each queue directory starts with the queue parameter
683 to SMS which is normally the CLI used for an outgoing message or the
684 called number on an incoming message, and may have -X (X being sub
685 address) appended. If no queue ID is known, then 0 is used by smsq by
686 default. After this is a dot, and then any text. Files are scanned for
687 matching queue ID and a dot at the start. This means temporary files
688 being created can be given a different name not starting with a queue
689 (we recommend a . on the start of the file name for temp files).<br>
690 <br>
691 Files in these queues are in the form of a simple text file where each
692 line starts with a keyword and an = and then data. udh and ud have
693 options for hex encoding, see below.<br>
694 <br>
695 UTF-8. The user data (ud) field is treated as being UTF-8 encoded
696 unless the DCS is specified indicating 8 bit formart. If 8 bit format
697 is specified then the user data is sent as is.<br>
698 <br>
699 The keywords are as
700 follows:-<br>
701 <table style="text-align: left;" border="1" cellpadding="2"
702  cellspacing="2">
703   <tbody>
704     <tr>
705       <td style="vertical-align: top;">oa</td>
706       <td style="vertical-align: top;">Originating address<br>
707 The phone number from which the message came<br>
708 Present on mobile terminated messages and is the CLI for morx messages<br>
709       </td>
710     </tr>
711     <tr>
712       <td style="vertical-align: top;">da<br>
713       </td>
714       <td style="vertical-align: top;">Destination Address<br>
715 The phone number to which the message is sent<br>
716 Present on mobile originated messages<br>
717       </td>
718     </tr>
719     <tr>
720       <td style="vertical-align: top;">scts<br>
721       </td>
722       <td style="vertical-align: top;">The service centre time stamp<br>
723 Format YYYY-MM-DDTHH:MM:SS<br>
724 Present on mobile terminated messages<br>
725       </td>
726     </tr>
727     <tr>
728       <td style="vertical-align: top;">pid<br>
729       </td>
730       <td style="vertical-align: top;">One byte decimal protocol ID<br>
731 See GSM specs for more details<br>
732 Normally 0 or absent<br>
733       </td>
734     </tr>
735     <tr>
736       <td style="vertical-align: top;">dcs<br>
737       </td>
738       <td style="vertical-align: top;">One byte decimal data coding
739 scheme<br>
740 If omitted, a sensible default is used (see below)<br>
741 See GSM specs for more details<br>
742       </td>
743     </tr>
744     <tr>
745       <td style="vertical-align: top;">mr<br>
746       </td>
747       <td style="vertical-align: top;">One byte decimal message
748 reference<br>
749 Present on mobile originated messages, added by default if absent<br>
750       </td>
751     </tr>
752     <tr>
753       <td style="vertical-align: top;">srr<br>
754       </td>
755       <td style="vertical-align: top;">0 or 1 for status report request<br>
756 Does not work in UK yet, not implemented in app_sms yet<br>
757       </td>
758     </tr>
759     <tr>
760       <td style="vertical-align: top;">rp<br>
761       </td>
762       <td style="vertical-align: top;">0 or 1 return path<br>
763 See GSM specs for details<br>
764       </td>
765     </tr>
766     <tr>
767       <td style="vertical-align: top;">vp<br>
768       </td>
769       <td style="vertical-align: top;">Validity period in seconds<br>
770 Does not work in UK yet<br>
771       </td>
772     </tr>
773     <tr>
774       <td style="vertical-align: top;">udh<br>
775       </td>
776       <td style="vertical-align: top;">Hex string of user data header
777 prepended to the SMS contents, excluding initial length byte.<br>
778 Consistent with ud, this is specified as udh# rather than udh=<br>
779 If blank, this means that the udhi flag will be set but any user data
780 header must be in the ud field<br>
781       </td>
782     </tr>
783     <tr>
784       <td style="vertical-align: top;">ud<br>
785       </td>
786       <td style="vertical-align: top;">User data, may be text, or hex,
787 see below<br>
788       </td>
789     </tr>
790   </tbody>
791 </table>
792 <br>
793 udh is specified as as udh# followed by hex (2 hex digits per byte). If
794 present, then the user data header indicator bit is set, and the length
795 plus the user data header is added to the start of the user data, with
796 padding if necessary (to septet boundary in 7 bit format).<br>
797 <br>
798 User data can hold an USC character codes U+0000 to U+FFFF. Any other
799 characters are coded as U+FEFF<br>
800 ud can be specified as ud= followed by UTF-8 encoded text if it
801 contains no control characters, i.e. only (U+0020 to U+FFFF). Any
802 invalid UTF-8 sequences are treated as is (U+0080-U+00FF).<br>
803 ud can also be specified as ud# followed by hex (2 hex digits per byte)
804 containing characters U+0000 to U+00FF only.<br>
805 ud can also be specified as ud## followed by hex (4 hex digits per
806 byte) containing UCS-2 characters.<br>
807 When written by app_sms (e.g. incoming messages), the file is written
808 with ud= if it can be (no control characters). If it cannot, the a
809 comment line ;ud= is used to show the user data for human readability
810 and ud# or ud## is used.<br>
811 <h2>Delivery reports</h2>
812 The SMS specification allows for delivery reports. These are requested
813 using the srr bit. However, as these do not work in the UK yet they are
814 not fully implemented in this application. If anyone has a telco that
815 does implement these, please let me know. BT in the UK have a non
816 standard way to do this by starting the message with *0#, and so this
817 application may have a UK specific bodge in the near future to handle
818 these.<br>
819 <br>
820 The main changes that are proposed for delivery report handling are :-<br>
821 <ul>
822   <li>New queues for sent messages, one file for each destination
823 address and message reference.</li>
824   <li>New field in message format, user reference, allowing
825 applications to tie up their original message with a report.</li>
826   <li>Handling of the delivery confirmation/rejection and connecting to
827 the outgoing message - the received message file would then have fields
828 for the original outgoing message and user reference allowing
829 applications to handle confirmations better.<br>
830   </li>
831 </ul>
832 <br>
833 </body>
834 </html>