Configure the Chat Widget

Each web chat configuration controls where one version of the widget appears and how it looks and behaves. A business can have multiple configurations—for example, one for the main storefront and another for a regional subdomain.

Configure them in Settings → Channels → Web Chat. Choose a configuration from the menu at the top of the page, or select Add New Configuration to create one.

Deployment and visibility

The Deployment section decides which pages load the widget.

Every hostname needs its own deployment entry. Different paths on the same hostname can be assigned to different configurations with non-overlapping regular expressions.

Each query condition contains parameter, operator, and value. Use equals for an exact decoded value, matches for a regular expression against the decoded value, or exists to require the parameter regardless of its value. Set value to null for exists. Repeated parameters match when any value satisfies the condition. Deployments without query conditions retain the existing domain-and-path-only behavior.

You can also configure a support-hours schedule with supportHours. Outside the configured intervals the widget is hidden. Set it to null to disable the schedule:

{
  "timezone": "Europe/London",
  "Monday": [{ "open": "09:00", "close": "17:30" }],
  "Tuesday": [{ "open": "09:00", "close": "17:30" }]
}

Omit a weekday to keep the widget hidden for that entire day. Times use the configured IANA timezone and a 24-hour clock.

Appearance

Most size and spacing values are CSS values, such as 20px, 3rem, or 64px. Colors accept CSS color strings; hexadecimal colors are the simplest choice.

Set only one of positionLeft and positionRight, and only one of mobilePositionLeft and mobilePositionRight; set the unused side to null.

Image uploads are managed in the dashboard. MCP returns image file IDs and public URLs when reading a configuration, but the general update tool does not accept image IDs.

Conversation start

Greetings

greetings controls the opening message. Each entry contains:

• content: the greeting text.
• pathRegex: an optional pathname regular expression. Null is a fallback that matches any page.
• priority: a non-negative number. Higher priority entries are evaluated first, and the first matching greeting wins.

Keep one null-path greeting at the lowest priority when you want a default.

Suggested replies

firstMessageSuggestions displays buttons before the visitor's first message. Each entry has displayText, the messageText sent when clicked, and an optional pathRegex.

secondMessageSuggestions can add a second choice after a first suggestion. Each entry contains messageText and an optional firstMessagesAllowed array. Values in firstMessagesAllowed must match the first suggestion's message text, not its display label.

Passing either array through MCP replaces the complete existing array. Read the configuration first when modifying only one suggestion.

Data collection, terms, and text

Attention grabbers

Attention grabbers invite a visitor to start a conversation before they open the widget.

• The intro pop-up uses enableAttentionGrabberIntroMessage, attentionGrabberName, and attentionGrabberMessage.
• Manual suggestion buttons use enableManualAttentionGrabbers, manualAttentionGrabberPathRegex, and attentionGrabberSuggestions (displayText is shown; message is sent).
• Product-aware suggestions use enableAiGeneratedAttentionGrabbers, aiGeneratedAttentionGrabberPrompt, and aiGeneratedAttentionGrabberPathRegex. Products must be available for the business.
• Appearance and timing use the four attentionGrabberSuggestionBubble*Color fields, attentionGrabberDelay, enableAttentionGrabberMobile, enableAttentionGrabberLabel, hideAttentionGrabberIcon, and altAttentionGrabberStyle.

enableAttentionGrabbers is the legacy master flag. For new configurations, use the manual and AI-specific enable flags.

Live chat

Enable human handoff with enableLiveChat. You can also configure:

• liveChatResponseTime: expected response time shown to the visitor, in minutes.
• liveChatTimeout: maximum wait before the live chat is closed and moved to email follow-up, in minutes.
• liveChatUseAgentInitialsAsIcon: show each agent's initials instead of a shared uploaded icon.

The uploaded live-chat agent icon is managed in the dashboard. See Live Chat for routing, assignment, and availability behavior.

Advanced behavior

These settings are available through MCP even when they are not shown in the main dashboard form:

Interaction buttons and virtual try-on are linked to web chat but have dedicated configuration and MCP tools. See Interaction Buttons and Virtual Try-On.

Manage configurations through MCP

The Octocom MCP exposes six web-chat configuration tools:

All tools require organizationId and businessId; get, update, and delete also require configId. The create tool intentionally starts with defaults—create it first, then update it.

Example update arguments:

{
  "organizationId": "org-id",
  "businessId": "business-id",
  "configId": "config-id",
  "patch": {
    "name": "UK storefront",
    "deployments": [
      {
        "hostname": "example.com",
        "pathRegex": "^/uk(?:/|$)",
        "queryConditions": [
          {
            "parameter": "campaign",
            "operator": "matches",
            "value": "^(summer|autumn)-sale$"
          },
          {
            "parameter": "preview",
            "operator": "exists",
            "value": null
          }
        ],
        "enableDeployment": true
      }
    ],
    "topBarTitle": "Ask us anything",
    "languageOverride": "en",
    "firstMessageSuggestions": [
      {
        "displayText": "Track my order",
        "messageText": "Where is my order?",
        "pathRegex": null
      }
    ]
  }
}

For patch fields, omission means “leave unchanged,” while null clears a nullable value. Arrays are full replacements; pass [] to remove every item. Deletion is permanent and is not covered by configuration version history, so list the configurations and confirm the ID before deleting.

Use test_web_chat_url after changing URL-sensitive behavior. Pass the complete URL, including protocol and query string. Its response reports the selected configuration and selection reason, then breaks down the enabled state, normalized hostname, pathname regular expression, and actual values seen by every query condition for every deployment.

For the selected configuration, resolvedExperience also reports:

• the greeting that would be used, its matching rule, and every other candidate;
• the effective first-message suggestions and whether path-specific or default suggestions won;
• the configured conversation-language rule or business-language fallback;
• URL/query-based auto-open matches and the configured delayed-open value;
• AI, manual, legacy, or intro attention-grabber URL eligibility.

Greeting, suggestion, and language rules continue to match the pathname only; query conditions apply to deployment selection. Browser-dependent decisions such as visitor interaction history, device type, the current open state, embed attributes, support hours, and actual AI-generated content are explicitly listed as unevaluated runtime state. The tool is read-only and evaluates configuration data without requesting the storefront URL.