Configuration reference

Every option you can pass to the AI Chat Widget — token, branding, identity, chat behavior, context, AI action request data, and custom mode components.

This page lists every option you can pass to the widget. For how to combine these options into a brand, launch flow, or visitor experience, start with Configuration.

Want to try options live and copy a working snippet? Open the Playground.

Defaults shown as undefined mean no value is supplied. Read each option’s behavior: some inherit organization settings, while streaming, personal connections and page permissions require explicit opt-in. Defaults shown as language-specific (e.g. for textContent) come from the active language translation, not a single hard-coded string.

Initialization

token

string · required

Your organization’s widget token. Find it in Channels → AI Chat Widget. The widget will not load without it.

Widget v5 options

These options require v5. See Install Widget for version selection and Companion mode for complete examples.

displayMode

'popover' | 'companion' · default: "popover"

Choose the classic corner popover or the Companion launcher and workspace. Ignored when inline is true. This controls the layout. Streaming requires explicit embed opt-in and organization support, in either layout.

companion

object

Options used with displayMode: 'companion'.

Property	Values / default	Purpose
layouts	['compact', 'sidebar', 'fullscreen']	Available layouts, in picker order. A single layout hides the picker; an empty list restores all three.
defaultLayout	compact or sidebar; defaults to first allowed layout	Initial layout. An excluded value falls back to the first allowed layout.
sidebar.side	auto, left, right; default auto	Edge used for the sidebar. Auto follows the page direction.
sidebar.mode	floating or docked; default floating	Overlay the page or reframe it beside the sidebar.
sidebar.width	400 pixels	Sidebar width.
bubbles	false	Use chat bubbles instead of flat replies.
avatars	Follows bubbles	Show the sender’s avatar beside each reply group, independently of bubble styling. Requires Widget 5.0.0-beta.10 or later.
icon	Image URL	Replace the built-in launcher icon.
pillBackground	Widget primary color	Launcher background.
placeholder	Localized message placeholder	Quick-ask input copy.
pillLabel	Falls back to placeholder	Text beside the resting launcher icon.
quickAskTools	history-only or all; default history-only	Also show attachment and page-mark controls in the quick-ask bar. The expanded panel keeps its full tool row.
contentMaxWidth	48rem	Fullscreen message-column width.
fullscreen.lockScroll	true	Prevent host-page scrolling while fullscreen is open.

Set companion: { bubbles: false, avatars: true } to show avatars with flat replies. These controls apply to Companion; the popover always shows avatars.

compact also accepts maxWidth (440), minWidth (280), minHeight (420), maxHeight (640), viewportHeightRatio (0.65) and borderRadius (20). Dimensions are pixels except the viewport-height ratio.

features

object

Per-embed switches for preamble, inlineUi, dictation, attachments, pageContext, clientTools and pageActions. In Widget 5.0.0, pageContext, clientTools and pageActions each default to off and require explicit true as well as organization permission. Actions require all three and visitor approval. For the other switches, omission leaves the organization setting in charge. false always disables the capability in this embed; true cannot override an organization restriction.

These defaults are enforced by the updated widget. Earlier v5 beta widgets can inherit enabled organization settings when a flag is omitted. Until you upgrade, use explicit features: { pageContext: false, clientTools: false, pageActions: false } to disable page access. Changing organization settings or updating the server alone does not give an older embed the new defaults.

Manage web capabilities in Channels → Web chat and progress updates in Settings → Advanced. attachments: false hides file uploads in this embed; widget versions without this option ignore it. To refuse files for every embed and custom client, turn off File uploads in Web chat settings. Turning off pageContext does not remove host-supplied context from outgoing messages, but the new agent excludes that context and historical page selections from its prompt.

streaming

boolean

Omitted or false uses polling for saved messages, preserving v4 delivery. Set true to opt into streamed replies when the organization supports them. Enabled progress updates can arrive on a poll before the final reply. Changing delivery does not change the agent version or require Companion. A runtime transport change waits for an accepted send and its reply to settle.

