> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Tip>
  Prefer tinkering to reading? The **[Playground](/widget/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](/widget/custom-components), [React Components](/widget/custom-components-react), or [Headless](/widget/custom-components-headless).
</Tip>

## Start with Deciding the Configuration Decisions

<AccordionGroup>
  <Accordion title="How should the widget look?" icon="paintbrush">
    Decide on the widget brand, copy, colors, launcher visuals, and deeper styling.
  </Accordion>

  <Accordion title="How should the widget open?" icon="message">
    Decide between the default floating launcher, inline embed, open-by-default behavior, and delayed open.
  </Accordion>

  <Accordion title="What should visitors see first?" icon="comment">
    Decide what visitors should see first, including welcome copy, suggested questions, and a quick resolution prompt.
  </Accordion>

  <Accordion title="What extra data should travel with the conversation?" icon="database">
    Decide what AI context, human-only metadata, and action-request data should travel with the conversation.
  </Accordion>
</AccordionGroup>

## Match The Widget To Your Brand

<Tabs>
  <Tab title="Bot and human identity">
    <Steps>
      <Step title="Set the AI identity visitors should see">
        Use <Tooltip tip="Configuration object for the AI identity shown in the widget header and message bubbles — includes name and avatar.">`bot`</Tooltip> for the AI name and avatar shown in the widget header and AI messages.
      </Step>

      <Step title="Set the default human-support appearance">
        Use <Tooltip tip="Configuration object for the default human agent appearance shown after handoff — includes avatar.">`humanAgent`</Tooltip> when your team wants a consistent human avatar after handoff.
      </Step>

      <Step title="Apply both in one options object">
        ```tsx theme={"dark"}
        const options = {
          token: '<WIDGET_TOKEN>',
          bot: {
            name: 'Acme Support',
            avatarUrl: 'https://example.com/acme-bot.png',
          },
          humanAgent: {
            avatarUrl: 'https://example.com/support-team.png',
          },
        };
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Logos and launcher visuals">
    <Steps>
      <Step title="Decide what brand visuals should appear">
        Use <Tooltip tip="Configuration object for brand visuals — organization logo, launcher images, and other visual identity assets.">`assets`</Tooltip> when the widget should look like part of your site instead of a generic chat tool.
      </Step>

      <Step title="Start with the welcome logo">
        The most common first change is the organization logo on the welcome screen.
      </Step>

      <Step title="Add the assets object">
        ```tsx theme={"dark"}
        const options = {
          token: '<WIDGET_TOKEN>',
          assets: {
            organizationLogo: 'https://example.com/logo.png',
          },
        };
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Theme, language, and copy">
    <Steps>
      <Step title="Use theme for color and layout">
        <Tooltip tip="Configuration object for colors, panel sizing, spacing, and other layout-level visual settings.">`theme`</Tooltip> controls colors, panel sizing, spacing, and other layout-level visuals.
      </Step>

      <Step title="Use text settings for wording">
        `textContent`, `language`, and <Tooltip tip="Custom text overrides for specific widget UI strings — lets you match product vocabulary without changing the language setting.">`translationOverrides`</Tooltip> help the widget match your product vocabulary.
      </Step>

      <Step title="Start with a small configuration first">
        ```tsx theme={"dark"}
        const options = {
          token: '<WIDGET_TOKEN>',
          language: 'en',
          theme: {
            primaryColor: '#166534',
          },
        };
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Note>
  If the built-in theme options are not enough, use <Tooltip tip="A string of custom CSS injected into the widget for deeper styling beyond the theme object.">`cssOverrides`</Tooltip> for deeper styling. This is the right option when you need to target specific widget parts with custom CSS.
</Note>

## Choose How The Widget Opens

<AccordionGroup>
  <Accordion title="Floating launcher" icon="message">
    Keep chat available across the site without taking permanent page space. See [Floating launcher setup](/widget/install-widget#floating-launcher).
  </Accordion>

  <Accordion title="Inline embed" icon="rectangle-list">
    Place the widget inside a page section, such as a help page, pricing page, or account area. See [Inline embed setup](/widget/install-widget#inline-embed).
  </Accordion>

  <Accordion title="Open by default" icon="arrow-up-right-from-square">
    Open the widget on first render for cases like a webview or a dedicated support screen. See [Open by default setup](/widget/install-widget#open-by-default).
  </Accordion>

  <Accordion title="Open after a delay" icon="clock">
    Open the widget after time on page when you want a proactive nudge instead of an always-on interruption. See [Delayed open setup](/widget/install-widget#open-after-a-delay).
  </Accordion>
</AccordionGroup>

<Info>
  Need to change session behavior too? Use options like <Tooltip tip="When true, hides the new-conversation option while an open thread already exists.">`oneOpenSessionAllowed`</Tooltip>, <Tooltip tip="Takes first-time visitors directly into the chat flow when there is no history to resume.">`router.goToChatIfNoSessions`</Tooltip>, <Tooltip tip="Removes the sessions browser and lands the visitor directly in the chat experience.">`router.chatScreenOnly`</Tooltip>, and <Tooltip tip="Array of button identifiers shown in the widget header — e.g. resolve-session.">`headerButtons`</Tooltip>. For the user-facing effect of those settings, see [Conversation Sessions](/widget/conversation-sessions).
</Info>

## Shape The First-Visit Experience

<Tabs>
  <Tab title="Welcome messages">
    <Steps>
      <Step title="Choose the opening message style">
        Use <Tooltip tip="Array of welcome messages displayed when a new conversation starts.">`initialMessages`</Tooltip> when you want a simple welcome message for a new chat.
      </Step>

      <Step title="Use advanced messages only when needed">
        Switch to <Tooltip tip="Extended welcome messages where some stay visible in the thread and others disappear after the first reply.">`advancedInitialMessages`</Tooltip> when some opening messages should stay visible in the conversation and others should disappear after the first reply.
      </Step>

      <Step title="Keep the opening copy focused">
        Use the welcome area to set expectations, not to explain every feature of your support flow.
      </Step>
    </Steps>

    ```tsx theme={"dark"}
    const options = {
      token: '<WIDGET_TOKEN>',
      initialMessages: ['Hi, how can I help today?'],
    };
    ```
  </Tab>

  <Tab title="Suggested questions">
    <Steps>
      <Step title="List the most common starting intents">
        Use <Tooltip tip="Suggested starting questions shown to the visitor to reduce hesitation and guide the first message.">`initialQuestions`</Tooltip> for the first few things visitors usually ask.
      </Step>

      <Step title="Choose the position">
        Use <Tooltip tip="Controls whether suggested questions appear above the input field or closer to the welcome copy.">`initialQuestionsPosition`</Tooltip> to decide whether they appear above the input or closer to the welcome copy.
      </Step>

      <Step title="Keep the list short">
        Pick the questions that reduce hesitation and help visitors start quickly.
      </Step>
    </Steps>

    ```tsx theme={"dark"}
    const options = {
      token: '<WIDGET_TOKEN>',
      initialQuestions: ['Where is my order?', 'Can I change my plan?'],
    };
    ```
  </Tab>

  <Tab title="Helpful prompt">
    <Steps>
      <Step title="Turn on the prompt">
        Use <Tooltip tip="A built-in widget prompt that asks the visitor whether the AI's answer resolved their issue, before the conversation moves on.">thisWasHelpfulOrNot</Tooltip> when you want the widget to ask whether the latest AI answer solved the issue.
      </Step>

      <Step title="Use it after self-serve answers">
        This works best when the AI often resolves issues without a human handoff.
      </Step>

      <Step title="Keep the next step clear">
        Pair it with your handoff setup so visitors who still need help know what happens next.
      </Step>
    </Steps>

    ```tsx theme={"dark"}
    const options = {
      token: '<WIDGET_TOKEN>',
      thisWasHelpfulOrNot: {
        enabled: true,
      },
    };
    ```
  </Tab>
</Tabs>

<Info>
  Need to collect visitor details before chat starts? Use <Tooltip tip="When true, the widget shows a built-in form asking for the visitor's name and email before chat begins.">`collectUserData`</Tooltip> for the built-in form, <Tooltip tip="Pre-populates the name and email fields in the data collection form with values your app already knows.">`prefillUserData`</Tooltip> when your site already knows the visitor’s name or email, and <Tooltip tip="Adds custom fields beyond name and email to the built-in data collection form.">`extraDataCollectionFields`</Tooltip> only for the extra fields you truly need.
</Info>

## Attach Context Without Changing The AI Prompt

<Tabs>
  <Tab title="AI context">
    <Steps>
      <Step title="Use context for runtime information">
        Use <Tooltip tip="Runtime data (page URL, product ID, screen context) sent with each message so the AI can tailor its response.">`context`</Tooltip> for page-level or runtime details the AI may need on each message.
      </Step>

      <Step title="Keep it focused on what changes the answer">
        This is the right place for page URL, product ID, or current screen context.
      </Step>

      <Step title="Add the context object">
        ```tsx theme={"dark"}
        const options = {
          token: '<WIDGET_TOKEN>',
          context: {
            page: {
              url: window.location.href,
            },
          },
        };
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Human-only message data">
    <Steps>
      <Step title="Use messageCustomData for per-message notes">
        <Tooltip tip="Per-message metadata attached to each contact message — intended for human agents, not the AI.">`messageCustomData`</Tooltip> travels with each contact message but is intended for human use, not to guide the AI response.
      </Step>

      <Step title="Use it for operational metadata">
        Good examples include app version, platform, or support workflow metadata.
      </Step>

      <Step title="Add the message metadata">
        ```tsx theme={"dark"}
        const options = {
          token: '<WIDGET_TOKEN>',
          messageCustomData: {
            platform: 'WEB',
          },
        };
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Session-level notes">
    <Steps>
      <Step title="Use sessionCustomData when the session starts">
        <Tooltip tip="Metadata attached when the session is created — useful for filtering, routing, and human operator context.">`sessionCustomData`</Tooltip> is attached when the session is created and is useful for human operators and filtering.
      </Step>

      <Step title="Keep it tied to the session itself">
        Good examples include visit IDs, plan tier, workspace ID, or a support-route label.
      </Step>

      <Step title="Add the session metadata">
        ```tsx theme={"dark"}
        const options = {
          token: '<WIDGET_TOKEN>',
          sessionCustomData: {
            visitId: 'visit_123',
          },
        };
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Pass Data To AI Actions

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

