Chat Widget

Attention Grabbers

Invite visitors to chat before they open the widget: what each attention grabber shows, when it appears, who sees it and how often, configured in the dashboard or through MCP and the REST API.

An attention grabber is a small bubble next to the chat launcher, with an optional message and buttons, that invites a visitor to start a conversation. A web chat configuration holds an ordered list of them. Each one is a rule with four parts:

  • Content: a message, buttons, or buttons written by AI for product pages.
  • Trigger: after a delay on a page, when the visitor is about to leave, or when your page code asks for it.
  • Conditions: which pages, how many pages the visitor has viewed, which devices, and whether the visitor already chats or recently dismissed one.
  • Frequency: how many times per visit, and how long to pause after a dismissal.

For each trigger, the widget shows the first enabled grabber in the list whose conditions all pass. Put specific grabbers (a help-center nudge) above general ones (a site-wide greeting). Only one grabber is on screen at a time, and none appears while the chat is open.

Configure them in Settings → Channels → Web Chat → Attention Grabbers, or ask Copilot. The sender name and button colors are shared by every grabber in the configuration.

Example

Show "Can't find an answer?" once per visit, five seconds after a visitor's third distinct help page, on desktop and mobile, unless they already chat with the bot:

{
  "name": "Help pages",
  "enabled": true,
  "trigger": { "type": "delay", "seconds": 5 },
  "content": {
    "message": "Can't find an answer? I can help you find it faster.",
    "suggestions": [],
    "aiSuggestions": null
  },
  "conditions": {
    "pathRegex": "/help",
    "minPageViews": { "count": 3, "pathRegex": "/help" },
    "devices": ["desktop", "mobile"],
    "hideIfChatStarted": true,
    "hideIfInteractedWithinDays": null
  },
  "frequency": { "maxPerSession": 1, "dismissCooldownMinutes": null }
}

Fields

FieldMeaning
idStable id. Keep it when you update a grabber; omit it for a new one.
nameUnique within the configuration. Page code can show a manual grabber by name.
enabledTurned-off grabbers stay in the list and are skipped.
trigger{ "type": "delay", "seconds": 5 } after each page view that meets the conditions; { "type": "exitIntent" } when a desktop visitor moves the pointer to the top of the window or leaves the tab; { "type": "manual" } (see below).
content.messageBubble text, up to 500 characters, shown with the bot icon and the sender name. null shows buttons only.
content.suggestionsUp to 5 buttons: { "displayText", "messageText" } starts a chat with the message (it defaults to the label); { "displayText", "url" } opens a complete https:// link in a new tab.
content.aiSuggestions{ "prompt": "..." } writes the buttons from the catalog product matching the page URL. Pages without a matching product use suggestions; nothing shows when both are empty. Results are cached per product and prompt.
conditions.pathRegexRegular expression on the current page path. null matches every page.
conditions.minPageViews{ "count": 3, "pathRegex": "/help" } waits until the visitor has viewed that many distinct pages in this visit, the current one included. pathRegex limits which pages count; null counts every page.
conditions.devices["desktop"], ["mobile"] or both. Mobile means a window narrower than 640px or shorter than 440px.
conditions.hideIfChatStartedHide from visitors who already have a chat with the bot on this device.
conditions.hideIfInteractedWithinDaysHide for this many days after the visitor opened the chat or dismissed any grabber. null never hides for that reason.
frequency.maxPerSessionShow at most this many times per visit. null shows it on every eligible page view.
frequency.dismissCooldownMinutesAfter the visitor dismisses this grabber, wait this many minutes before showing it again.

A visit ends after 30 minutes without a page view, as in web analytics. Page-view counts and maxPerSession reset with it.

Conditions are checked when the page loads and again when the delay ends, so a visitor who opens the chat in the meantime doesn't see the grabber.

Storage

minPageViews and maxPerSession need to remember the visit across page loads. When an enabled grabber uses either one, the widget keeps a small record of the visit's page paths and shows in the visitor's browser (octocom-attention-visit:<configId>) before the visitor opens the chat. Without these conditions, attention grabbers store nothing until the visitor interacts. Take this into account when you classify the widget for cookie consent; see Browser Storage and Consent.

Showing a grabber from page code

A grabber with "trigger": { "type": "manual" } appears only when your page asks for it, by id or name:

document.dispatchEvent(
  new CustomEvent("showAttentionGrabberEvent", {
    detail: { type: "SHOW_OCTOCOM_ATTENTION_GRABBER", grabber: "Spring sale" },
  }),
);

From a configuration's custom JavaScript, octocom.showAttentionGrabber("Spring sale") does the same. The grabber's conditions and frequency still apply, and nothing shows over an open chat or another grabber.

Configure through MCP or the REST API

Attention grabbers are the attentionGrabbers array of a web chat configuration:

  • Read it with get_web_chat_config or GET /rest/v1/web-chat-configs/{id}.
  • Change it with update_web_chat_config (patch.attentionGrabbers) or PATCH /rest/v1/web-chat-configs/{id}. The array replaces every existing grabber, so read the configuration first and keep the id of each grabber you are not changing. Omitted parts take defaults: a 5-second delay, every page, all devices, no limits.
  • Check the result with test_web_chat_url. It reports which grabber shows after a page view and on exit intent, and every failed condition of the others. Pass visitor to try other states, for example { "viewedPaths": ["/help/a", "/help/b"], "device": "mobile" }.

The appearance fields (attentionGrabberName, enableAttentionGrabberLabel, hideAttentionGrabberIcon, altAttentionGrabberStyle and the four attentionGrabberSuggestionBubble*Color fields) stay on the configuration. altAttentionGrabberStyle is a compact pill that shows only the message and sends it to the bot when clicked; buttons are not shown in that style.

Retired fields

Until November 2026 a configuration had one set of attention grabber fields: enableAttentionGrabbers, enableAttentionGrabberIntroMessage, attentionGrabberMessage, attentionGrabberSuggestions, attentionGrabberDelay, enableAttentionGrabberMobile, enableManualAttentionGrabbers, manualAttentionGrabberPathRegex, enableAiGeneratedAttentionGrabbers, aiGeneratedAttentionGrabberPrompt, aiGeneratedAttentionGrabberPathRegex, exitIntentEnabled, exitIntentMessage and attentionGrabberIdleDeleteMinutes. Every configuration was converted to grabbers that behave the same way, and writes naming a retired field are refused with a pointer to attentionGrabbers. Converted grabbers keep the old one-week pause after the visitor opens the chat or dismisses a grabber (hideIfInteractedWithinDays: 7). The idle cleanup that deleted conversations whose only message was a grabber button no longer exists.

On this page