streamingFetch

typeof fetch

The fetch used to send and resume streamed replies. Omitted uses the global fetch, which every other widget request uses. In React Native, pass the fetch from expo/fetch; see Stream in React Native. Available from Widget 5.1.0.

presentation

object

Narrow what this embed shows. Organization limits in Channels → Web chat → Reply display apply to live replies, reconnects and history.

Property	Values	Behavior
streaming	boolean	Set false to show complete text while retaining the streaming transport for supported live interactions.
toolActivity	hidden, status, details	Hide activity, show name/status only, or allow inputs and outputs. The organization default is status.
reasoning	boolean	Set false to hide reasoning. The organization default is off.

An embed can show less than the organization allows, never more. Hiding activity does not stop tools from executing. Selectable questions and page highlights retain the data needed for their visible interaction. Polling can return saved progress updates and completed replies; it does not deliver live activity events.

capabilities

object

Set connections: true to opt into personal connection controls and requests; omission or false keeps them off. Signed user/account access and streaming are also required for connection requests.

Declare which interactions your client can render: structuredQuestions, richReplies and pageEffects. Enabling a capability does not enable the organization’s feature.

The standard widget declares its built-in support. A headless client must explicitly declare support after implementing the corresponding renderer or page-effect handler. Custom message or rich-reply renderers must declare their own support. Set an individual capability to false to opt out. Clients without support receive ordinary replies; the agent can still ask clarifying questions in text. The polling transport does not support these structured interactions.

This reference describes Widget 5.0.0. Earlier beta defaults differ; see Migrate to v5 before upgrading a beta integration.

mentions

object

Configure the @ picker using either items (a fixed array) or search (a function returning an array or a promise of one). Use one source, not both.

Each record needs type, id and title, with optional description, icon, iconName and meta. preview defaults to true and shows the selected item’s description when the layout has room. Mentions require page context to be enabled. See mention examples.

Branding

assets

object · default: {}

Brand visuals shown around the chat — organization logo and launcher icons.

Hide properties

organizationLogo · string

Logo shown on the welcome screen.

widgetTrigger · object

Hide properties

openIcon · string

Icon shown on the launcher when the widget is closed.

closeIcon · string

Icon shown on the launcher when the widget is open.

bot

object

Identity of the AI shown in the widget header and AI message bubbles.

Hide properties

name · string · default: "AI Support Agent"

Display name of the AI.

avatarUrl · string

Avatar image URL of the AI.

humanAgent

object

Default appearance applied to every human agent after handoff.

Hide properties

avatarUrl · string

Default avatar image URL used for all human agents.

theme

object

Colors, panel sizing, spacing, and other layout-level visuals.

Hide properties

palette · 'neutral' | 'stone' | 'zinc' | 'slate' · default: "stone"

primaryColor · string · default: "hsl(0, 0%, 0%)"

widgetTrigger · object

Launcher button styling.

Hide properties

zIndex · number · default: 10000000

offset · object

Hide properties

bottom · number (pixels) · default: 20

right · number (pixels)

Defaults to 20 when the host page is ltr, otherwise initial.

left · number (pixels)

Defaults to 20 when the host page is rtl, otherwise initial.

size · object

Hide properties

button · number (pixels) · default: 48

icon · number (pixels) · default: 24

widgetContentContainer · object

Outer container styling for the chat panel.

Hide properties

borderRadius · string · default: "32px"

boxShadow · string · default: "0 0px 100px 0px rgb(0 0 0 / 0.25)"

outline · string · default: "none"

outlineColor · string · default: "hsl(0 0% 50% / .5)"

transitionProperty · string · default: "all"

transitionTimingFunction · string · default: "cubic-bezier(0.16, 1, 0.3, 1)"

transitionDuration · string · default: "800ms"

