B Blengi docs
/

Build your agent

Behavior rules & triggers

Triggers open the chat by themselves at a moment you choose — a visitor about to leave, sitting idle, scrolling far, arriving from a campaign — with a message of your own. In the code and the database they are behavior rules (the behavior_rules table). They run in the visitor's browser only; nothing about them happens during a chat turn.

Where to set them

On the AI employee, Behaviour › When the chat opens by itself (/app/agents/{id}/behavior), under Triggers, next to auto-open and the staged invitation. To add one, fill in Name, pick When, give the one number that kind needs, write the text for Bar opens with message, and click Add trigger.

The list below the form says in plain words when each trigger fires, with its message. The trash icon deletes one after a confirmation. The page has no edit and no on/off switch: to change a trigger, delete it and add it again.

The seven triggers

WhenCodeFiresSetting
About to leave the pageexit_intentWhen the mouse leaves the page through the top edge. It needs a mouse, so in practice desktop only.—
No activity for a whileidleAfter this many seconds without mouse movement, a key press, scrolling or a touch.Seconds (default 30)
Scrolled down the pagescrollAfter scrolling this share of the page. A page too short to scroll never fires it.Percentage (default 50)
Some time on the pagetimeAfter this many seconds on the page.Seconds (default 30)
A returning visitorreturningFrom the second page load in the same browser on. The widget counts page loads in the browser's storage (pb_visitor_count), so a second page in the same visit already counts.—
Arrived from a campaignutmWhen the address of the page carries utm_campaign with this value.Campaign
Left something in the cartabandoned_cartWhen a cart has held items for this many minutes. It reads the cart state the WordPress plugin keeps in the browser on WooCommerce shops (pitchbar_cart_state), checked every 30 seconds; without the plugin it never fires.Minutes (default 5)

A trigger created before these settings existed uses the defaults; a campaign trigger without a campaign fires on every page load.

What happens when one fires

  • The widget opens the chat on this page and adds the trigger's message as a bubble from the AI employee. A trigger saved without a message uses Hi! Can I help you find anything? in the visitor's language (before card #673 it opened on an empty bubble). Opening it this way is not stored as the visitor's choice, so the chat does not keep opening on later pages.
  • It logs a trigger.fired event with the trigger's id and kind.
  • Each trigger fires at most once per page load, and then waits five minutes in that browser before it can fire again (per trigger, remembered under pb_last_trigger_at:<id>).

The widget receives the triggers from /widget/init when it loads: up to 20 enabled ones, highest priority first. Triggers added on the page are enabled, with priority 0.

How a trigger is stored

Each trigger is a row in behavior_rules:

  • name — what the list shows.
  • kind — one of the seven codes above. The server accepts no other value (BehaviorRuleController).
  • conditions — the one setting: seconds (idle, time), percent (scroll), idle_minutes (abandoned cart) or utm_campaign (campaign).
  • action — {"kind": "open_with_message", "message": "…"}.
  • enabled, priority — see above.
  • cta_rule_id — stored, but the widget does not use it.

Related settings