Matrix push rules for quiet previews

When channels.matrix.streaming is "quiet", FluffBuzz edits a single preview event in place and marks the finalized edit with a custom content flag. Matrix clients notify on the final edit only if a per-user push rule matches that flag. This page is for operators who self-host Matrix and want to install that rule for each recipient account. If you only want stock Matrix notification behavior, use streaming: "partial" or leave streaming off. See Matrix channel setup.

Prerequisites

recipient user = the person who should receive the notification
bot user = the FluffBuzz Matrix account that sends the reply
use the recipient user’s access token for the API calls below
match sender in the push rule against the bot user’s full MXID
the recipient account must already have working pushers — quiet preview rules only work when normal Matrix push delivery is healthy

Steps

Configure quiet previews

{
  channels: {
    matrix: {
      streaming: "quiet",
    },
  },
}

Get the recipient's access token

Reuse an existing client session token where possible. To mint a fresh one:

curl -sS -X POST \
  "https://matrix.example.org/_matrix/client/v3/login" \
  -H "Content-Type: application/json" \
  --data '{
    "type": "m.login.password",
    "identifier": { "type": "m.id.user", "user": "@alice:example.org" },
    "password": "REDACTED"
  }'

Verify pushers exist

curl -sS \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  "https://matrix.example.org/_matrix/client/v3/pushers"

If no pushers come back, fix normal Matrix push delivery for this account before continuing.

Install the override push rule

FluffBuzz marks finalized text-only preview edits with content["com.fluffbuzz.finalized_preview"] = true. Install a rule that matches that marker plus the bot MXID as sender:

curl -sS -X PUT \
  "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/fluffbuzz-finalized-preview-botname" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "conditions": [
      { "kind": "event_match", "key": "type", "pattern": "m.room.message" },
      {
        "kind": "event_property_is",
        "key": "content.m\\.relates_to.rel_type",
        "value": "m.replace"
      },
      {
        "kind": "event_property_is",
        "key": "content.com\\.fluffbuzz\\.finalized_preview",
        "value": true
      },
      { "kind": "event_match", "key": "sender", "pattern": "@bot:example.org" }
    ],
    "actions": [
      "notify",
      { "set_tweak": "sound", "value": "default" },
      { "set_tweak": "highlight", "value": false }
    ]
  }'

Replace before running:

https://matrix.example.org: your homeserver base URL
$USER_ACCESS_TOKEN: the recipient user’s access token
fluffbuzz-finalized-preview-botname: a rule ID unique per bot per recipient (pattern: fluffbuzz-finalized-preview-<botname>)
@bot:example.org: your FluffBuzz bot MXID, not the recipient’s

Verify

curl -sS \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/fluffbuzz-finalized-preview-botname"

Then test a streamed reply. In quiet mode the room shows a quiet draft preview and notifies once the block or turn finishes.

To remove the rule later, DELETE the same rule URL with the recipient’s token.

Multi-bot notes

Push rules are keyed by ruleId: re-running PUT against the same ID updates a single rule. For multiple FluffBuzz bots notifying the same recipient, create one rule per bot with a distinct sender match. New user-defined override rules are inserted ahead of default suppress rules, so no extra ordering parameter is needed. The rule only affects text-only preview edits that can be finalized in place; media fallbacks and stale-preview fallbacks use normal Matrix delivery.

Homeserver notes

Synapse

No special homeserver.yaml change is required. If normal Matrix notifications already reach this user, the recipient token + pushrules call above is the main setup step.If you run Synapse behind a reverse proxy or workers, make sure /_matrix/client/.../pushrules/ reaches Synapse correctly. Push delivery is handled by the main process or synapse.app.pusher / configured pusher workers — ensure those are healthy.

Tuwunel

Same flow as Synapse; no Tuwunel-specific config is needed for the finalized preview marker.If notifications disappear while the user is active on another device, check whether suppress_push_when_active is enabled. Tuwunel added this option in 1.4.2 (September 2025) and it can intentionally suppress pushes to other devices while one device is active.

Overview

Messaging platforms

Configuration

Matrix push rules for quiet previews

Prerequisites

Steps

Multi-bot notes

Homeserver notes

​Prerequisites

​Steps

​Multi-bot notes

​Homeserver notes

​Related

Prerequisites

Steps

Multi-bot notes

Homeserver notes

Related