zIndex · number · default: 10000001

offset · object

Hide properties

side · number (pixels) · default: 10

align · number (pixels) · default: 0

screens · object

Per-screen sizing for the welcome, sessions, and chat panels.

Hide properties

welcome · object

Hide properties

width · string · default: "375px"

minHeight · string · default: "200px"

sessions · object

Hide properties

width · string · default: "450px"

height · string · default: "600px"

chat · object

Hide properties

width · string · default: "525px"

height · string · default: "700px"

withCanvas · object

Sizing applied while the canvas is open (used by modesComponents).

Hide properties

width · string · default: "min(1050px, 100vw)"

height · string · default: "min(800px, 100vh)"

transitionTimingFunction · string · default: "cubic-bezier(0.16, 1, 0.3, 1)"

transitionDuration · string · default: "1000ms"

cssOverrides

string

Custom stylesheet that targets widget parts via data-component selectors. Use when the theme options are not enough.

Inspect the DOM to find selectors like data-component="chat/input_box/root". If a part you need to style does not yet have a selector, contact us and we will add one.

Show available selectors

export type OpenCxComponentNameU =
  | 'ui_lib/btn'
  | 'trigger/btn'

  /* Sessions screen */
  | 'sessions/root'
  | 'sessions/header'
  | 'sessions/new_conversation_btn'

  /* Chat screen */
  | 'chat/root'
  | 'chat/header'
  | 'chat/main/root'
  | 'chat/canvas/root'
  | 'chat/msgs/root'

  /* Agent message */
  | 'chat/agent_msg_group/root'
  | 'chat/agent_msg_group/avatar_and_msgs/root'
  | 'chat/agent_msg_group/avatar_and_msgs/avatar'
  | 'chat/agent_msg_group/avatar_and_msgs/msgs'
  | 'chat/agent_msg_group/root/avatar'
  | 'chat/agent_msg_group/suggestions'
  | 'chat/agent_msg/root'
  | 'chat/agent_msg/msg'

  /* User message */
  | 'chat/user_msg_group/root'
  | 'chat/user_msg_group/avatar/root'
  | 'chat/user_msg/root'
  | 'chat/user_msg/msg'

  /* Chat input */
  | 'chat/input_box/root'
  | 'chat/input_box/inner_root'
  | 'chat/input_box/textarea_and_attachments_container'
  | 'chat/input_box/textarea'
  | 'chat/input_box/attachments_container'

  /* Chat utilities */
  | 'chat/bot_loading/root'
  | 'chat/bot_loading/bouncing_dots_container'
  | 'chat/suggested_reply_btn'
  | 'chat/might_solve_user_issue_suggested_replies_container';

Show example

{
  cssOverrides: `
    * {
      font-family: "Arial", sans-serif;
    }

    [data-component="ui_lib/btn"][data-variant="ghost"]:hover {
      background: rgba(68, 71, 70, 0.08);
    }

    [data-component="chat/agent_msg_group/root/avatar"] {
      border-width: 2px;
      border-color: white;
      display: initial;
    }
    [data-component="chat/agent_msg_group/avatar_and_msgs/avatar"] {
      display: none;
    }
    [data-component="chat/agent_msg_group/suggestions"] {
      padding-left: unset;
    }
  `,
}

language

string · default: "en"

Language code used for built-in widget copy.

Supported codes:

• ar Arabic
• da Danish
• de German
• en English
• es Spanish
• fi Finnish
• fr French
• it Italian
• nl Dutch
• no Norwegian
• pl Polish
• pt Portuguese
• ro Romanian
• sv Swedish
• tr Turkish

Need another language? Contact support or open a pull request.

textContent

object

Override built-in copy on individual screens. Defaults come from the active language.

Hide properties

welcomeScreen · object

Hide properties

title · string

description · string

sessionsScreen · object

Hide properties

headerTitle · string

chatScreen · object

Hide properties

