Widget configuration

Customize the AI Chat Widget for your brand, launch behavior, visitor flow, prompts, session rules, and advanced website use cases.

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.

Configure Widget v5

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?

Decide on the widget brand, copy, colors, launcher visuals, and deeper styling.

How should the widget open?

Decide between the default floating launcher, inline embed, open-by-default behavior, and delayed 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.

Match The Widget To Your Brand

Bot and human identity

1. Set the AI identity visitors should see

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

2. Set the default human-support appearance

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

3. 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',
     },
   };
   

Logos and launcher visuals

1. Decide what brand visuals should appear

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

2. Start with the welcome logo

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

3. Add the assets object

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

Theme, language, and copy

1. Use theme for color and layout

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

2. Use text settings for wording

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

3. 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 cssOverrides for deeper styling. This is the right option when you need to target specific widget parts with custom CSS.

Choose How The Widget Opens

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 oneOpenSessionAllowed, router.goToChatIfNoSessions, router.chatScreenOnly, and headerButtons. For the user-facing effect of those settings, see Conversation Sessions.

Shape The First-Visit Experience

Welcome messages

1. Choose the opening message style

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

2. Use advanced messages only when needed

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

3. 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?'],
};

Suggested questions

1. List the most common starting intents

   Use initialQuestions for the first few things visitors usually ask.

2. Choose the position

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

3. Keep the list short

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

4. 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.

Helpful prompt

1. Turn on the prompt

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

2. Use it after self-serve answers

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

3. 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 collectUserData for the built-in form, prefillUserData when your site already knows the visitor’s name or email, and extraDataCollectionFields only for the extra fields you truly need.

Attach Context Without Changing The AI Prompt

AI context

1. Use context for runtime information

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

2. 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.

3. Add the context object

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

Human-only message data

1. Use messageCustomData for per-message notes

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

2. Use it for operational metadata

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

3. Add the message metadata

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

Session-level notes

1. Use sessionCustomData when the session starts

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

2. Keep it tied to the session itself

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

3. 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:

• headers
• queryParams
• bodyProperties

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 modesComponents 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.

Use custom components

Use custom components when the AI stays in a normal chat thread but one action result should render as richer UI.

Good fit

Order summaries, balance cards, booking confirmations, and status views.

Where to continue

Use the custom components guides for the React and headless implementations.

Choose this when you are rendering a result inside the conversation, not taking over the conversation flow.

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

Register action-specific UI in the default React widget.

Headless

Build fully custom rendering with the headless widget packages.

Mobile Support

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