Settings

Configure the chat widget

Configure the web chat widget appearance, allowed domains, proactive messaging, and tracking so it installs cleanly on your site and emits reliable analytics.

Overview

Configure the Chat Widget settings to control how the embeddable widget looks, where it can load, when it proactively appears, and how its events are tracked.

Prerequisites

You need:

Access to your website codebase or tag manager to add the embed snippet before the closing </body> tag.
DNS or hosting access to confirm the exact domains where the widget should load (for example, app.acme.com, www.acme.com).
Tenant admin or workspace admin permissions to change Settings → Chat Widget.

If you do not add your production domains to Allowed domains, the widget does not load even if the embed snippet is present.

Use the Chat Widget Configuration section to control how the widget looks on your site.

themestring

Required

Visual theme for the widget. Choose Light for light backgrounds or Dark for darker pages and better contrast.

positionstring

Required

Screen corner where the launcher button appears. Options: Bottom right, Bottom left, Top right, Top left.

widgetColorstring

Required

Hex color that controls the launcher button, primary buttons, and key accents in the widget. Use a brand-safe color to match your site.

greetingMessagestring

Required

Text shown when the widget opens for the first time, above the message composer. Use it to set expectations, for example, "Ask anything about your account."

avatarUrlstring

Optional image URL used for the assistant avatar in the conversation view. Use a square image hosted over HTTPS for best rendering.

headerIconUrlstring

Optional icon URL shown in the header next to the widget title or wordmark. Use a transparent PNG or SVG for best results.

headerWordmarkUrlstring

Optional logo or wordmark URL used in the header. This typically displays your brand name or logotype.

Preview how the widget looks on both light and dark pages. If your site has multiple themes, pick the theme and widget color that maintains contrast in the most common environment.

Use the Save widget configuration button to apply appearance changes to new widget loads.

Adjust visual settings

Open Settings → Chat Widget → Configuration.
In Chat Widget Configuration, set Theme, Position, Widget color, and Greeting message.
Optionally add Avatar URL, Header icon URL, and Header wordmark URL.

Preview on your site

Open a page that already has the chat widget embed snippet installed.
Hard refresh the page to bypass cached assets.
Open the widget and confirm the new colors, images, and greeting message render as expected.

Save your changes

Return to Settings → Chat Widget → Configuration.
Click Save widget configuration.
Confirm the saved indicator appears and changes persist after a page refresh.

Allowed domains

Allowed domains restrict where the widget can initialize and connect to your tenant.

If the current page domain is not in Allowed domains, the widget fails to load or connect even if the embed snippet exists. Always add production and staging domains before testing.

Allowed domain fields

domainstring

Required

Hostname where the widget is allowed to run, for example, app.acme.com or help.acme.io. Do not include protocol or path.

workspacestring

Required

Workspace associated with conversations that start from this domain. Each domain routes to exactly one workspace, but you can change it at any time.

statusstring

Read-only active indicator showing whether the most recent health checks and loads for this domain succeeded.

Manage allowed domains

Use the domain input, workspace dropdown, and domain list controls to manage access.

Add an allowed domain

Go to Settings → Chat Widget → Configuration → Allowed domains.
Enter the domain in the add-domain field, for example www.acme.com.
Select the Workspace that should receive new conversations from this domain.
Click Add domain and confirm the new row appears in the list with an active status.

Change a domain workspace

Locate the domain in the list.
Use the workspace dropdown in that row to select the new workspace.
Confirm that new conversations from that domain now appear in the updated workspace.

Remove a domain

Find the domain you want to deauthorize.
Click the Remove or delete icon in the domain row.
Confirm the removal. The widget no longer initializes on that domain after you deploy and reload the page.

The Embed code section lets you generate a widget token and copy the installation snippet for your site.

widgetTokenstring

Required

Unique token that identifies your tenant and configuration. The dashboard generates this when you click Generate token.

Use one widget token per tenant. If you regenerate the token, update the embed snippet everywhere it is installed.

Generate or locate your widget token

Open Settings → Chat Widget → Configuration → Embed code.
Click Generate token if you do not see a token yet.
Note the displayed token and confirm the embed snippet reflects it.

Copy the embed snippet

In the Embed code panel, copy the provided snippet using the Copy button.
The snippet is pre-configured with your widgetToken and tenant endpoint.

Paste before the closing body tag

Open your website layout or template in your code editor or CMS.
Paste the snippet immediately before the closing </body> tag on pages where the widget should appear.
Save and deploy your changes.

<!-- Example: chat widget embed snippet -->
<script>
  (function () {
    window.chatWidget = window.chatWidget || {};
    window.chatWidget.widgetToken = "YOUR_WIDGET_TOKEN";
  })();
