Use this page when the widget is already installed and you want it to feel right for your website, support workflow, and visitor journey.
Start with Deciding the Configuration Decisions
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?
Bot and human identity
Logos and launcher visuals
Theme, language, and copy
Set the AI identity visitors should see
Use bot
Set the default human-support appearance
Use humanAgent
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 assets
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
theme
Use text settings for wording
textContent, language, and translationOverrides
Start with a small configuration first
const options = { token: '<WIDGET_TOKEN>' , language: 'en' , theme: { primaryColor: '#166534' , }, };
If the built-in theme options are not enough, use cssOverrides
Place the widget inside a page section, such as a help page, pricing page, or account area. See Inline embed setup .
Open the widget on first render for cases like a webview or a dedicated support screen. See Open by default setup .
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 oneOpenSessionAllowedrouter.goToChatIfNoSessionsrouter.chatScreenOnlyheaderButtonsConversation Sessions . Shape The First-Visit Experience Welcome messages
Suggested questions
Helpful prompt
Choose the opening message style
Use initialMessages
Use advanced messages only when needed
Switch to advancedInitialMessages
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 initialQuestions
Choose the position
Use initialQuestionsPosition
Keep the list short
Pick the questions that reduce hesitation and help visitors start quickly.
const options = { token: '<WIDGET_TOKEN>' , initialQuestions: [ 'Where is my order?' , 'Can I change my plan?' ], };
Turn on the prompt
Use thisWasHelpfulOrNot
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 collectUserDataprefillUserDataextraDataCollectionFields
Attach Context Without Changing The AI Prompt AI context
Human-only message data
Session-level notes
Use context for runtime information
Use context
Keep it focused on what changes the answer
This is the right place for page URL, product ID, or current screen context.
Add the context object
const options = { token: '<WIDGET_TOKEN>' , context: { page: { url: window . location . href , }, }, };
Use messageCustomData for per-message notes
messageCustomData
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
sessionCustomData
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:
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 custom components
Use modesComponents
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 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 component guides next when you need implementation 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.
Conversation Sessions Re-check how history, handoff, and resolution should behave.
