aboutsummaryrefslogtreecommitdiffstats
path: root/doc/sms.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/sms.txt')
-rw-r--r--doc/sms.txt147
1 files changed, 147 insertions, 0 deletions
diff --git a/doc/sms.txt b/doc/sms.txt
new file mode 100644
index 000000000..02e38764b
--- /dev/null
+++ b/doc/sms.txt
@@ -0,0 +1,147 @@
+* The SMS application
+---------------------
+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 analog calls.
+
+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 (like a VoIP call using GSM codec).
+
+Typical applications include:-
+
+1. Connection to a message centre to send text messages - probably initiated via the
+ manager interface or "outgoing" directory
+2. Connection to an POTS line with an SMS capable phone to send messages - probably
+ initiated via the manager interface or "outgoing" directory
+3. Acceptance of calls from the message centre (based on CLI) and storage of
+ received messages
+4. Acceptance of calls from a POTS line with an SMS capable phone and storage of
+ received messages
+
+* Arguments to sms():
+
+- First argument is queue name
+- Second is options:
+ a: SMS() is to act as the answering side, and so send the initial FSK frame
+ s: SMS() is to act as a service centre side rather than as terminal equipment
+
+- If a third argument is specified, then SMS does not handle the call at all,
+ but takes the third argument as a destination number to send an SMS to
+- The forth argument onward is a message to be queued to the number in the
+ third argument. All this does is create the file in the me-sc directory.
+ If 's' is set then the number is the source
+ address and the message placed in the sc-me directory.
+
+All text messages are stored in /var/spool/asterisk/sms
+A log is recorded in /var/log/asterisk/sms
+
+There are two subdirectories called sc-me.<queuename> holding all
+messages from service centre to phone, and me-sc.<queuename> holding all
+messages from phone to service centre.
+
+In each directory are messages in files, one per file, using any filename not
+starting with a dot.
+
+When connected as a service centre, SMS(s) will send all messages waiting in
+the sc-me-<queuename> directory, deleting the files as it goes. Any
+received in this mode are placed in the me-sc-<queuename> directory.
+
+When connected as a client, SMS() will send all messages waiting in the
+me-sc-<queuename> directory, deleting the files as it goes. Any received in
+this mode are placed in the sc-me-<queuename> directory.
+
+Message files created by SMS() use a time stamp/reference based filename.
+
+The format of the sms file is lines that have the form of key=value
+Keys are :
+
+oa Originating Address
+ Telephone number, national number if just digits
+ Telephone number starting with + then digits for international
+ Ignored on sending messages to service centre (CLI used)
+da Destination Address
+ Telephone number, national number if just digits
+ Telephone number starting with + then digits for international
+scts Service Centre Time Stamp
+ In the format YYYY-MM-DD HH:MM:SS
+pid Protocol Identifier (decimal octet value)
+dcs Data coding scheme (decimal octet value)
+mr Message reference (decimal octet value)
+ud The message (see escaping below)
+srr 0/1 Status Report Request
+rp 0/1 Return Path
+vp mins validity period
+
+Omitted fields have default values.
+
+Note that there is special format for ud, ud# instead of ud= which is followed
+by raw hex (2 characters per octet). This is used in output where characters
+other than 10,13,32-126,128-255 are included in the data. In this case a comment (line
+starting ;) is added showing the printable characters
+
+When generating files to send to a service centre, only da and ud need be
+specified. oa is ignored.
+
+When generating files to send to a phone, only oa and ud need be specified. da is ignored.
+
+When receing a message as a service centre, only the destination address is
+sent, so the originating address is set to the callerid.
+
+EXAMPLES
+
+The following are examples of use within the UK using BT Text SMS/landline
+service.
+
+This is a context to use with a manager script.
+
+[smsdial]
+; create and send a text message, expects number+message and
+; connect to 17094009
+exten => _X.,1,SMS(${CALLERIDNUM},,${EXTEN},${CALLERIDNAME})
+exten => _X.,n,SMS(${CALLERIDNUM})
+exten => _X.,n,Hangup
+
+The script sends
+
+ action: originate
+ callerid: message <from>
+ exten: to
+ channel: Local/17094009
+ context: smsdial
+ priority: 1
+
+You put the message as the name of the caller ID (messy, I know), the
+originating number and hence queue name as the number of the caller ID and the
+exten as the number to which the sms is to be sent. The context uses SMS to
+create the message in the queue and then SMS to communicate iwth 17094009 to
+actually send the message.
+
+Note that the 9 on the end of 17094009 is the sub address 9 meaning no sub
+address (BT specific). If a different digit is used then that is the sub
+address for the sending message source address (appended to the outgoing CLI
+by BT).
+
+For incoming calls you can use a context like this :-
+
+[incoming]
+exten => _XXXXXX/_8005875290,1,SMS(${EXTEN:3},a)
+exten => _XXXXXX/_8005875290,n,System(/usr/lib/asterisk/smsin ${EXTEN:3})
+exten => _XXXXXX/_80058752[0-8]0,1,SMS(${EXTEN:3}${CALLERIDNUM:8:1},a)
+exten => _XXXXXX/_80058752[0-8]0,n,System(/usr/lib/asterisk/smsin ${EXTEN>:3}${CALLERIDNUM:8:1})
+exten => _XXXXXX/_80058752[0-8]0,n,Hangup
+
+
+In this case the called number we get from BT is 6 digits (XXXXXX) and we are
+using the last 3 digits as the queue name.
+
+Priority 1 causes the SMS to be received and processed for the incoming call.
+It is from 080058752X0. The two versions handle the queue name as 3 digits (no
+sub address) or 4 digits (with sub address). In both cases, after the call a
+script (smsin) is run - this is optional, but is useful to actually processed
+the received queued SMS. In our case we email them based on the target number.
+Priority 3 hangs up.
+
+If using the CAPI drivers they send the right CLI and so the _800... would be
+_0800...
+