</script>
<script src="YOUR_WIDGET_SCRIPT_URL" async></script>

The authoritative embed snippet is always the one shown in the Embed code panel, so copy it directly from there instead of retyping from this example.

Publish and verify

Open your site in a browser at a domain included in Allowed domains.
Confirm the launcher button appears in the configured position.
Click the launcher and verify the greeting message and branding match your configuration.
Repeat for any additional environments (staging, preview) after adding those domains.

Proactive messaging configuration

Proactive messaging automatically opens the widget and shows a message when the visitor matches configured triggers.

Proactive messaging fields

proactiveEnabledboolean

Master toggle that enables or disables proactive messaging. When disabled, no automatic prompts appear, even if triggers are configured.

proactiveMessageTemplatestring

Text template for the proactive message shown when a trigger fires. Write a short, clear invitation to start a conversation.

timeDelaySecondsinteger

Minimum number of seconds after page load before the proactive message can appear.

scrollPercentageinteger

Scroll depth (0–100) required before the proactive message can appear. Use higher values when you only want to engage engaged readers.

idleTimeSecondsinteger

Number of seconds without mouse or keyboard activity required to trigger the message.

exitIntentboolean

Enable detection of exit-intent, such as the cursor moving rapidly toward the browser chrome, to trigger a proactive prompt.

customEventsarray

List of custom event rules. Each rule specifies a type (Hover, Click, or Focus) and a CSS selector that identifies the element that should trigger a proactive message.

showOncePerSessionboolean

Prevent the same visitor from seeing the proactive message more than once per browser session, regardless of how many triggers fire.

Combine a generous time delay with Show only once per session to avoid overwhelming visitors. For example, wait 30–45 seconds and only show the prompt once.

Configure a proactive message

Enable proactive messaging

Go to Settings → Chat Widget → Configuration → Proactive Messaging.
Turn on the Enable proactive messaging toggle.
Enter a concise Message template, for example, "Need help finding the right plan? Chat with us."

Set trigger conditions

Configure one or more triggers:
- Time delay: choose a delay such as 30 seconds.
- Scroll percentage: set 50 or 60 to target engaged readers.
- Idle time: specify a threshold like 20 seconds.
- Exit intent: enable to catch users as they move to close or leave the page.
If you use custom events, define rules such as:
- Type Click with selector .pricing-cta-button
- Type Hover with selector #contact-support-link

// Example: custom event target element
<button class="pricing-cta-button">
  Talk to sales
</button>

Limit frequency

Enable Show only once per session to avoid repeated prompts.
Save the configuration to ensure the session rules apply.

Test triggers

Open a page with the embed snippet in a new incognito window.
Interact with the page to meet your trigger conditions (for example, scroll past 60 percent).
Confirm the widget opens with your proactive message and only appears once per session.
Repeat for custom event elements and exit-intent behavior.

Tracking health overview

The Tracking tab helps you monitor whether widget events are emitted, delivered to your webhooks, and accepted by downstream analytics tools.

Use the Configuration tab to control how the widget looks and behaves, and the Tracking tab to confirm that data from those interactions is flowing correctly.

Tracking health metrics and controls

The Tracking health panel shows status over a selected time window.

timeWindowstring

Required

Time range selector for the health view. Options typically include Last 1 hour, Last 24 hours, and Last 7 days.

statusBadgestring

High-level status indicator. Healthy means webhook failures are within acceptable thresholds; Warning indicates elevated failure rates or recent errors.

emittedEventsinteger

Total number of widget events emitted in the selected time window, such as widget_opened or message_sent.

webhookAttemptsinteger

Total number of webhook delivery attempts for tracking and analytics destinations.

webhookFailRatenumber

Percentage of webhook attempts that failed (HTTP error, timeout, or network issue). High values indicate downstream problems.

lastEventstring

Timestamp and type of the most recent event, which helps confirm that events are still flowing in real time.

In addition, the Tracking tab shows:

A breakdown by event type and time series so you can see volume trends.
A Recent failures table that lists webhook targets, status codes, failure reasons, and timestamps.

Validate tracking health

Select a time window

Open Settings → Chat Widget → Tracking → Tracking health.
Choose Last 1 hour when testing a recent change or Last 24 hours for daily trends.
Click Refresh to reload metrics for the selected window.

Confirm overall status

Review the Status badge:
- Healthy suggests events are flowing and webhooks are being delivered.
- Warning signals a spike in failures or missing events.
Compare Emitted events with expected traffic for your site.

Inspect event types and series