headerTitle · string

translationOverrides

{ [key in Language]?: Partial<TranslationInterface> } · default: {}

Override individual translation strings per language. See language for the list of supported codes.

Show TranslationInterface

export type TranslationInterface = {
  i_need_more_help: string;
  this_was_helpful: string;
  write_a_message_placeholder: string;
  your_issue_has_been_resolved: string;
  new_conversation: string;
  back_to_conversations: string;
  closed_conversations: string;
  no_conversations_yet: string;
  welcome_screen_title: string;
  welcome_screen_description: string;
  your_name_placeholder: string;
  your_email_placeholder: string;
  optional: string;
  start_chat_button: string;
  start_chat_button_loading: string;
};

Show example

{
  translationOverrides: {
    en: {
      i_need_more_help: `This didn't answer my question`,
      this_was_helpful: `It's all good!`,
    },
    ar: {
      start_chat_button: 'يلا ندردش',
    },
  },
}

timestamps

object · default: {}

Display timestamps in the conversation.

Hide properties

perMessageGroup · object

Hide properties

enabled · boolean · default: false

Show a timestamp at the top of each message group.

disableTooltips

boolean · default: false

Disable the in-widget hover tooltips on UI controls (e.g. header buttons). Has no effect on documentation tooltips.

inline

boolean · default: false

Embed the widget inside its parent element instead of floating over the page.

When true, the widget content fills its parent container, the widget stays open, and the launcher button is hidden. Useful when you want a chat panel built into a page section.

headerButtons

{ sessionsScreen?: Array<HeaderButton>; chatScreen?: Array<HeaderButton> } · default: {}

Custom header buttons for the sessions and chat screens — expand-shrink the widget, close it, resolve the session, and so on.

Setting this option removes the default close-widget button on small screens. Add a close-widget entry yourself if you still need one.

Show HeaderButton

type IconNameU =
  | 'Maximize'
  | 'Maximize2'
  | 'Minimize'
  | 'Minimize2'
  | 'Expand'
  | 'Shrink'
  | 'X'
  | 'SquareX'
  | 'CircleX'
  | 'Check'
  | 'CheckCheck'
  | 'CircleCheck'
  | 'CircleCheckBig'
  | 'SquareCheck'
  | 'SquareCheckBig';

type HeaderButtonBase = {
  icon?: IconNameU;
  hideOnSmallScreen?: boolean;
  hideOnLargeScreen?: boolean;
};

type HeaderButton =
  | (HeaderButtonBase & {
      functionality: 'expand-shrink';
      /** Overridden by HeaderButtonBase.icon if set. */
      expandIcon?: IconNameU;
      /** Overridden by HeaderButtonBase.icon if set. */
      shrinkIcon?: IconNameU;
    })
  | (HeaderButtonBase & {
      functionality: 'close-widget';
      /**
       * Side effect run on click. Overrides the default close behavior —
       * useful when the widget's open/closed state is controlled externally.
       */
      handleClick?: () => void;
    })
  | (HeaderButtonBase & {
      functionality: 'resolve-session';
      /** What happens after the session is resolved. @default 'stay-in-chat' */
      onResolved?:
        | 'stay-in-chat'
        | 'reset-chat'
        | 'close-widget'
        | 'reset-chat-and-close-widget';
      /** Optional confirmation dialog before resolving. */
      confirmation?: {
        type: 'modal';
        title?: string;
        description?: string;
        confirmButtonText?: string;
        cancelButtonText?: string;
      };
      /** Behavior before the session is created. @default 'disabled' */
      behaviorBeforeSessionCreation?: 'disabled' | 'close-widget';
      /** Behavior after the session is resolved. @default 'disabled' */
      behaviorIfSessionIsResolved?:
        | 'disabled'
        | 'reset-chat'
        | 'close-widget'
        | 'reset-chat-and-close-widget';
    });

Show expand-shrink example

