Skip to main content
This guide shows how to create, manage, and diagnose automation rules. For the conceptual model (triggers, conditions, actions), see Overview.

​
Creating a Rule

  1. Go to Settings → Automation.
  2. Click New Rule.
  3. Give it a descriptive name (e.g., “Assign WhatsApp leads to commercial team”).
  4. Choose a trigger from the list.
  5. (Optional) Add conditions to filter when the rule should fire.
  6. Add one or more actions.
  7. Activate the rule.

​
Tips for Naming

  • Start with the verb of the main action (Assign..., Move..., Tag...).
  • Include context (channel, team, stage) so other operators understand without opening the detail.
  • Avoid generic names like “Rule 1” or “Auto” — you will accumulate dozens and need to find them by search.

​
Conditions and Message Templates

Conditions use the template variable system when you need dynamic comparisons. Starting in v1.0.0-rc3 (EVO-1146), variables gained additional fields:
  • label, source, example, position, component
Use these fields in conditions for more precise expressions. For example: filter by a specific label using the resolved label.title instead of the raw UUID.

​
attribute_changed Operator with From/To

When you want the rule to fire only on a specific attribute transition (e.g., “status changed from pending to qualified”), use the attribute_changed operator with explicit before and after value pickers.

​
Actions with Dynamic Payload

​
send_template

Lets you send a message template with dynamically filled variables. The system applies deep_stringify_keys to the payload so the call works regardless of key shape (string or symbol).

​
send_canned_response

Shortcut to send a canned response stored in Settings → Canned Responses. The payload accepts variables substituted with conversation data.

​
move_to_pipeline (rc3)

Moves the pipeline item to a different pipeline preserving the item’s id. Useful for rules like “if qualified label was added in the Leads pipeline, move to the Sales pipeline”.
The action automatically bypasses the same-pipeline validation. Do not confuse with move_to_stage, which moves within the same pipeline.

​
apply_label

Starting in v1.0.0-rc3, the action shows a label picker instead of free-text input. UUIDs are resolved to titles before tagging, with a fallback in case the label has been renamed.

​
Logs Panel (rc3)

Each rule execution now generates a record in the Automation → Logs panel. You see:
  • When the rule fired.
  • Which conversation / item triggered it.
  • Evaluated conditions — which passed and which did not.
  • Executed actions — success or error.
  • Surfaced errors — including macro webhook failures (which were previously silent, see EVO-1041).

​
Automatic Cleanup

Old logs are removed by a cleanup job that runs periodically. You do not need to delete manually.

​
API Endpoint

To consume logs programmatically (external dashboards, alerts), use the automation_rule_runs listing endpoint. See the API Reference for the full schema.

​
Diagnosing Rules That Do Not Fire

Quick roadmap when a rule appears not to work:
  1. Check if it is active. Disabled rules do not appear as errors — they simply do not run.
  2. Confirm the trigger. conversation_updated covers several cases, but attribute_changed is specific.
  3. Look at the execution log. In the logs panel, filter by the rule. If it appears with “no match”, your conditions are filtering it out.
  4. Label conditions. The labels condition uses EXISTS subquery (independent and NULL-safe) and matches a label on conversation OR contact. If you expected match only on the conversation, narrow it with another condition.
  5. Dedup. For pipeline_stage_updated, there is a 5s window — two events on the same (rule, pipeline_item, stage) in a short window run only once.

​
Loop Prevention

When a move_to_stage rule triggers a pipeline_stage_updated event that could fire the same rule recursively, the system marks the execution with Current.executed_by = :stage_automation and ignores reentries. This prevents infinite loops by design.

​
Final Considerations

Automation rules are the declarative way to encode operational CRM behavior. For more complex flows involving conversational AI, consider combining an automation rule with an agent — the rule handles routing and the agent handles dialogue.