Message, keyword, and time triggers
Rules can match a new message, listed keywords, or an out-of-hours condition. The first_message_only flag supports welcome flows.
WhatsApp Automation
Trigger, filter, act — a rules engine that respects provider state.
Wavy's automation engine evaluates inbound WhatsApp messages against rules. Each rule has a trigger (what event starts it), filters (what conditions must match), and an action (what happens). Built-in rules handle welcome replies, out-of-office messages, and broadcast unsubscribe. Custom rules can send messages, hand off to a bot, or invoke AI Copilot — but send actions respect the channel's configured or dry-run state, and AI features require a server-side LLM key.
Status: Configuration-dependentRules engine and built-in rules exist. Send actions require a configured channel; AI features require an LLM key.
Built-in rules seededWelcome, out-of-office, and unsubscribe rules are seeded on startup and can be toggled or replaced.
Dry-run awareSend-message actions go through the WhatsAppClient, which returns synthetic IDs when unconfigured.
How automation works
The exact path from inbound webhook to rule action.
This is the real rules-engine flow in the backend — not a generic automation overview.
- Inbound message arrives — Meta posts the message to the
/webhooks/metaendpoint. The verifier checks the HMAC signature (constant-time). The message is persisted to the conversation and message tables. - Trigger evaluation — The rules engine supports
new_message,keyword, andout_of_hourstriggers. New-message rules may usefirst_message_only; keyword rules read their keyword list from the trigger. - Filter matching — The current filter implementation is used by
out_of_hoursfor working-hour settings. It is not a general visual condition builder for arbitrary message fields. - Action execution — Matching rules can send a configured text body, assign, tag, or update selected contact attributes. Text sends use WhatsAppClient; unconfigured sends return synthetic IDs and do not call Meta.
- Side effects — The
unsubscribeaction immediately suppresses the contact by setting their opted_in flag to False. Automation replies are recorded with provider message IDs when available, so the conversation log reflects what actually happened.
Built-in rules
Four rules seeded on startup.
These are defined in the rules service and seeded when the backend starts. They can be toggled off or replaced with custom rules.
- WA Welcome message — Trigger: new message, first message only. Action: sends a welcome reply referencing the contact's name. This is the first-touch auto-response.
- Out-of-office reply — Trigger: out-of-hours. Action: sends an away message outside the configured working hours.
- Broadcast unsubscribe — Trigger: keyword matching stop or unsubscribe. Action: sets
opted_into False and marks the lead Unsubscribed. - Hello keyword sample — Trigger: keyword matching hello or hi. Action: sends the configured greeting text.
What you need
Requirements for live automation.
Automation without a configured channel is a dry run. Automation with AI features needs an LLM key.
- A configured WhatsApp channel — Send-message actions go through the WhatsAppClient. Without server credentials, sends return synthetic IDs and no real reply reaches the contact.
- A verified webhook — Automation is triggered by inbound messages. Without a verified Meta webhook, no inbound message reaches the rules engine.
- An LLM key for AI actions — AI Copilot features (suggested replies, summaries, translation) call an OpenAI-compatible endpoint. Without
LLM_API_KEYset server-side, Copilot methods return a not-configured response. - Custom rules — Custom rules are created via the rules API with a name, trigger, filters, and action. They are workspace-scoped and can be enabled or disabled independently of built-in rules.
Safeguards
What keeps automation from running wild.
- Provider-state respect — Send actions go through the WhatsAppClient, which checks its
configuredproperty. Unconfigured sends do not call Meta — they return synthetic IDs so the automation log shows what would have been sent without actually sending it. - Immediate unsubscribe — The unsubscribe action suppresses the contact synchronously. There is no delay window where a suppressed contact could still receive a broadcast.
- Workspace isolation — Rules are workspace-scoped. A rule in one workspace cannot trigger on another workspace's messages or send through another workspace's channel.
- AI degradation is explicit — Copilot methods return a clear "not configured" string when no LLM key is set. They do not silently produce low-quality or empty responses that could be mistaken for real AI output.
- Bot routing needs review — Bot dispatch runs when a conversation is marked as bot-handled and an enabled workspace connector exists. The current selector uses an enabled workspace connector rather than a per-conversation connector binding.
Automation capabilities
What the rules engine covers today.
Working-hours filter
The current filter implementation supplies working-hour settings to out-of-hours rules; it is not yet a general condition canvas.
Send-message action
Sends a configured text body through WhatsAppClient. It respects configured and dry-run states — no real send occurs without credentials.
Unsubscribe suppression
Immediately sets the contact's opted_in flag to False. Suppressed contacts are excluded from future campaign segments.
AI Copilot integration
Copilot can suggest replies, summarise conversations, and translate — but only when an LLM key is configured server-side.
Questions
WhatsApp automation — straight answers.
Can automation send messages without a configured channel?
The rule fires, but the send-message action goes through the WhatsAppClient, which returns a synthetic ID and does not call Meta. This is the dry-run fallback. No real reply reaches the contact until the channel is configured.
Are the built-in rules mandatory?
No. They are seeded on startup but can be toggled off or replaced with custom rules. You control which rules are enabled for your workspace.
Does automation work without a webhook?
No. Automation is triggered by inbound messages arriving via the Meta webhook. Without a verified webhook, no inbound message reaches the rules engine.
Can I use AI to generate auto-replies?
AI Copilot can suggest replies and summaries, but it requires an LLM key configured server-side. Without it, Copilot methods return a not-configured response. AI-generated replies are suggestions for a human to review, not autonomous sends.
What happens when a contact replies with an unsubscribe keyword?
The unsubscribe built-in rule fires and immediately suppresses the contact by setting their opted_in flag to False. They are excluded from future campaign segments from that point forward.
When does bot dispatch run?
It runs when the conversation is marked as bot-handled and an enabled workspace connector exists. The current selector is workspace-level, so connector routing requires careful review before live use.
Automate with rules that respect provider state.
The rules engine fires on real inbound messages, but send actions respect your channel's configured state. Configure your webhook and channel to move from dry-run to live automation.