{
  headerButtons: {
    sessionsScreen: [
      {
        functionality: 'expand-shrink',
        expandIcon: 'Expand',
        shrinkIcon: 'Shrink',
      },
    ],
    chatScreen: [
      {
        functionality: 'expand-shrink',
        expandIcon: 'Expand',
        shrinkIcon: 'Shrink',
      },
    ],
  },
}

Show resolve-session example

{
  headerButtons: {
    chatScreen: [
      {
        functionality: 'resolve-session',
        icon: 'X',
        behaviorBeforeSessionCreation: 'close-widget',
        behaviorIfSessionIsResolved: 'reset-chat-and-close-widget',
        confirmation: {
          type: 'modal',
          title: 'Close conversation',
          description: 'Are you sure you want to close this conversation?',
          confirmButtonText: 'Yes',
          cancelButtonText: 'No',
        },
      },
    ],
  },
}

Show close-widget example

{
  headerButtons: {
    sessionsScreen: [
      {
        functionality: 'close-widget',
        icon: 'CircleX',
      },
    ],
    chatScreen: [
      {
        functionality: 'close-widget',
        icon: 'CircleX',
      },
    ],
  },
}

User

collectUserData

boolean · default: false

Show a built-in form on the welcome screen that asks for the visitor’s name and email. The submitted values create a non-verified contact.

Use prefillUserData and extraDataCollectionFields to tailor the form. For verified identity, see Authentication.

prefillUserData

object · default: {}

Initial values for the name and email inputs in the welcome screen. Requires collectUserData to be true.

Hide properties

name · string

email · string

extraDataCollectionFields

Array<string> · default: []

Extra free-text fields to add to the welcome form, beyond name and email. Requires collectUserData to be true.

user

object · default: {}

Verified or non-verified contact data passed from your app. If omitted, an anonymous contact is used.

See Authentication for the full setup, including how to mint a verified token from your backend.

Show verified contact properties

token · string · required

Server-issued contact token. Generate it via the authenticate-contact API.

externalId · string

Optional ID that scopes the contact’s sessions per workspace — use it when one email can belong to multiple accounts in your application.

Show non-verified contact properties

data · object

Hide properties

name · string

Stored as non_verified_name. Will not override the name on a verified contact with the same email.

email · string

avatarUrl · string

customData · Record<string, string | number | boolean>

Arbitrary user attributes. Stored as non_verified_custom_data.

Show example

{
  org_id: 'org_185938572649',
  vip: true,
  loyalty_points: 1200,
}

externalId · string

Optional ID that scopes the contact’s sessions per workspace.

Chat

initialMessages

Array<string> · default: ["Hello, how can I help you?"]

Messages the visitor sees in a new chat session. They disappear after the visitor sends their first message.

advancedInitialMessages

Array<{ message: string; persistent?: boolean }>

Same idea as initialMessages with per-message persistence control. When set, this overrides initialMessages.

When persistent is true, the message stays pinned at the top of the chat; otherwise it disappears after the first reply.

Show example

{
  advancedInitialMessages: [
    { message: 'Hello, how can I help you?', persistent: true },
    { message: 'Please select an option from the list below:', persistent: false },
  ],
}

initialQuestions

Array<string> · default: []

Suggested starting questions shown at the top of a new chat. Clicking one sends it as the visitor’s first message.

To require a selection before visitors can type, enable requireInitialQuestion.

requireInitialQuestion

boolean · default: false

Require a visitor to select an initialQuestions option before typing in a new session. In the popover, the message box is hidden until selection. In Companion, starter pills appear above the composer and the composer stays visible but disabled. Selecting a question sends it as the first message and enables follow-ups.

Each new or reset session requires another selection. Resuming a session with messages keeps the message box available. If there are no initial questions, or all questions are empty or whitespace-only, the message box stays available.

The popover supports both initialQuestionsPosition values. Companion places starter pills above its composer. Leave this option off to let visitors type their first message freely.

