--- name: "gammu-smsd-run" section: "7" platform: "linux" package: "gammu" version: "1.45.0-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/gammu-smsd-run" --- # gammu-smsd-run(7) documentation for RunOnReceive directive ## NAME gammu-smsd-run - documentation for RunOnReceive directive ## DESCRIPTION Gammu SMSD can be configured by **RunOnReceive** \<#option-RunOnReceive\> directive (see SMSD Configuration File \<#gammu-smsdrc\> 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 \<#gammu-smsd-null\>) 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** \<#option-PhoneID\>. Useful when running multiple instances (see Multiple modems \<#smsd-multi\>). 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? \<#faq-mms-download\> - **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** \<#option-RunOnReceive\> in the SMSD Configuration File \<#gammu-smsdrc\>. ``` [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** \<#option-RunOnReceive\> handler) passes message data to other program. This works only with the Files backend \<#gammu-smsd-files\>. ``` #!/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** \<#option-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** \<#option-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** \<#option-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** \<#option-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)) ``` ## Author Michal Čihař \ ## Copyright 2009-2015, Michal Čihař \