Skip to end of metadata
Go to start of metadata

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

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

  • No labels