Widget configuration

Use this page when the widget is already installed and you want it to feel right for your website, support workflow, and visitor journey.

Prefer tinkering to reading? The Playground lets you tweak the most common options live and copy the generated snippet. Need implementation guidance for richer widget UI? Go straight to Custom Components, React Components, or Headless.

For Widget v5, Companion mode covers the floating workspace, sidebar and fullscreen layouts, page context, annotations and mentions. Set displayMode: 'companion' in your widget options to use it; the classic popover remains the default. Choose website capabilities in Channels → Web chat, alongside the live widget preview. Use Settings → Advanced for progress updates, memory and available capabilities such as scheduled follow-ups. The embed’s features options can switch supported capabilities off for one site; setting them to true does not enable an organization-disabled feature. Installing v5 or a coding skill does not turn on streaming for your organization. See the v5 configuration reference for option names, or install a coding skill to help apply them in your app.

Decide what to configure

How should the widget look?

How should the widget open?

What should visitors see first?

Decide what visitors should see first, including welcome copy, suggested questions, and a quick resolution prompt.

What extra data should travel with the conversation?

Decide what AI context, human-only metadata, and action-request data should travel with the conversation.

Bot and human identity
Logos and launcher visuals
Theme, language, and copy

Set the AI identity visitors should see

Use for the AI name and avatar shown in the widget header and AI messages.

Set the default human-support appearance

Use when your team wants a consistent human avatar after handoff.

Apply both in one options object

const options = {
  token: '<WIDGET_TOKEN>',
  bot: {
    name: 'Acme Support',
    avatarUrl: 'https://example.com/acme-bot.png',
  },
  humanAgent: {
    avatarUrl: 'https://example.com/support-team.png',
  },
};

Decide what brand visuals should appear

Use when the widget should look like part of your site instead of a generic chat tool.

Start with the welcome logo

The most common first change is the organization logo on the welcome screen.

Add the assets object

const options = {
  token: '<WIDGET_TOKEN>',
  assets: {
    organizationLogo: 'https://example.com/logo.png',
  },
};

Use theme for color and layout

controls colors, panel sizing, spacing, and other layout-level visuals.

Use text settings for wording

textContent, language, and help the widget match your product vocabulary.

Start with a small configuration first

const options = {
  token: '<WIDGET_TOKEN>',
  language: 'en',
  theme: {
    primaryColor: '#0A0A0A',
  },
};

If the built-in theme options are not enough, use for deeper styling. This is the right option when you need to target specific widget parts with custom CSS.

Floating launcher

Keep chat available across the site without taking permanent page space. See Floating launcher setup.

Inline embed

Place the widget inside a page section, such as a help page, pricing page, or account area. See Inline embed setup.

Open by default

Open the widget on first render for cases like a webview or a dedicated support screen. See Open by default setup.

Open after a delay

Open the widget after time on page when you want a proactive nudge instead of an always-on interruption. See Delayed open setup.

Need to change session behavior too? Use options like , , , and . For the user-facing effect of those settings, see Conversation Sessions.

Shape The First-Visit Experience

Welcome messages
Suggested questions
Helpful prompt

Choose the opening message style

Use when you want a simple welcome message for a new chat.

Use advanced messages only when needed

Switch to when some opening messages should stay visible in the conversation and others should disappear after the first reply.

Keep the opening copy focused

Use the welcome area to set expectations, not to explain every feature of your support flow.

const options = {
  token: '<WIDGET_TOKEN>',
  initialMessages: ['Hi, how can I help today?'],
};

List the most common starting intents

Use for the first few things visitors usually ask.

Choose the position

Use to decide whether they appear above the input or closer to the welcome copy.

Keep the list short

Pick the questions that reduce hesitation and help visitors start quickly.

Require a choice before typing (optional)

Set requireInitialQuestion to true to require a choice before typing. The popover hides the message box; Companion keeps it visible but disabled below the starter pills. Selection sends the first message and enables follow-ups. Leave it off to allow free text from the start.

const options = {
  token: '<WIDGET_TOKEN>',
  initialQuestions: ['Where is my order?', 'Can I change my plan?'],
  requireInitialQuestion: true,
};

