Outreach rules

The Proactive outreach field group decides when the chat window addresses visitors to your website on its own, with a single sentence: after some time on the page, once a share of the page has been read, after a standstill, when the pointer leaves the page or on a second visit. This page covers every field, limit and message, and explains how the speech bubble behaves on your site.

Where to set up rules

1. 1

   Step 1

   Open Assistants

   In the app, go to Work › Assistants at app.xicbot.de/assistenten.

2. 2

   Step 2

   Expand the assistant

   Choose Edit next to the assistant you want. With the Read role the button says View instead and the fields stay locked. Close folds the assistant up again.

3. 3

   Step 3

   Find the field group

   The Chat window on your website section contains the Proactive outreach field group. Below the rules and the Add rule button there is a help text, and at its end a counter shows how many rules there are, for example 0/5.

4. 4

   Step 4

   Add a rule

   Add rule puts a new row at the bottom. Pick the event, enter a number and a path where needed, and write the sentence.

5. 5

   Step 5

   Save

   Save submits the entire chat window form. The button reads Saving … while it is sending, and afterwards you see “Saved.”

The fields of a rule

Each field in a row has its label above it: Event, Value, Only on path and Sentence of the prompt. The unit, Seconds or Percent, follows the number field. Screen readers announce the number field with its label and unit, such as “Value Seconds”.

Add rule is shown while there are fewer than five rules. Underneath you read “One event and one sentence per rule. The first rule that applies speaks; after that the widget stays quiet for this visit. Without a rule nothing appears unasked.” followed by the counter, for example 2/5. In practice “visit” here means a single page view. New rules go to the end of the list, and rules cannot be moved.

The five events

When the clock starts

The chat window only loads after the page itself has finished loading. Once it has received its settings from the server, the rules are armed, and that is when the clocks for After time on the page and After a standstill start. The page's own loading time is not included. Scrolling and the mouse wheel do not count as a standstill, because someone who is reading is not idle.

How the share read is measured

The measure is how far down the page the bottom edge of the visible area reaches, rounded to whole percent. At the top of a page three times the height of the window that is already 33 percent, so a rule set to 30 percent fires straight away. A page no taller than the window counts as read to the end. The check runs when the rules are armed, whenever the visitor scrolls and when the window is resized.

On a second visit

For On a second visit the widget keeps a marker in the browser. All it records is “has been here before”; it carries no identifier.

• Name in local storage: xicbot.besuch.<key>, valid for 90 days.
• Every time the rule is armed it reads the marker and writes it again, so the 90 days start over.
• The rule fires if the marker was already there. That is the case from the very next page view, even within the same session.
• The marker is only written on pages whose path matches the rule.
• If the browser does not allow storage, the rule does not fire.
• <key> is the value of the data-xicbot attribute in the embed code. With a different key, counting starts over.

Which rule speaks

• Rules are armed in the order they appear in the form, up to five. Rules without a sentence and rules whose path does not match are skipped.
• The rule whose event happens first speaks, and every other rule is switched off at that moment.
• If several rules already apply at the moment of arming – a second visit, say, or a low share on a short page – the one highest in the form wins.
• The lock lasts for one page view. On the next page of the same site the rules are armed again from scratch.

Path filter

Only on path looks at the start of the page path, leaving out the domain, query string and fragment. Upper and lower case matter. With the field left empty the rule applies on every page that embeds the widget.

The speech bubble

The speech bubble appears where the chat window opens: in the same corner as the chat button, 12 pixels above it, or 12 pixels below it if the button sits at the top. When the button moves aside for a fixed bar on the page, the bubble moves with it. It is at most 320 pixels wide – on narrow screens at most the window width minus 32 pixels – with a white background, dark 15-pixel text and rounded corners.

• The sentence itself is a button at least 48 pixels tall. Clicking it opens the chat window.
• The cross beside it, 44 pixels wide, dismisses the bubble. Screen readers announce it as “Dismiss message” when the chat window is in English, otherwise as “Hinweis schließen”. The rules stay off for the rest of that page view.

The bubble has the status role, so screen readers announce the sentence without moving focus. It is rendered as plain text, meaning asterisks, links or HTML show up exactly as typed. There is no translation, so if your site has an English version, give it its own rule with a matching path such as /en/.

When the button steps back behind an overlay that covers nearly the whole window (80 percent of its height or more), the bubble is hidden too. Details are in Appearance and accessibility.

When no bubble appears

• No rule has a sentence, or no path matches the page being viewed.
• The visitor has already opened the chat window on this page. From that point outreach stays off for the page view.
• The script carries data-einwilligung="erforderlich" and the visitor has not yet agreed through window.xicbot.einwilligen(). See Consent and visitor rights.
• The assistant's status is Draft or paused rather than active, Enable chat window is switched off, or the account is not active. The widget then also takes its button off the page.
• The assistant has no active version yet. No rule is armed then. The button stays on the page, and the opened chat window shows “This assistant is not ready yet.”
• The chat window has not yet received its settings from the server, for example without a network connection. Until then no rule is armed.
• window.xicbot.widerrufen() has been called. Revoking takes the rules and any bubble off the page at once. Outreach then stays off until the next page view, even if your page calls einwilligen() again.

Saving and when changes apply

Before sending, the form tidies up: rules without a sentence are dropped, leading and trailing spaces are trimmed from path and sentence, and the number is pulled into the event's range. When leaving the page and On a second visit are sent with the value 0. The server checks the list once more, keeps only ereignis, wert, pfad and text for each rule, and stores an empty list as “no rules”.

Visitors pick up new rules on their next page view. On a page that is already open, the widget only checks for changes when the chat window is opened or the visitor returns to the browser tab, at most once a minute, and even then it takes over the display alone: heading, colour, corner, distances, width, height, scale, corner radius and image, plus the notice below the heading and the limits notice. The rules only apply there after a reload.

Messages when saving

If the server rejects a rule, a sentence at the end of the Proactive outreach field group gives the reason: for outreach_rule_path it reads “The path of a rule must start with “/” and be no longer than 120 characters, for example /contact.”, for any other code it reads “A proactive outreach rule is not valid. Check the event, value, path and sentence of each rule.” The app does not say which row is affected. If the server also rejects a field that the app does not mark, the message on saving is “That did not work. Please check your entries.” The API response lists one of the following codes under widget_outreach_rules. Checking stops at the first problem it finds.

Roles

With Read, the form in the Chat window on your website section is locked, Save included. See Team and roles for more.

API

Rules live on the assistant in the widget_outreach_rules field and are read and changed along with it. Responses return them under widget.outreach_rules. If an update leaves the field out, the rules stay untouched; null or [] deletes them. For the API in general, see API: knowledge and assistants and API limits.

{
  "widget_outreach_rules": [
    { "ereignis": "tiefe", "wert": 60, "pfad": "/pricing", "text": "Questions about the plans? Happy to help." },
    { "ereignis": "ausstieg", "wert": 0, "pfad": "", "text": "Before you go: anything I can answer?" },
    { "ereignis": "zeit", "wert": 45, "pfad": "", "text": "Looking for something in particular?" }
  ]
}

In this example the first rule speaks on /pricing once 60 percent has been read, unless the pointer leaves the page or 45 seconds pass first. On every other page it comes down to leaving and time.

Further reading

• Widget settings: title, colour, position and size of the chat window
• Embed the widget
• Script attributes, including data-einwilligung
• JavaScript and storage
• Consent and visitor rights
• Appearance and accessibility
• Chat in the widget
• Widget delivery

Frequent questions