RunOnReceive Directive

Description

Gammu SMSD can be configured by RunOnReceive directive (see SMSD Configuration File for details) to run defined program after receiving every message. It can receive single message or more messages, which are parts of one multipart message.

The configured command can include parameters. SMSD appends identifiers of received messages as additional arguments. The identifiers depend on the service backend: typically database row IDs or file names for the files backend. File names do not include the inbox directory. There can be multiple arguments for a multipart message, so scripts must handle all supplied identifiers.

On POSIX systems, the configured command is executed through a shell, so special characters in that command need to be escaped. Message identifiers are passed as separate literal arguments. SMSD waits for the script to terminate, so slow scripts can delay receiving new messages. Do not rely on a fixed timeout to interrupt a blocked script.

On Windows, SMSD starts the configured executable directly. Batch files require an explicit command interpreter, as shown in Running a batch file on Windows. SMSD does not wait for the process to finish or collect its exit status. Hooks can overlap, and successful process creation does not mean that message forwarding succeeded.

Note

On POSIX systems, standard input is closed and standard output and standard error are captured in the SMSD log. On Windows, the hook must arrange its own output and error logging. Scripts should not require interactive input.

Environment

Added in version 1.28.0.

Program is executed with environment which contains lot of information about the message. You can use it together with NULL service (see Null Backend) to implement completely own processing of messages.

Global variables

SMS_MESSAGES: Number of physical messages received.

DECODED_PARTS: Number of decoded message parts.

PHONE_ID: Added in version 1.38.2.

Value of PhoneID. Useful when running multiple instances (see Multiple modems). This variable is available to all RunOn directives, including calls which do not provide message details.

Per message variables

The variables further described as SMS_1_... are generated for each physical message, where 1 is replaced by current number of message.

SMS_1_CLASS: Class of message.

SMS_1_NUMBER: Sender number.

SMS_1_TEXT: Message text. Text is not available for 8-bit binary messages.

SMS_1_REFERENCE: Added in version 1.38.5.

Message Reference. If delivery status received, this variable contains TPMR of original message

SMS_1_SENT_ID: For a delivery report matched by a database backend, the ID of the corresponding row in the sentitems table. The value is empty for other messages, when no matching sent message was found, and for non-database backends.

SMS_1_TIMESTAMP: Message date and time as seconds since the Unix epoch. For a received message this is the service center timestamp. For a delivery report this is the time when the service center received the original message. The value is empty when the message does not contain a valid date and time.

SMS_1_DATETIME: The same value as SMS_1_TIMESTAMP, formatted as ISO 8601 with a timezone offset, for example 2024-01-02T03:04:05+01:30.

SMS_1_SMSC_TIMESTAMP: For a delivery report, the discharge time as seconds since the Unix epoch. The value is empty for other messages or when the report does not contain a valid discharge time.

SMS_1_SMSC_DATETIME: The same value as SMS_1_SMSC_TIMESTAMP, formatted as ISO 8601 with a timezone offset.

Per part variables

The variables further described as DECODED_1_... are generated for each message part, where 1 is replaced by current number of part. Set are only those variables whose content is present in the message.

DECODED_1_TEXT: Decoded long message text.

DECODED_1_MMS_SENDER: Sender of MMS indication message.

DECODED_1_MMS_TITLE: title of MMS indication message.

DECODED_1_MMS_ADDRESS: Address (URL) of MMS from MMS indication message.

See also

Can I use Gammu to receive MMS?

DECODED_1_MMS_SIZE: Size of MMS as specified in MMS indication message.

Examples

Activating RunOnReceive

To activate this feature you need to set RunOnReceive in the SMSD Configuration File.

[smsd]
RunOnReceive = /path/to/script.sh

Running a batch file on Windows

Use cmd.exe to launch a batch file. For example, with the script and inbox in C:\gammu:

[smsd]
RunOnReceive = C:\Windows\System32\cmd.exe /d /c C:\gammu\forward_sms.bat

Adjust these absolute paths to match your installation and restart SMSD after changing the configuration. The example uses paths without spaces.

