# 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.

This parameter is executed through shell, so you might need to escape some special characters and you can include any number of parameters. Additionally parameters with identifiers of received messages are appended to the command line. The identifiers depend on used service backend, typically it is ID of inserted row for database backends or file name for file based backends.

Gammu SMSD waits for the script to terminate. If you make some time consuming there, it will make SMSD not receive new messages. However to limit breakage from this situation, the waiting time is limited to two minutes. After this time SMSD will continue in normal operation and might execute your script again.

Note

All input and output file descriptors are closed when this program is invoked, so you have to ensure to open files on your own.

## 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

### 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))