Merge anthm's monitor fixes (better default path, set variable for monitor) (bug...
[asterisk/asterisk.git] / doc / README.sms
1 SMS() is an application to handles calls to/from text message capable phones and message centres using ETSI ES 201 912 protocol 1 FSK messaging over analogue calls.
2
3 Basically it allows sending and receiving of text messages over the PSTN. It is compatible with BT Text service in the UK and works on ISDN and PSTN lines. It is designed to connect to an ISDN or zap interface directly and uses FSK so would probably not work over any sort of compressed link.
4
5 Typical applications include:-
6
7 1. Connection to a message centre to send text messages - probably initiated via the manager interface or "outgoing" directory
8 2. Connection to an POTS line with an SMS capable phone to send messages - probably initiated via the manager interface or "Outgoing" directory
9 3. Acceptance of calls from the message centre (based on CLI) and storage of received messages
10 4. Acceptance of calls from a POTS line with an SMS capable phone and storage of received messages
11
12 First argument is queue name
13
14 Second is options
15
16  a: SMS() is to act as the answering side, and so send the initial FSK frame
17  s: SMS() is to act as a service centre side rather than as terminal equipment
18
19 If a third argument is specified, then SMS does not handle the call at all,
20 but takes the third argument as a destination number to send an SMS to, and
21 the forth argument onward as a message to be queued. All this does is create
22 the file in the me-sc directory. If 's' is set then the number is the source
23 address and the message placed in the sc-me directory.
24
25 All text messages are in /var/spool/asterisk/sms
26 A log is recorded in /var/log/asterisk/sms
27
28 There are two subdirectories called sc-me.<queuename> holding all
29 messages from service centre to phone, and me-sc.<queuename> holding all
30 messages from phone to service centre.
31
32 In each directory are messages in files, one per file, using any filename not
33 starting with a dot.
34
35 When connected as a service centre, SMS(s) will send all messages waiting in
36 the sc-me-<queuename> directory, deleting the files as it goes. Any
37 received in this mode are placed in the me-sc-<queuename> directory.
38
39 When connected as a client, SMS() will send all messages waiting in the
40 me-sc-<queuename> directory, deleting the files as it goes. Any received in
41 this mode are placed in the sc-me-<queuename> directory.
42
43 Message files created by SMS() use a time stamp/reference based filename.
44
45 The format of the sms file is lines that have the form of key=value
46 Keys are :-
47
48 oa      Originating Address
49         Telephone number, national number if just digits
50         Telephone number starting with + then digits for international
51         Ignored on sending messages to service centre (CLI used)
52 da      Destination Address
53         Telephone number, national number if just digits
54         Telephone number starting with + then digits for international
55 scts    Service Centre Time Stamp
56         In the format YYYY-MM-DD HH:MM:SS
57 pid     Protocol Identifier (decimal octet value)
58 dcs     Data coding scheme (decimal octet value)
59 mr      Message reference (decimal octet value)
60 ud      The message (see escaping below)
61 srr     0/1 Status Report Request
62 rp      0/1 Return Path
63 vp      mins validity period
64
65 Omitted fields have default values.
66
67 Note that there is special format for ud, ud# instead of ud= which is followed
68 by raw hex (2 characters per octet). This is used in output where characters
69 other than 10,13,32-126,128-255 are included in the data. In this case a comment (line
70 starting ;) is added showing the printable characters
71
72 When generating files to send to a service centre, only da and ud need be
73 specified. oa is ignored.
74
75 When generating files to send to a phone, only oa and ud need be specified. da is ignored.
76
77 When receing a message as a service centre, only the destination address is
78 sent, so the originating address is set to the callerid.
79
80 EXAMPLES
81
82 The following are examples of use within the UK using BT Text SMS/landline
83 service.
84
85 This is a context to use with a manager script.
86
87 [smsdial]       ; create and send a text message, expects number+message and
88 connect to 17094009
89 exten = _X.,1,SMS(${CALLERIDNUM},,${EXTEN},${CALLERIDNAME})
90 exten = _X.,2,SMS(${CALLERIDNUM})
91 exten = _X.,3,Hangup
92
93 The script sends
94
95 action: originate
96 callerid: message <from>
97 exten: to
98 channel: Local/17094009
99 context: smsdial
100 priority: 1
101
102 You put the message as the name of the caller ID (messy, I know), the
103 originating number and hence queue name as the number of the caller ID and the
104 exten as the number to which the sms is to be sent. The context uses SMS to
105 create the message in the queue and then SMS to communicate iwth 17094009 to
106 actually send the message.
107
108 Note that the 9 on the end of 17094009 is the sub address 9 meaning no sub
109 address (BT specific). If a different digit is used then that is the sub
110 address for the sending message source address (appended to the outgoing CLI
111 by BT).
112
113 For incoming calls you can use a context like this :-
114
115 [incoming]
116 exten = _XXXXXX/_8005875290,1,SMS(${EXTEN:3},a)
117 exten = _XXXXXX/_8005875290,2,System(/usr/lib/asterisk/smsin ${EXTEN:3})
118 exten = _XXXXXX/_80058752[0-8]0,1,SMS(${EXTEN:3}${CALLERIDNUM:8:1},a)
119 exten = _XXXXXX/_80058752[0-8]0,2,System(/usr/lib/asterisk/smsin
120 ${EXTEN:3}${CALLERIDNUM:8:1})
121 exten = _XXXXXX/_80058752X0,3,Hangup
122
123
124 In this case the called number we get from BT is 6 digits (XXXXXX) and we are
125 using the last 3 digits as the queue name.
126
127 Priority 1 causes the SMS to be received and processed for the incoming call.
128 It is from 080058752X0. The two versions handle the queue name as 3 digits (no
129 sub address) or 4 digits (with sub address). In both cases, after the call a
130 script (smsin) is run - this is optional, but is useful to actually processed
131 the received queued SMS. In our case we email them based on the target number.
132 Priority 3 hangs up.
133
134 If using the CAPI drivers they send the right CLI and so the _800... would be
135 _0800...
136