Rules engine for Chat (new)

The Puzzel Chat platform features a powerful rules engine that controls under which circumstances specific interaction journeys should start for a website visitor.

The most basic setup is one rule that matches any URL, and has an outcome configured to always trigger a generic start interaction panel.

More complex setups can have multiple rules, each with multiple conditions of different types, and outcomes that decides what should happen when a rule triggers, also taking into account time of day, number of available agents, etc.

Overview

Every chat configuration has a list of Rules that is evaluated on page load or hash change.
Each rule consists of one or more Rulesets.
Each ruleset consists of one or more Conditions.
Each condition is a logical operation that evaluates to either true or false.
There are a number of different types of conditions.
A ruleset evaluates to true if all conditions in are true.
The whole rule evaluates to true if one or more ruleset is true.

I.e. when rules are evaluated, the evaluation priority is:
The rule is true if: “Ruleset 1=true” OR “Ruleset 2=true” OR “Ruleset 3=true”, etc.
And a ruleset is true if: “Condition 1=true” AND “Condition 2=true” AND “Condition 3=true”, etc.

If a rule evaluates to false, the next rule in the rules list is evaluated.
If a rule evaluates to true, further evaluation stops by default (see next section for other options).
When a rule evaluates to true, its Outcome is triggered and evaluated.
I.e. only the first matching rule in the rules list will trigger by default.

Example: A common setup is to create a rule with a ruleset matching URL pattern “/” (which will trigger on any URL), with an outcome that launches a generic interaction, and place this rule in the bottom of the rules list as a default fallback. And then add more specific rules above it.
E.g. a rule matching URLs containing “/sales” may be placed first, and if it matches, its outcome triggers an interaction-chain with a “Chat Queue Key” to agents in the sales department.
The default fallback rule in the bottom is only evaluated if no rule above it matches.

A rule’s Outcome settings determine what happens when the rule matches.

Fig 1. The ruleset configuration of “First rule” will match if either:
Current URL contains “/mobile-test” AND the visitor’s device type is “Mobile”,
OR the URL contains “#testingtesting” AND the visitor stays over 30 seconds on the page.

Fig 2. The outcome of “First rule” will trigger an interaction-chain in “Swedish”, starting with interaction “Panel #1”, and any chat started later in the chain will use Chat Queue Key “Chat 9”.

Rule list and order of evaluation

The rules list in a configuration is automatically evaluated on every page load, and on URL hash changes (for singe-page-apps). In some complex setups, some rules will also be monitored and evaluated continously as long as the visitor stays on a page (rule containing condition types “Time” and “Custom” described later in this document).

The default evaluation behaviour is that the rules list is evaluated from top to bottom, and when a matching rule is reached, further evaluation is stopped. Since the order of rules are important, it is possible to re-order the rules list by dragging each rule up/down by its ☰ icon.

However, the default ordered rule evaluation (and “trigger first match only”) may sometimes be a bit limiting, and there are situations where multiple interactions and interaction-chains should be allowed to launch simultaneously.

This can be achieved by enabling the option “Always evaluate this rule” (see Fig 1 above). All rules with this option enabled will always be evaluated, independently of any other rules that may or may not match at the same time.

Note: When a rule’s outcome is set to trigger some specific interaction types as the first interaction in an interaction chain/journey, the option may be disabled and its value is locked.

Fig 3. When a rule’s outcome is set to trigger an interaction of type “Detect Visitor Login”,
the option “Always evaluate this rule” is automatically enabled and it can’t be changed.
This type of interaction needs to always evaluate, is invisible, and it should not block other rules.

Another situation where “Always evaluate this rule” can be useful is when an injected interaction of type “Information panel” should be rendered in the DOM on some pages, and at the same time panel with a trigger button offering chat support may be rendered during office hours. Enabling “Always evaluate this rule” for the rule triggering the injected interaction will make it independent of any other rules, which is probably the desired behaviour.

Conditions and condition types

To allow fine-grained control over the visitor experience and “what should happen when” for the visitor, the Web Engage Rules Engine offers different types of Conditions for rule evaluation.

The most common type of condition is URL with criteria: “Current page”, operation: “Contains” and value: <string>.
Such condition will evaluate true if the current URL contains <string>, and it's used to launch specific interaction-chains when the visitor navigates to specific pages or sections of the website.

But sometimes it is useful to trigger interactions and interaction-chains based on more complex contitions than the current URL.

The Web Engage Rules Engine currently offers these condition types:

• URL, for analysing and matching current and previous navigations

• DOM, for looking for specific content in the DOM of the current page

• Device type, for conditions depending on mobile/desktop visitor

• Time, for triggering interactions depending on time on the site or current page

• Static, skip analysis and always/never trigger automatically

• Login, for conditions based on login status (for use with “Secure visitor identification”)

• Custom, for custom implementations of the condition logic

  
  The different types has the following options:

Detailed description of condition types

URL