Available in Widget 4.0.63 and Widget 5.0.0. Earlier v5 betas, including beta.10, do not include this behavior.

Show example

{
  initialQuestions: ['Where is my order?', 'I need help with a return'],
  requireInitialQuestion: true,
  initialQuestionsPosition: 'below-initial-messages',
}

initialQuestionsPosition

'above-chat-input' | 'below-initial-messages' · default: "above-chat-input"

Where the suggested questions appear relative to the chat input.

thisWasHelpfulOrNot

object

Prompt the visitor to confirm whether the latest AI reply solved their issue. Renders as two buttons: “This was helpful” and “I need more help”, after an AI reply that might have solved the issue.

Hide properties

enabled · boolean · default: true

Behavior

isOpen

boolean · default: false

Whether the widget is open. Use to open the widget on first render (e.g. inside a webview) or to control its open state from your app.

openAfterNSeconds

number

Open the widget automatically after N seconds on the page.

oneOpenSessionAllowed

boolean · default: false

When true, the New conversation button is hidden while an open session already exists. See Conversation Sessions for the user-facing effect.

router

object

Override the default screen routing.

Hide properties

goToChatIfNoSessions · boolean · default: true

Navigate first-time visitors directly to the chat screen instead of the sessions list.

restoreLastSession · boolean · default: false

Reopen the last selected session when it is still open. The standard widget uses browser storage; a headless provider needs a storage adapter to persist the selection across reloads. Closing the session or starting a new one clears the saved active-session pointer.

chatScreenOnly · boolean · default: false

Show only the welcome and chat screens. The most recent open session is selected; if none exists, an empty conversation is opened and a session is created when the visitor sends a message. The “back to sessions” button is hidden.

anchorTarget

'_top' | '_blank' · default: "_top"

Target attribute applied to all links rendered in AI or human-agent replies.

• _top — open links in the same tab.
• _blank — open links in a new tab.

disableSendingWhenAwaitingAIReply

boolean · default: true

By default the send button is disabled while the AI is generating a reply. Set to false to let the visitor send another message before the AI finishes — the typing indicator stays visible; only the send button’s disabled state is dropped.

Context & custom data

context

object | (() => object)

Runtime data sent with each visitor message so the AI can tailor its response. In v5, pass a function to read current state on each send. The page key accepts url and optional title; entity accepts type, id, title and optional meta and can appear as a context pill.

Exclude query strings and fragments from page URLs. If a path or title contains private information, use an approved route label or omit it.

For record changes without navigation, dispatch opencx:context-changed to refresh the pill. Have the callback read a ref or store so it reflects the record visible when the visitor sends. Host context is still sent when features.pageContext is false. See page context guidance.

Show example

{
  context: {
    page: { url: window.location.origin + window.location.pathname },
    product_id: '99836009',
    product_name: 'Ineffective painkiller',
    product_price: 12.99,
  },
}

messageCustomData

object · default: {}

Per-message metadata attached to each visitor message. Intended for human agents — the AI does not see it and it does not influence replies.

Show example

{
  messageCustomData: {
    platform: 'MOBILE',
    version: '1.3.57',
  },
}

sessionCustomData

Record<string, string | number | boolean> · default: {}

Metadata attached to the session when it is created. Intended for human agents and for filtering sessions in the inbox — the AI does not see it.

Show example

{
  sessionCustomData: {
    visit_id: '0199e212-d7fd-71d3-808b-48d860bfa469',
  },
}

Keys prefixed with opencx__ are reserved for OpenCX-specific controls. Set opencx__ai_agent_version to 'v2' to upgrade that session to the latest AI agent. A session can only upgrade, never downgrade, so a lower value has no effect. The value is stored as session data, so you can also filter on it in the inbox. Omitting it uses the version from your channel settings.

{
  sessionCustomData: {
    opencx__ai_agent_version: 'v2',
  },
}

