doc/sms.txt

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