Each new or reset session requires a choice. Existing sessions with messages stay editable. Add at least one non-empty question; if the list is empty or contains only whitespace, the message box stays available.

requireInitialQuestion is available in Widget 4.0.63 and Widget 5.0.0. Earlier v5 betas, including beta.10, do not support it. Try it under First visit → Require an initial question in the Playground.

Turn on the prompt

Use when you want the widget to ask whether the latest AI answer solved the issue.

Use it after self-serve answers

This works best when the AI often resolves issues without a human handoff.

Keep the next step clear

Pair it with your handoff setup so visitors who still need help know what happens next.

const options = {
  token: '<WIDGET_TOKEN>',
  thisWasHelpfulOrNot: {
    enabled: true,
  },
};

Need to collect visitor details before chat starts? Use for the built-in form, when your site already knows the visitor’s name or email, and only for the extra fields you truly need.

Attach Context Without Changing The AI Prompt

AI context
Human-only message data
Session-level notes

Use context for runtime information

Use for page-level or runtime details the AI may need on each message.

Keep it focused on what changes the answer

This is the right place for an approved page URL, product ID, or current screen context. Exclude query strings and fragments; if the path contains private information, send an approved route label instead.

Add the context object

const options = {
  token: '<WIDGET_TOKEN>',
  context: {
    page: {
      url: window.location.origin + window.location.pathname,
    },
  },
};

Use messageCustomData for per-message notes

travels with each contact message but is intended for human use, not to guide the AI response.

Use it for operational metadata

Good examples include app version, platform, or support workflow metadata.

Add the message metadata

const options = {
  token: '<WIDGET_TOKEN>',
  messageCustomData: {
    platform: 'WEB',
  },
};

Use sessionCustomData when the session starts

is attached when the session is created and is useful for human operators and filtering.

Keep it tied to the session itself

Good examples include visit IDs, plan tier, workspace ID, or a support-route label.

Add the session metadata

const options = {
  token: '<WIDGET_TOKEN>',
  sessionCustomData: {
    visitId: 'visit_123',
  },
};

Pass Data To AI Actions

If your AI calls your APIs, the widget can send request data with those action calls:

Use these when the action request needs customer-specific or page-specific data. If your main problem is secure API credentials, see General settings.

Advanced UI: Conversation Modes

Use modesComponents
Use custom components

Use when the widget should temporarily switch from normal chat to a guided flow, such as onboarding, qualification, or structured data collection.

Good fit

Multi-step flows, guided forms, and canvas-style experiences.

What you control

The UI shown during the active mode, the submit action, and the exit flow back to the conversation.

Choose this when the widget is driving a flow, not just rendering the result of one action.

Where To Go Next

This page is for choosing the right configuration direction. Use the implementation guides next when you need details:

Custom Components

Decide when richer UI is worth the extra implementation work.

React Components

Headless

Build fully custom rendering with the headless widget packages.

Mobile Support

Configure the widget for iOS, Android, and React Native support screens.

Overview

AI Chat Widget

AI X (Twitter) Support

AI App Review Support

AI WhatsApp Support

AI SMS Support

Phone & Telephony

AI Email Support

AI Actions

Resources

Configure Widget v5

Decide what to configure

Match The Widget To Your Brand

Choose How The Widget Opens

Shape The First-Visit Experience

Attach Context Without Changing The AI Prompt

Pass Data To AI Actions

Advanced UI: Conversation Modes

Good fit

What you control

Good fit

Where to continue

Where To Go Next

Custom Components

React Components

Headless

Mobile Support

​Configure Widget v5

​Decide what to configure

​Match The Widget To Your Brand

​Choose How The Widget Opens

​Shape The First-Visit Experience

​Attach Context Without Changing The AI Prompt

​Pass Data To AI Actions

​Advanced UI: Conversation Modes

Good fit

What you control

Good fit

Where to continue

​Where To Go Next

Custom Components

React Components

Headless

Mobile Support

Configure Widget v5

Decide what to configure

Match The Widget To Your Brand

Choose How The Widget Opens

Shape The First-Visit Experience

Attach Context Without Changing The AI Prompt

Pass Data To AI Actions

Advanced UI: Conversation Modes

Where To Go Next