Using smsq

smsq is a simple helper application designed to make it easy to send messages from a command line. it is intended to run on the Asterisk box and have direct access to the queue directories for SMS and for Asterisk.

In its simplest form you can send an SMS by a command such as smsq 0123456789 This is a test to 0123456789 This would create a queue file for a mobile originated TX message in queue 0 to send the text "This is a test to 0123456789" to 0123456789. It would then place a file in the /var/spool/asterisk/outgoing directory to initiate a call to 17094009 (the default message centre in smsq) attached to application SMS with argument of the queue name (0).

Normally smsq will queue a message ready to send, and will then create a file in the Asterisk outgoing directory causing Asterisk to actually connect to the message centre or device and actually send the pending message(s).

Using --process, smsq can however be used on received queues to run a command for each file (matching the queue if specified) with various environment variables set based on the message (see below); smsq options:

   --help
   Show help text
   --usage
   Show usage
   --queue
   -q
   Specify a specific queue
   In no specified, messages are queued under queue "0"
   --da
   -d
   Specify destination address
   --oa
   -o
   Specify originating address
   This also implies that we are generating a mobile terminated message
   --ud
   -m
   Specify the actual message
   --ud-file
   -f
   Specify a file to be read for the context of the message
   A blank filename (e.g. --ud-file= on its own) means read stdin. Very
   useful when using via ssh where command line parsing could mess up the
   message.
   --mt
   -t
   Mobile terminated message to be generated
   --mo
   Mobile originated message to be generated
   Default
   --tx
   Transmit message
   Default
   --rx
   -r
   Generate a message in the receive queue
   --UTF-8
   Treat the file as UTF-8 encoded (default)
   --UCS-1
   Treat the file as raw 8 bit UCS-1 data, not UTF-8 encoded
   --UCS-2
   Treat the file as raw 16 bit bigendian USC-2 data
   --process
   Specific a command to process for each file in the queue
   Implies --rx and --mt if not otherwise specified.
   Sets environment variables for every possible variable, and also ud,
   ud8 (USC-1 hex), and ud16 (USC-2 hex) for each call. Removes files.
   --motx-channel
   Specify the channel for motx calls
   May contain X to use sub address based on queue name or may be full
   number
   Default is Local/1709400X
   --motx-callerid
   Specify the caller ID for motx calls
   The default is the queue name without -X suffix
   --motx-wait
   Wait time for motx call
   Default 10
   --motx-delay
   Retry time for motx call
   Default 1
   --motx-retries
   Retries for motx call
   Default 10
   --mttx-channel
   Specify the channel for mttx calls
   Default is Local/ and the queue name without -X suffix
   --mtttx-callerid
   Specify the callerid for mttx calls
   May include X to use sub address based on queue name or may be full
   number
   Default is 080058752X0
   --mttx-wait
   Wait time for mttx call
   Default 10
   --mttx-delay
   Retry time for mttx call
   Default 30
   --mttx-retries
   Retries for mttx call
   Default 100
   --default-sub-address
   The default sub address assumed (e.g. for X in CLI and dialled numbers
   as above) when none added (-X) to queue
   Default 9
   --no-dial
   -x
   Create queue, but do not dial to send message
   --no-wait
   Do not wait if a call appears to be in progress
   This could have a small window where a message is queued but not
   sent, so regular calls to smsq should be done to pick up any missed
   messages
   --concurrent
   How many concurrent calls to allow (per queue), default 1
   --mr
   -n
   Message reference
   --pid
   -p
   Protocol ID
   --dcs
   Data coding scheme
   --udh
   Specific hex string of user data header specified (not including the
   initial length byte)
   May be a blank string to indicate header is included in the user data
   already but user data header indication to be set.
   --srr
   Status report requested
   --rp
   Return path requested
   --vp
   Specify validity period (seconds)
   --scts
   Specify timestamp (YYYY-MM-DDTHH:MM:SS)
   --spool-dir
   Spool dir (in which sms and outgoing are found)
   Default /var/spool/asterisk

Other arguments starting '-' or '--' are invalid and will cause an error. Any trailing arguments are processed as follows:-

• If the message is mobile originating and no destination address has been specified, then the first argument is assumed to be a destination address

• If the message is mobile terminating and no destination address has been specified, then the first argument is assumed to be the queue name

• If there is no user data, or user data file specified, then any following arguments are assumed to be the message, which are concatenated.

• If no user data is specified, then no message is sent. However, unless --no-dial is specified, smsq checks for pending messages and generates an outgoing anyway

Note that when smsq attempts to make a file in /var/spool/asterisk/outgoing, it checks if there is already a call queued for that queue. It will try several filenames, up to the --concurrent setting. If these files exist, then this means Asterisk is already queued to send all messages for that queue, and so Asterisk should pick up the message just queued. However, this alone could create a race condition, so if the files exist then smsq will wait up to 3 seconds to confirm it still exists or if the queued messages have been sent already. The --no-wait turns off this behaviour. Basically, this means that if you have a lot of messages to send all at once, Asterisk will not make unlimited concurrent calls to the same message centre or device for the same queue. This is because it is generally more efficient to make one call and send all of the messages one after the other.

smsq can be used with no arguments, or with a queue name only, and it will check for any pending messages and cause an outgoing if there are any. It only sets up one outgoing call at a time based on the first queued message it finds. A outgoing call will normally send all queued messages for that queue. One way to use smsq would be to run with no queue name (so any queue) every minute or every few seconds to send pending message. This is not normally necessary unless --no-dial is selected. Note that smsq does only check motx or mttx depending on the options selected, so it would need to be called twice as a general check.

UTF-8 is used to parse command line arguments for user data, and is the default when reading a file. If an invalid UTF-8 sequence is found, it is treated as UCS-1 data (i.e, as is). The --process option causes smsq to scan the specified queue (default is mtrx) for messages (matching the queue specified, or any if queue not specified) and run a command and delete the file. The command is run with a number of environment variables set as follows. Note that these are unset if not needed and not just taken from the calling environment. This allows simple processing of incoming messages

   $queue
   Set if a queue specified
   $?srr
   srr is set (to blank) if srr defined and has value 1.
   $?rp
   rp is set (to blank) if rp defined and has value 1.
   $ud
   User data, UTF-8 encoding, including any control characters, but with
   nulls stripped out
   Useful for the content of emails, for example, as it includes any
   newlines, etc.
   $ude
   User data, escaped UTF-8, including all characters, but control
   characters \n, \r, \t, \f, \xxx and \ is escaped as \\
   Useful guaranteed one line printable text, so useful in Subject lines
   of emails, etc
   $ud8
   Hex UCS-1 coding of user data (2 hex digits per character)
   Present only if all user data is in range U+0000 to U+00FF
   $ud16
   Hex UCS-2 coding of user data (4 hex digits per character)
   other
   Other fields set using their field name, e.g. mr, pid, dcs, etc. udh
   is a hex byte string