Automation rules¶

The rules engine fires on every inbound message, outbound send, or cron schedule. Rules let you auto-reply, forward to webhooks, suppress messages, and log events — without writing code.

How rules work¶

When a message arrives, the bridge evaluates every enabled rule in order. If a rule's conditions match, its action fires. Multiple rules can match the same message — all matching rules execute unless a stop action is set.

Rules live in ~/.chatwire/rules.json and are fully editable from Settings → Automation in the web UI.

Creating a rule¶

Open Settings → Automation
Click Add rule
Choose a trigger, add conditions, pick an action
Click Save

Rules appear in the list with enable/disable toggles and ↑/↓ reorder buttons.

Triggers¶

Trigger	When it fires
`on_inbound`	Every received message
`on_send`	After every outbound send (including relays)
`cron: <schedule>`	On a cron schedule (e.g., `cron: 0 9 * * 1-5` = weekdays at 9am)

Conditions¶

Conditions filter which messages a rule applies to. All conditions in a rule must match (AND logic). Leave conditions empty to match all messages.

Text conditions¶

Condition	Syntax	Example
Sender	`from:<handle-or-name>`	`from:Alice` or `from:+15551234567`
Text contains	`contains:<text>`	`contains:urgent`
Text matches regex	`matches:<regex>`	`matches:^\d{4}$`
Group chat	`group:<name-or-guid>`	`group:Family`
Direction	`direction:inbound` or `direction:outbound`

Combining conditions¶

Use AND, OR, and NOT in the DSL:

from:Alice AND contains:urgent
from:Bob OR from:Carol
NOT group:Work
from:Alice AND (contains:call OR contains:urgent)

The DSL toggle in the rule builder switches between dropdown UI and raw text input.

Actions¶

Action	What it does
`auto_reply`	Send an automatic reply from your account
`webhook`	POST the message to a URL
`suppress`	Drop the message (don't relay to any integration)
`log`	Write a structured entry to `chatwire.jsonl`
`ntfy`	Send a push notification (requires ntfy plugin)
`stop`	Stop evaluating further rules for this message

auto_reply¶

{
  "action": "auto_reply",
  "body": "I'm away right now. I'll get back to you soon."
}

The reply is sent as you via Messages.app. Applies the same anti-spam fuse as manual sends.

webhook¶

{
  "action": "webhook",
  "url": "https://example.com/hook",
  "secret": "optional-hmac-secret",
  "timeout_s": 10
}

The bridge POSTs JSON to the URL:

{
  "ts": "2026-05-16T14:00:00Z",
  "sender": "Alice",
  "handle": "+15551234567",
  "group": null,
  "text": "Are you around?",
  "trigger": "on_inbound"
}

Include a secret to add an X-Chatwire-Signature HMAC header for verification.

suppress¶

Stops the message from reaching any integration (Telegram, ntfy, web UI, etc.). Useful for filtering spam or muting a contact temporarily.

{
  "action": "suppress"
}

log¶

Writes a structured entry to chatwire.jsonl (visible in Settings → Logs):

{
  "action": "log",
  "message": "Rule matched: urgent from Alice"
}

stop¶

Stops rule evaluation for this message. No further rules are checked.

{
  "action": "stop"
}

Rule file format¶

Rules are stored in ~/.chatwire/rules.json:

[
  {
    "id": "rule-001",
    "name": "Urgent from Alice",
    "enabled": true,
    "trigger": "on_inbound",
    "conditions": "from:Alice AND contains:urgent",
    "action": {
      "type": "auto_reply",
      "body": "On my way!"
    }
  },
  {
    "id": "rule-002",
    "name": "Webhook on all inbound",
    "enabled": false,
    "trigger": "on_inbound",
    "conditions": "",
    "action": {
      "type": "webhook",
      "url": "https://example.com/hook"
    }
  }
]

Edit the file directly or via the web UI — both are equivalent. The bridge loads the file on each relevant event, so changes take effect immediately.

Cron rules¶

Cron rules fire on a schedule, not on a message event. They receive no message context — use them for periodic tasks like sending a reminder or calling a webhook.

{
  "trigger": "cron: 0 8 * * 1",
  "name": "Monday morning reminder",
  "action": {
    "type": "webhook",
    "url": "https://example.com/weekly-hook"
  }
}

Standard cron syntax: minute hour day month weekday. Use * for "every".

Reordering rules¶

Rule order matters when rules share conditions — the first matching rule with stop terminates evaluation. Drag rules in the Settings UI or edit the JSON array directly.

↑/↓ buttons in the rule list let you adjust order without drag-and-drop.

Troubleshooting rules¶

A rule isn't firing: - Check that the rule is enabled (green toggle) - Verify the trigger matches the message type (inbound vs. outbound) - Test your DSL in the rule builder's preview panel - Check chatwire logs -f for rule engine errors

Auto-replies are hitting the fuse: - Auto-replies count toward the anti-spam fuse like manual sends - Consider using suppress or log for high-volume rules instead of auto_reply