Do not add "%FILE%": this is not a Gammu placeholder. SMSD appends the received file names automatically. For example, the batch file receives IN20260228_053040_00_+61402111111_00.txt as its first argument. In the batch file, %1 accesses that argument and %~1 removes surrounding quotes. With the inbox above, the full path is C:\gammu\%~1. Process subsequent arguments as well, for example using shift in a loop.

Use absolute paths for the inbox, address book, log files, and helper programs. The hook inherits SMSD’s working directory, which need not be the script or inbox directory. When moving SMSD to a Windows service, ensure the service account can access these files and any credentials needed by the forwarding program.

To test invocation separately from email delivery, save the following as C:\gammu\receive-test.bat and temporarily use that path in RunOnReceive:

@echo off
setlocal DisableDelayedExpansion
>>C:\gammu\receive-hook.log echo Hook started
>>C:\gammu\receive-hook.log set SMS_MESSAGES
>>C:\gammu\receive-hook.log set SMS_1_NUMBER

Restart SMSD and send a fresh SMS. A new entry in receive-hook.log confirms that the batch file started. If no entry appears, check the SMSD log for Starting run on receive and CreateProcess failed, and check that the account running SMSD can write the diagnostic log. Restore the forwarding script path after testing. Its own log should record processing and email delivery errors because Windows SMSD does not collect the script’s output or exit status.

Forwarding messages with an address book

A forwarding program can match SMS_1_NUMBER against the Number column of a CSV address book and use the corresponding Name in the email subject. Store and compare phone numbers in a consistent format, for example international numbers beginning with +, and use the sender’s number when no name matches.

For multipart text, use the available DECODED_n_TEXT variables described above, or process all file arguments. Do not assume SMS_1_TEXT contains the entire message. Read message text as data inside the forwarding program rather than expanding it into batch commands, where SMS characters could be interpreted as command syntax.

Configure SMTP authentication in the forwarding program. That program is also responsible for logging delivery failures and retaining pending messages for retry; starting a hook does not guarantee email delivery.

Processing messages from the files backend

Following script (if used as RunOnReceive handler) passes message data to other program. This works only with the Files backend.

#!/bin/sh
INBOX=/path/to/smsd/inbox
PROGRAM=/bin/cat
for ID in "$@" ; do
    $PROGRAM < $INBOX/$ID
done

Invoking commands based on message text

Following script (if used as RunOnReceive handler) executes given programs based on message text.

#!/bin/sh

# Check for sender number
if [ "$SMS_1_NUMBER" != "+420123456789" ] ; then
    exit
fi

# Handle commands
case "$SMS_1_TEXT" in
    "DMS A")
        /usr/bin/dms-a
        ;;
    "DMS B")
        /usr/bin/dms-b
        ;;
esac

Passing message text to program

Following script (if used as RunOnReceive handler) passes message text and sender to external program.

#!/bin/sh
PROGRAM=/bin/echo
for i in `seq $SMS_MESSAGES` ; do
    eval "$PROGRAM \"\${SMS_${i}_NUMBER}\" \"\${SMS_${i}_TEXT}\""
done

Passing MMS indication parameters to external program

Following script (if used as RunOnReceive handler) will write information about each received MMS indication to the log file. Just replace echo command with your own program to do custom processing.

#!/bin/sh
if [ $DECODED_PARTS -eq 0 ] ; then
    # No decoded parts, nothing to process
    exit
fi
if [ "$DECODED_1_MMS_ADDRESS" ] ; then
    echo "$DECODED_1_MMS_ADDRESS" "$DECODED_1_MMS_SENDER" "$DECODED_1_MMS_TITLE" >> /tmp/smsd-mms.log
fi

Processing message text in Python

Following script (if used as RunOnReceive handler) written in Python will concatenate all text from received message:

#!/usr/bin/env python

import os

numparts = int(os.environ["DECODED_PARTS"])

text = ""
# Are there any decoded parts?
if numparts == 0:
    text = os.environ["SMS_1_TEXT"]
# Get all text parts
else:
    for i in range(1, numparts + 1):
        varname = "DECODED_%d_TEXT" % i
        if varname in os.environ:
            text = text + os.environ[varname]

# Do something with the text
print("Number {} have sent text: {}".format(os.environ["SMS_1_NUMBER"], text))