AI action requests

These options attach data to every HTTP request the widget makes when the AI calls one of your APIs. For secure credentials, configure them in General settings instead.

headers

Record<string, string> · default: {}

Custom headers added to every AI action request.

Show example

{
  headers: {
    auth_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
  },
}

queryParams

Record<string, string> · default: {}

Custom query parameters appended to every AI action request URL.

Show example

{
  queryParams: {
    session_id: '9de647ba-25b9-4d9e-b51a-7ab2f4c68d9d',
  },
}

bodyProperties

Record<string, string> · default: {}

Custom properties merged into the body of every AI action request.

Show example

{
  bodyProperties: {
    preferred_language: 'en',
  },
}

Components

modesComponents

Array<ModeComponent> · default: []

Custom React components rendered in the canvas while a mode is active. See Custom Components for the surrounding implementation guidance.

Show ModeComponent

key · string · required

The mode’s ID, name, or slug.

component · (props: ModeComponentProps) => ReturnType<typeof React.createElement> · required

The functional component to render.

Show ModeComponentProps

react · React

The React instance powering the widget. Use this instead of importing your own to avoid version mismatches.

mode · object

Hide properties

id · string

name · string

slug · string | null

createStateCheckpoint · (payload: Record<string, unknown>) => { success: boolean }

Persist state for whatever is happening inside the mode’s component.

sendMessage · (payload: { content: string; exitModePrompt: string }) => void

Call at the end of the mode to submit a summary message and exit the mode.

isSendingMessage · boolean

Whether sendMessage is currently processing. Use to disable the submit button or show a loading indicator after submission.

Show example

function Onboarding(props: ModeComponentProps) {
  const [monthlyVolume, setMonthlyVolume] = props.react.useState(0);
  const [targetMarket, setTargetMarket] = props.react.useState('');

  const handleSubmit = async () => {
    // Submit to your system here, then end the mode with a summary
    // message and an exit prompt for the AI.
    props.sendMessage({
      content: `My expected volume is ${monthlyVolume} per month.\nMy target market is ${targetMarket}`,
      exitModePrompt: `
        Tell the user something like this:
        "Great! I've now submitted your request.
        We are already checking whether you are eligible to join our service.
        We will notify you as soon as we review your request.
        You can always check the progress by looking at the notifications on the top right of your dashboard."
      `,
    });
  };

  return props.react.createElement(
    'div',
    null,
    props.react.createElement('input', {
      value: monthlyVolume,
      onChange: (e) => setMonthlyVolume(Number(e.target.value)),
    }),
    props.react.createElement('input', {
      value: targetMarket,
      onChange: (e) => setTargetMarket(e.target.value),
    }),
    props.react.createElement(
      'button',
      {
        onClick: handleSubmit,
        disabled: !monthlyVolume || !targetMarket || props.isSendingMessage,
      },
      'Submit',
    ),
  );
}

const options = {
  token: '<WIDGET_TOKEN>',
  modesComponents: [
    {
      key: 'onboarding',
      component: Onboarding,
    },
  ],
};

Accessibility

accessibility

object · default: {}

Accessibility options for the widget UI.

Hide properties

widgetTriggerButton · object

Hide properties

label · string · default: "Chat with us"

Accessible name for the launcher button. Applied as both aria-label (for assistive technology) and title (native hover tooltip).

Required because the trigger is icon-only — satisfies WCAG 2.4.4 (Link Purpose) and 4.1.2 (Name, Role, Value).

Show example

{
  accessibility: {
    widgetTriggerButton: {
      label: 'Open support chat',
    },
  },
}

---

Related Documentation

Configuration

Job-first guidance — pick the right options for branding, launch flow, and visitor experience.

Playground

Try options live and copy a working snippet.

Authentication

Identify signed-in visitors and protect conversation history.

Custom Components

Render richer UI for AI action results and conversation modes.