* <Tooltip tip="Custom HTTP headers sent with AI action requests to your APIs.">`headers`</Tooltip>
* <Tooltip tip="Custom query parameters appended to AI action request URLs.">`queryParams`</Tooltip>
* <Tooltip tip="Custom properties merged into the body of AI action requests.">`bodyProperties`</Tooltip>

Use these when the action request needs customer-specific or page-specific data. If your main problem is secure API credentials, see [General settings](https://platform.open.cx/settings).

## Advanced UI: Conversation Modes

<Tabs>
  <Tab title="Use modesComponents">
    Use <Tooltip tip="Widget components that take over the full chat area to drive a structured flow — like onboarding, qualification, or multi-step forms — instead of normal back-and-forth messages.">modesComponents</Tooltip> when the widget should temporarily switch from normal chat to a guided flow, such as onboarding, qualification, or structured data collection.

    <CardGroup cols={2}>
      <Card title="Good fit" icon="check">
        Multi-step flows, guided forms, and canvas-style experiences.
      </Card>

      <Card title="What you control" icon="sliders">
        The UI shown during the active mode, the submit action, and the exit flow back to the conversation.
      </Card>
    </CardGroup>

    <Note>
      Choose this when the widget is driving a flow, not just rendering the result of one action.
    </Note>
  </Tab>

  <Tab title="Use custom components">
    Use custom components when the AI stays in a normal chat thread but one action result should render as richer UI.

    <CardGroup cols={2}>
      <Card title="Good fit" icon="bolt">
        Order summaries, balance cards, booking confirmations, and status views.
      </Card>

      <Card title="Where to continue" icon="paintbrush" href="/widget/custom-components">
        Use the custom components guides for the React and headless implementations.
      </Card>
    </CardGroup>

    <Info>
      Choose this when you are rendering a result inside the conversation, not taking over the conversation flow.
    </Info>
  </Tab>
</Tabs>

## Where To Go Next

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

<CardGroup cols={2}>
  <Card title="Custom Components" icon="paintbrush" href="/widget/custom-components">
    Decide when richer UI is worth the extra implementation work.
  </Card>

  <Card title="React Components" icon="react" href="/widget/custom-components-react">
    Register action-specific UI in the default React widget.
  </Card>

  <Card title="Headless" icon="code" href="/widget/custom-components-headless">
    Build fully custom rendering with the headless widget packages.
  </Card>

  <Card title="Mobile Support" icon="phone" href="/widget/native-mobile">
    Configure the widget for iOS, Android, and React Native support screens.
  </Card>
</CardGroup>