Notify Action

The Notify action sends a notification using an available, configured notification method.

Some Notify actions

Each notification method has its own requirements and limitations; see below.

All notification methods support an expression as the message to be sent. This is done by placing the expression within ${{ }}. For example, a message that inserts the expression variable humidity might look like this: ${{ "The current humidity is " + humidity + "%" }}. Notice that the expression is entirely surrounded by the curly braces. The form The current humidity is ${{humidity}}% is incorrect and will not work. Any valid expression may be used, and all operators and functions are available. For example, if you have temperature in degrees-C but you want your message in degrees-F, you can use ${{ "The temperature is " + ( temp * 1.8 + 32 ) + "F" }}.

Notification Methods

The following notification methods are currently supported:

Alert

The Alert method puts up a notification on the Reactor Status page. Profiles are not supported for this method.

SMTP Mail

The SMTP Mail method sends a SMTP (Simple Mail Transfer Protocol) message. A message and list of recipients must optionally be specified. Email addresses specified with this method must be in the form someone@domain or Name <someone@domain> and may not contain commas, even if quotes are used (e.g. "Lastname, Firstname" <someone@domain> is not acceptable).

The recipient, subject, and message body all allow expression references using the usual ${{ expression }} syntax.

Before using this method, you must configure at least one profile with an outbound mail server. In the configuration file notification.yaml, you'll find an SMTP section. This section contains the various settings that you may need to configure your SMTP server. By default, an SMTP MTA running on the same system as Reactor (aka localhost) will be used, unless you modify the configuration to do otherwise. The configuration details are documented in the configuration file. Please note that any passwords needed are stored in plain text in the configuration file.

Prowl

The Prowl method sends the requested message to the Prowl servers. Setup of an API key is a prerequisite to using this method. An API key can be sourced from the Prowl service by registering for an account at https://www.prowlapp.com/ and then creating an API key at https://prowlapp.com/api_settings.php. Note that the storage of the API key is not secure (plain text in the config file).

You can configure the API key in the Prowl section of the notification.yaml file.

Pushover

The Pushover method sends notifications through the Pushover service. You must register for an account on their web site or through one of their mobile apps. This will give you a user key (shown on the landing page when you log in), and then you can register an application to get an API token. These data can then be added to a Pushover profile in notification.yaml configuration file.

Info