Use the By event type table to confirm that canonical events such as widget_opened and message_sent appear.
Check the time series chart for unexpected drops, especially around recent deployments.
Note which event types show the largest share of failures, if any.

Review recent failures

Scroll to the Recent failures table.
For each failed delivery, note the endpoint, status code (for example, 500 or 404), and error message.
Use these details to debug your webhook handler or analytics endpoint.

Tracking code and analytics providers

The Tracking code section helps you connect widget events to your analytics stack using a guided snippet builder and provider-specific templates.

guidedSnippetBuilderobject

Interactive tool that lets you select providers, events, and destinations, then generates a combined snippet tailored to your setup.

templatesarray

Collection of prebuilt snippets for common providers, including GA4 gtag, Meta Pixel, and a generic dataLayer pattern.

canonicalEventsarray

Standardized event names exposed to tracking code, such as widget_opened, widget_closed, message_sent, and conversation_resolved.

When to use the guided snippet builder

Use the Guided snippet builder when:

You are setting up tracking for the first time.
You need to send events to more than one provider in a single handler.
You want a single combined snippet you can paste into your tag manager or site code.

The builder lets you:

Choose providers (GA4 gtag, Meta Pixel, dataLayer).
Pick which canonical events to forward.
Copy a combined snippet that wires up all selected providers with one click.

When to use templates

Use the Templates section when:

You already have a tracking architecture and want to integrate widget events into it.
You prefer to manage provider logic yourself.
You want a reference implementation for one specific provider.

Templates typically include:

A callback that receives widget events.
Provider-specific calls using canonical events.

// Example: forwarding widget events to GA4 with gtag
window.chatWidget = window.chatWidget || {};
window.chatWidget.onEvent = function (event) {
  if (event.name === "widget_opened") {
    gtag("event", "widget_opened", { widget_location: event.context.position });
  }

  if (event.name === "message_sent") {
    gtag("event", "widget_message_sent", {
      message_length: event.payload.text.length,
      channel: "web_chat",
    });
  }
};

Troubleshooting tracking and health

Widget appears but no events in Tracking

Confirm the page includes the latest widget script and not a cached or self-hosted copy.
Open Settings → Chat Widget → Tracking → Tracking health and set Last 1 hour.
Interact with the widget (open, send a message) and click Refresh.
If Emitted events remains at 0, check the browser console for JavaScript errors.

High webhook fail rate

In Tracking health, open Recent failures.
Identify recurring status codes:
- 4xx errors usually point to authentication, URL, or payload validation issues in your endpoint.
- 5xx errors indicate your endpoint is failing or overloaded.
Test your webhook endpoint independently (for example, with a test POST request) using a sample widget event.
Fix the underlying issue, then monitor Webhook fail rate until it returns to a normal baseline.

Analytics platform missing events

Open your tracking code or tag manager implementation and verify that widget events are being forwarded using canonical names such as widget_opened and message_sent.
Compare the code to the relevant provider template or the generated snippet from the Guided snippet builder.
Use your analytics provider"s real-time or debug view to confirm events arrive when you interact with the widget.
Ensure ad blockers or script blockers are not blocking the provider"s script on your test environment.

General troubleshooting

Use these checks if the widget does not show up or behaves unexpectedly.

Widget not appearing at all

Confirm you installed the embed snippet before the closing </body> tag on the page you are testing.
Verify the snippet uses a valid widgetToken from Settings → Chat Widget → Configuration → Embed code.
Check the browser console for network errors loading widget.js or CORS issues.

Widget blocked on certain domains

Go to Settings → Chat Widget → Configuration → Allowed domains.
Confirm the exact hostname you are testing (for example, staging.acme.com) appears in the list.
Add the domain and assign the correct workspace if it is missing, then reload the page.
If you recently updated DNS, allow time for propagation before re-testing.

Appearance changes not reflected

Ensure you clicked Save widget configuration after editing appearance or proactive messaging settings.
Hard refresh your browser (Shift + reload) or clear cache to bypass stale assets.
If you use a CDN, purge the cache for the page or script where the widget loads.

Was this page helpful?

Last updated today

Built with Documentation.AI

Configure the chat widget

Overview

Prerequisites

Chat widget appearance fields

Save widget configuration

Allowed domains

Allowed domain fields

Manage allowed domains

Generate embed token and install the widget

Proactive messaging configuration

Proactive messaging fields

Configure a proactive message

Tracking health overview

Tracking health metrics and controls

Validate tracking health

Tracking code and analytics providers

When to use the guided snippet builder

When to use templates

Troubleshooting tracking and health

General troubleshooting