URL-condition is the most common type. Use it to analyse and match the URL the visitor is currently visiting, or coming from (maximum two steps back in the navigation history).

On a basic, straightforward setup, this may be the only rule/condition needed to set up Web Engage.

The URL is analysed on page load

Examples:

This rule will always match (same effect as type “Static” + “Always match”)

Match all pages except URLs containing “&page_type=demopage”

Match when visitor navigates to an error-page, coming from a checkout-page.

DOM

A DOM-condition is used to analyse the content of the page the visitor is currently visiting. To set up a DOM-condition, a CSS-selector string should be entered as “Criteria”, and for some operators also a “Value” string.

Note: For SPAs and other sites with dynamic content (where the DOM changes during a page visit), a DOM-condition may fail to pick up the state of the DOM if it changes after rules evaluation (in those cases, a “Custom”-condition may be needed instead).

Examples:

This condition will match when a Button-element with id=”logout-btn” exists in the DOM and is visible. This could be one method of detecting if a visitor is currently logged in and a “Logout”-button is presented somewhere on the page.

Match pages containing an element with class=”heading” and content “Support”

Device type

Use “Device type” to specifically target mobile or desktop visitors

Note: Device type detection is based on the “User-Agent” string reported by the visitor’s browser, and detection may not be 100 % accurate. Common devices should be correctly detected though.

Example:

This condition will only match visitors currently using a mobile device

Time

Time-conditions can be used to trigger an outcome after/before a specified time on the current page or on the site (since visitor’s the session was created).

Note: Time-conditions will be continously monitored and may trigger asynchronously (unlike regular condition types that are only evaluated on URL-changes or when evaluation is explicitly triggered via the api). The implication of asynchronous conditions is that the strict order/priority in the rules list may be overridden. For normal rules (with “Always evaluate” = false) only one rule’s outcome may be triggered and presented at any given time, and if only a low-priority rule (i.e. in the bottom of the rules list) has matched at page load time and is currently activated, a high-priority Time-rule (higher up in the list) matching later will be supressed. I.e. an already visible interaction will not be removed/changed if another rule suddenly matches, and the rules engine does not allow more than one regular rule being displayed at the same time. An exception is rules with “Always evaluate” = true, which are independent of other rules, and active interaction chains currently displaying a sticky interaction (like a chat or a post-chat survey) are also allowed to co-exist with other rules/interaction chains.

Examples:

This condition will start matching when a visitor has been on a page for more than 60 seconds

This condition will match when the visitor’s session is no more than 60 seconds old. I.e. it will only match during the first minute a visitor is visiting the website, and then stop matching.

Static

A Static condition is not performing any analysis. It can be set to “Always match” or “Never match”. “Always match” can be used as a fallback rule in the bottom of the rules list when no rule with higher priority matches. A condition set to “Never match” will always be false when evaluated by the Web Engage rules engine. Such conditions can still be useful in rules created to only be triggered manually via the api. Triggering a specific rule from the api, instead of triggering a specific interaction, is sometimes preferred, because when triggering a rule, the rule’s outcome will still be evaluated (i.e. different things may happen depending on time-of-day or queue status)

Example:

This condition will always evaluate to true

Login

A “Login”-condition can be used in combination with “Secure visitor identification” and interactions of type “Detect visitor login” (see separate documentation for “Visitor identification”).

Example:

This condition will match if/when the visitor has previously been detected as “Logged in” by a “Detect visitor login”-interaction.

Custom

“Custom”-conditions can be used for more complex evaluations when none of the built-in types described above works.

The operator of a Custom condition is “Evaluates true” or “Evaluates false”, and the value is a string with the name of a function or a variable in the global scope of the webpage or defined under the browser’s “window” object. The value-string can also be an object path in dot-notation relative the global browser scope.
E.g. value api.somepath.myCustomFunction would try to resolve a function of variable under:

api: {
   somepath: {
      myCustomFunction: () => { /* run logic and return true/false */ }
   }
}

The actual function/variable needs to be implemented/set by the customer on every webpage the rule is relevant. It needs to be exposed in the webpage’s global scope, and it is expected to return true or false (or some “truthy”/”falsy” value). It name refers to a variable, it will be directly evaluated interpreted as “truthy”/”falsy”.

A “Custom”-condition is asynchronous like “Time”-conditions, and its rule’s state may switch between “matching” and “not matching” at any time. See the description for “Time”-conditions above for how this is handled in combination with regular rules.

Note: The custom function will be called continously, once every second, by the evaluation engine, so it must not contain any heavy computations or REST-calls, etc.

Example:

This function is implemented by the customer on a webpage injecting the Puzzel script:

 

 

window.visitorIsVIP = () => {
	const cartValue = Number(localStorage.getItem('total_sum') || 0);
	if (cartValue > 1000) {
		return true;
	}
	return false;
}

Will match if the value of localStorage-key “total_sum” in the visitor’s browser is >1000

Open image-20250612-122121.png