Pushover is a paid service. It offers a limited trial period. See their site for current pricing (as of this writing, it's one-time US$4.99 per client/endpoint).

Attention

As of this writing, the "Emergency (2)" priority level verifiably does not work on Android, and apparently not on iOS either. This is a bug and/or limitation of the Pushover service (and iOS). It is therefore not displayed as an available priority level.

Syslog

The Syslog method sends the message in a Syslog UDP datagram to a server (target port 514). The IP address of the server must be specified. Configuration of this method is done via the Syslog section of the notification.yaml configuration file.

Syslog messages may contain expression variable references using the usual ${{variableName}} syntax.

Any error that occurs in communication with the Syslog server will be logged to the reactor.log file, although these will be minimal because UDP does not guarantee delivery. Please look in the log for messages before posting "it doesn't work" messages on the community forums. The author will not provide diagnostic support for your network or Syslog server.

Telegram

The Telegram method sends a message using the Telegram Bot API. The message text may contain expression variable references using the usual ${{variableName}} syntax. Errors are logged to the reactor.log file.

This notifier supports three basic formatting options for messages: plain text, Markdown (V2), and HTML. If you send messages using the Markdown or HTML format options, your message text must follow the rules for that format, including escaping of special characters, etc. Refer to the Telegram API documentation for specifics.

Router

It's often the case that users have notifications that should be sent to multiple destinations. While you can do this in Reactions by having multiple Notify actions, the Router notifier allows you to configure "routes" that send a single notification to multiple notifiers with a single action. Messages sent using the Router notifier are assigned a priority and optional tags, and these can be matched via configuration to determine how notifications are routed (i.e. to which other notifiers a message is forwarded).

New in 26144!

Router is new for build 26144 and beyond. Its features are still under development, and more options are coming. If you have suggestions to make it more useful, please join the discussion in the Smarthome Community.

The following is the basic form of configuration for the Router notifier's configuration:

notification:
  Router:
    profiles:
      default:
        routes:

First, like all notifiers, Router has profiles, of which one default profile must be provided. You may create as many additional profiles as you wish (each must have a unique ID/name).

Within a profile, the routes array is the list of routes for the profile. A route consists of filter criteria that the notification must match (in a match object), and a list of target notifiers (in a targets array) to which a matching notification will be sent. Let's say we want to send all notifications to the Syslog, for starters. That requires adding a routes element with the Syslog notifier as the sole target, and no match object. When the match object is omitted, all notifications match by default, so all notifications sent to this Router profile will be sent to the Syslog notifier. The updated config now looks like this:

  Router:
    profiles:
      default:
        routes:
          -
            targets:
              - Syslog

No Recursion

In the current implementation, you can not have Router be a target for Router.

Next, let's have all notifications having priority "warning" or higher route to the Alert and Pushover notifiers. Priorities for Router are numbered 1-5 (1=info, 2=notice, 3=warning, 4=error, 5=critical). We add the priority criterion to match with the numeric value 3 to match messages of priority 3 and higher.

  Router:
    profiles:
      default:
        routes:
          -
            targets:
              - Syslog
          -
            match:
              priority: 3  # could also use string ">=3"
            targets:
              - Alert
              - Pushover

The priority criterion can also be given a string containing a number prefixed by an optional comparison operator (=, ==, >, >=, <, <=). If no prefix is given, >= is assumed (matching the behavior of a numeric priority). So for example, if priority: "=3" is given, only messages with priority 3 will be sent to the listed targets.

The Router supports tags on notifications to help further categorize messages for routing. These are simply arbitrary strings that you define. In the match section, the tagged and not_tagged values will be matched to the tags on the notification.

Using tagged, a notification must have any of the listed tags to match the route. Optionally adding tagged_all: true changes the any to all: all listed tags must be present on the message to match the route.

Using not_tagged, the message must not have any of the listed tags. Optionally adding not_tagged_all: true requires that the message not have the complete set of listed routes. For example, let's say our message has tags dev,garage,outdoor. Using not_tagged: basement would match, because basement is not a tag on the message. Using not_tagged: basement,dev without not_tagged_all: true would skip the route, because dev is a tag on the message. Conversely, adding not_tagged_all: true would match (not skip) the route, because basement is not on the message and it now needs to have both basement and dev to be excluded. Put another way, the not_tagged_all: true changes the test from OR to AND.

You can match a message that has no tags at all with untagged: true.

Multiple tags can be specified in one of two ways: as strings delimited by commas, semicolons, or vertical bars (|); or as a YAML array (e.g. tagged: [house, sensor]). Use whichever is easier for you.

Embellishing on our example configuration, here's how I would have all notifications tagged dev go to my developer SMTP (email) profile, and anything not tagged dev go to the default profile (an email address that forwards to everyone in my household):

  Router:
    profiles:
      default:
        routes:
          -
            targets:
              - Syslog
          -
            match:
              priority: 3  # could also use string ">=3"
            targets:
              - Alert
              - Pushover
          -
            match:
              tagged: dev
            targets:
              - SMTP:
                  profile: toggledbits  # Use different SMTP profile for dev matches
          -
            match:
              not_tagged: dev
            targets: SMTP

My default SMTP profile sends to an email address that forwards to everyone in the house, and that's fine for the not_tagged: dev route. On the tagged: dev route, howver, I specified that the SMTP notifier should use my toggledbits profile, which sends to a different email address that the rest of my house doesn't get.

In the targets array, if your targets don't have any overrides, you can just list the name, like this:

            targets:
              - Pushover
              - Alert

If you only have one target, and it doesn't required any overrides, you can use the even-shorter form used in the not_tagged: dev example above: just list the name of the notifier directly as the sole targets: value.

You can mix forms as well, so your targets that don't require overrides can use the shorter syntax, and targets that do use the longer syntax:

            targets:
              - Alert  # short form, no overrides needed here
              - SMTP:
                  profile: toggledbits  # long form for this override

In your sequence of routes, if you want a matched route to be the last route that is checked (i.e. ignore all following routes), you can add stop: true to the route, like this:

          -
            match:
              tagged: dev
            targets:
              - SMTP:
                  profile: toggledbits
            stop: true

Overridable Parameters for Notifiers

The following table lists the parameters that Router can override for a target notifier:

Notifier	Parameter	Description
(all)	`profile`	Specify which profile the target notifier should use (default: `default`)
Alert	`level`	Level of alert to send (0=Error, 1=Warning, 2=Notice)
Prowl	`priority`	Message priority (-2=very low, 1=low, 0=normal, 1=high, 2=emergency)
Pushover	`title`	Message title
	`device`	Target device
	`priority`	Priority (-2=very low, -1=low, 0=normal, 1=high)
	`sound`	Sound name
	`url`	URL for link
	`url_title`	Title for `url`
SMTP	`recipient`	Recipient email address(es)
	`subject`	Subject line
Syslog	`facility`	syslog facility code (number)
	`severity`	syslog severity (number)
Telegram	`chat_id`	Chat ID
	`parse_mode`	Message format (`*`=Plain Text, `MarkdownV2`, `HTML`, `image`, `video`)
	`disable_notification`	`true` to disable notification

Troubleshooting Routes

Troubleshooting routes is best accomplished by turning the logging level for NotifyRouter up to 5 or 6 and sending the log stream to its own file.

# add to logging.yaml and restart:
  NotifyRouter:
    level: 6
    streams:
      - type: file
        name: "NotifyRouter.log"
        recycle: true
        keep: 2

See Logging for more details on configuring a specific object's logging level and output streams.

To assist you with identifying the profile and routes being processed, Router's logging includes the profile name and index of the route. In the example below, which is shown with the default logging level (4/Info) an untagged notification with priority 3 has been sent to our example Router configuration.

... <NotifyRouter:INFO> NotifyRouter[default.1] forwarding to NotifySyslog with { "message": "Message Priority 3", "profile": "default" }
... <NotifyRouter:INFO> NotifyRouter[default.2] forwarding to NotifyAlert with { "message": "Message Priority 3", "profile": "default" }
... <NotifyRouter:INFO> NotifyRouter[default.2] forwarding to NotifyPushover with { "message": "Message Priority 3", "profile": "default" }
... <NotifyRouter:INFO> NotifyRouter[default.4] forwarding to NotifySMTP with { "message": "Message Priority 3", "profile": "default" }

Notice the text in square brackets. The default is the name of the Router profile specified by the action, and the number is the index of the route being processed. Route indexes are simply sequential numbers starting at 1 for each element of the routes array. Route numbers 1, 2, and 4 matched this message, which was forwarded to the Syslog, Alert, Pushover and SMTP notifiers.

With log level 5 or 6, the log will also contain detail messages for each step of matching/route selection. Because our message didn't match route 3 (which requires tag dev that our message doesn't have), we would expect to see this in the log at level 5:

... <NotifyRouter:5> NotifyRouter[default.3] message tags [] did not match tagged="dev" tagged_all=(undefined); SKIP ROUTE

Asynchronous Behavior

Be careful when interpreting the logs when multiple notifications are sent by a route. Notifications in Reactor are asyncrhonous, so the order of log messages can often be confusing, and problems messages from target notifiers can be distant from route selection messages. To avoid this confusion, a good approach is to create a simple (global) Reaction with only one notification action to Router, so you can run that by itself without the noise of other notifications. If a particular target is giving you trouble, comment out the other targets from your route.

Updated 2026-May-24