Behavior rules & triggers

Behavior rules let the agent do something beyond answering — pop a CTA when the visitor matches an intent, prompt for an email after a threshold, suggest a curated answer when keywords match. They run on every turn, both server-side (during prompt assembly) and client-side (for visible UI like CTAs).

Anatomy of a rule

Each rule is a row in behavior_rules with three pieces:

• kind — what type of rule. Currently: cta, lead_capture, route, curated.
• conditions — JSON describing when the rule fires (intent keywords, page URL match, scroll depth, idle time, message count).
• action — JSON describing what to do (show CTA card, ask for email, route to human, return curated text).

Rules also have enabled (boolean) and priority (integer) fields. Higher priority wins when multiple rules match. Disabled rules are kept around for history, not deleted.

Editing rules

Open /app/agents/{id}/behavior. The form is a kind-aware builder — pick the kind, fill in conditions and action, save. Up to 20 enabled rules are loaded into the widget at init time; anything beyond that is ignored at runtime (so prune the disabled list periodically).

Triggers (visitor-side)

The widget tracks lightweight signals to fire rules without the visitor saying anything:

• Scroll depth — fired when the visitor passes a percentage of the page.
• Idle — fired when there's no input or scroll for N seconds.
• Exit intent — fired when the cursor leaves the viewport toward the top of the screen.
• URL match — fired when the current page URL matches a regex.

These are evaluated locally in the widget so the trigger fires instantly. The actual action (show a CTA card, etc.) happens client-side too — no round-trip needed.

CTAs

A CTA action renders a card inside the chat panel with a title, description, and one or two buttons. Buttons can:

• Open a URL in a new tab.
• Send a message as if the visitor typed it.
• Capture a lead (open the inline lead form).
• Dismiss.

Manage CTAs at /app/agents/{id}/ctas. They're stored as behavior rules with kind=cta, but the dedicated UI is friendlier than the raw rule editor.

Curated answers

Curated answers short-circuit the RAG pipeline. If a visitor's question matches a curated trigger (substring or regex), the curated text streams back instead of going through retrieval and the LLM. Useful for:

• Pricing questions where you want exact numbers, never paraphrased.
• Refund/legal language that has to be word-for-word.
• "How do I contact support?" where you want to control the routing.

Manage them at /app/agents/{id}/curated. Each entry has a list of trigger phrases, the canned answer, and an optional citation. At runtime the agent streams the curated text token-by-token to mimic the LLM's behavior — visitors don't see a jarring pop-in.

Lead capture rules

A lead_capture rule fires the inline lead form. Common triggers:

• After N message turns (visitor's intent looks real).
• When low-confidence is detected ("we'll follow up").
• On exit intent ("before you go…").

The form fields are configurable — name, email, phone, and any custom field you've defined. See Voice, leads & persistence for the visitor-side flow.

Routing rules

A route rule pings a human operator. Use it to escalate when:

• The visitor explicitly asks for a human.
• Confidence drops below a threshold.
• The conversation reaches a complexity heuristic (long messages, multiple unanswered topics).

The route appears in /app/inbox as an unread thread; an operator can claim it and continue inline. See Inbox & human takeover.

Experiments

Behavior rules can be A/B tested. The Experiments page (/app/agents/{id}/experiments) lets you split traffic between two rule variants and watch the conversion delta. The split is per-visitor, not per-conversation — once a visitor is bucketed they stay in that bucket for the lifetime of the conversation.