Configure a chat widget

Updated Monday, October 26, 2026 · Marc Staine

A chat widget gives website visitors a way to find knowledge, ask an AI bot, contact an agent, or submit a case. Configure the experience around the support you can provide: choose the available channels, connect the right knowledge and queue, and make the outside-hours experience clear.

Applies to: Supportbench Core. Location: Settings → Self-Service → Chat widgets. The Chat module and chat-widget editing permission are required. Some newer controls appear only when supported by the account.

Before you begin

Identify the website domains where the widget will run and a staging page where you can test it.
Choose the live-chat queue, its agents, available capacity, and working hours.
For AI or knowledge answers, prepare the intended FAQ content or published customer-readable articles and choose the correct Community.
Decide whether visitors can be anonymous or must be recognized as existing Contacts. Recognizing a contact is different from proving that a visitor has signed in.
Agree what happens outside working hours and when no agent can accept a new chat.

Set up a widget

Open Settings → Self-Service → Chat widgets and create a widget or select an existing one.
In Overview, give it a recognizable Name, review Active, select its Mode, and add Allowed domains.
Configure the live Queue and availability in Routing. Review case defaults and any follow-up settings.
Configure the AI persona and Knowledge answer sources if those channels are enabled.
Choose Case form behavior, customer-facing Messages, and Appearance.
Review Security and Abuse protection. Test recognized-contact behavior before requiring it.
Save the widget. Use the Install tab's generated snippet for the saved widget.
Install it on an allowed staging domain and test the complete visitor experience, including unavailable-agent and outside-hours scenarios.
Install the verified snippet on the intended website and monitor real conversations and case submissions.

Most widget edits take effect after the main Save action. FAQ topics and questions use separate modal saves that persist immediately. Image uploads also happen before the main settings save. The visual preview helps with appearance; it does not test provider connectivity, AI answers, queue availability, or delivered email.

Overview and modes

Setting	Meaning	Guidance
Name	An internal label for the widget.	Include the site, audience, or purpose, such as “Customer support portal.”
Active	Whether the widget is enabled.	Review this before installing or changing a customer-facing widget.
Widget key	The read-only identifier used by the installation snippet.	Copy the generated code from Install. The widget key identifies configuration; it is not an authentication secret.
Allowed domains	The embedding host allowlist. You can enter a hostname or paste a URL; the input normalizes its host. Wildcards such as *.example.com are supported.	Add the actual staging and production hosts. Commit each entry with Enter or Tab and resolve invalid entries before saving.

Mode	Visitor experience	When to use it
AI bot + live chat	AI assistance and live-agent conversation.	Self-service with a staffed handoff path.
Live chat only	Live conversation without AI answers.	A team that wants direct human service during supported hours.
AI bot only	AI answers without a live-chat channel.	An automated information channel with a clearly configured case fallback.
Knowledge base only	Article browsing without AI-generated answers or live chat.	A lightweight self-service entry point.
Case form only	Opens case submission and pauses new AI/live entry while retaining their configuration. The widget remains visible outside hours.	A case-first channel or temporary replacement for chat. Available only where the runtime option is supported.

A newly created widget starts active with AI, live chat, and knowledge enabled. Its answer source starts as Q&A, its tone as Friendly, and its language as English. These are starting values for a new widget, not a claim about an existing widget's saved configuration. AI execution also requires the account's AI capability.

Routing, hours, and follow-up

Setting	Meaning and recommendation
Queue	The live-chat destination. Confirm queue membership, agent availability, and capacity; selecting a queue does not guarantee an agent can accept a chat.
Working hours	Use queue hours, Manual widget hours, or Always. A new widget starts with queue hours.
Time zone	The timezone used for the widget's configured schedule. Verify the zone before entering a weekly schedule.
Monday–Sunday start/end	Shown for Manual widget hours. Set the intended opening interval for each day and test a boundary time.
Disable widget outside working hours	Controls outside-hours availability. Review it together with Case form automatic switching and the selected mode.
Out-of-hours message	Sets the explanation visitors receive when live service is outside its schedule.
Auto-create case	Controls automatic case creation for supported chat processing. It starts enabled on a new widget.
Division / Priority	Defaults for cases created through the widget where applicable. They do not replace routing and workflow checks.
Chat timeout	The supported wait/follow-up timeout setting. Review it with the waiting and timeout messages.
Waiting message / Timeout message	Explain the current wait and what happens when the timeout is reached. Avoid promising a response time your team cannot meet.
Follow-up Queue	The destination for supported timed follow-up cases.
Show agent profile pictures	Off by default. When enabled, the current assigned agent appears in the live conversation header, and each agent’s own profile photo appears beside their replies in the widget and Core chat console. Bot replies keep the bot avatar. Missing or unavailable photos use the existing icon or initials. Save, reload the widget, and test a live assignment and transfer. The switch is available when your account supports this setting.
Conversation history	Controls the supported visitor history experience. Changing it affects active conversation/session behavior; communicate the change and test existing and new sessions.
Reopen chat window	Never, Allow any time, or 1 hour, 4 hours, 12 hours, 24 hours, 3 days, 7 days, or 30 days. A new widget starts with Allow any time.

To confirm a timeout by email or give the resulting ticket a friendly title, configure a Case workflow with the Chat timed out event. It runs after the follow-up case, transcript and routing are ready, including for a chat already linked to a case. Add Change case subject and the required customer notification. Timeout conversion alone does not send a confirmation email. Historical timeouts and normal chat closure do not trigger this event.

Some timeout, history, and runtime controls are conditional. If the editor reports that an option is unavailable, do not assume the setting is active or has been saved.

AI persona and behavior

Setting	Purpose and recommendation
Bot name	The name shown for the AI assistant. Use a name that makes its role clear.
Bot avatar	Upload or clear the bot image where storage support is available. Supported image types include PNG, JPG, GIF, and WebP; the avatar limit is 250 KB.
Tone	The desired communication style. Choose one consistent with the support team's voice.
Language	The configured response language. Test the actual questions and source content your customers use.
Natural typing	Controls the typing presentation. It does not expand the bot's knowledge.
Intent	Describes the bot's purpose. Be specific about the help it should provide.
Advanced prompt	Additional behavior instructions. Keep them consistent with your content, support process, and handoff promises.

AI settings may remain editable while a mode that does not use AI is selected. Saving a prompt does not enable the AI channel or the account's AI capability.

Knowledge and Q&A

Setting	Meaning
Knowledge base enabled	Enables the supported knowledge-browsing experience.
Answer source	Choose Q&A, Knowledge base, or Both for the bot's answer sources.
Community	Selects the customer portal used to scope external knowledge where applicable. Verify that the intended articles are readable in that portal.
FAQ search / Show all topics	Find widget-specific topics, questions, and answers.
Topic name / Topic description	Organize the widget's FAQ content into recognizable topics.
Question / Answer	Provide the customer's question and the full answer they should receive. FAQ content is separate from knowledge-base Articles.

Separate save behavior: FAQ topic and question edits save immediately through their own dialogs. They are not an unsaved part of the main widget form.

For a growing documentation library, keep the detailed guidance in maintained Articles and choose the appropriate knowledge source. Use widget Q&A for concise, specific answers. Test both exact feature names and the natural-language problems customers ask about.

Security and recognized contacts

The Security tab offers independent Require a recognized contact controls and explanatory messages for live chat, AI, and case submission when supported. These controls start off on a new widget.

An Allowed domain is an embedding restriction, not visitor authentication. Passing an email address or Contact ID supplies identity context; it does not independently verify that the visitor signed in to your website. Only pass a customer's identity after your website has authenticated that customer. A supplied Company must be linked to the Contact.

Use the Install tab's recognized-user example with your signed-in customer's values. Clear identity on website logout using the supported sbChatSetIdentity({}) integration. Do not embed credentials or a fixed real customer's identity in publicly served installation code.

Abuse protection

Choose Off, Monitor only, or Enforce. Off preserves the existing behavior and is the starting value. Monitor only records activity that would be blocked; Enforce applies the configured limits. Observe normal and busy periods for at least seven days before enabling enforcement.

Action and window	New policy: signed visitor	New policy: shared IP + widget
New conversations / 1 minute	5	30
New conversations / 60 minutes	15	300
Customer messages / 1 minute	60	600
AI requests / 1 minute	15	150
AI requests / 60 minutes	120	0; this IP field is fixed and not editable.
New handoffs / 10 minutes	5	50
Case submissions / 60 minutes	5	100
Uploaded files / 10 minutes	30	300

Editable caps accept 1–1,000,000. The two scopes help distinguish one visitor from many visitors sharing an office network. Review the last-24-hour blocked and would-block counts when available. This feature does not add a CAPTCHA or change allowed file types. If protection storage is unavailable, the editor reports that state; do not assume enforcement is active.

Case form and automatic switching

Order of precedence: Case form only mode takes precedence over automatic fallback, which takes precedence over ordinary form-link rules. Configure these as separate decisions.

Setting	Meaning
Switch automatically to case submission	Off, Outside working hours, When no agents can accept a chat, or Either. These runtime options are conditional on account support.
What customers see during fallback	Keep AI and offer Submit a case, or open the case form directly and hide AI/knowledge browsing.
When to show regular form links	No regular form link; when live and AI are both off; when live is off; or alongside chat/AI. These are ordinary links, separate from automatic switching.
Show on widget home / Show in knowledge base / Show after bot	Placement of ordinary form links. They do not override a higher-priority case-form-only mode or fallback.
Allow attachments	Whether visitors can attach files to a case submission.
Case form title / Case form intro	The form's heading and explanation. Intro supports basic HTML; scripts and embedded content are removed.
Subject label / Description label	The labels for the main case fields. Ask for the information your team needs to begin work.
Success message	Explains what happens after submission. Give a realistic next step.

Automatic switching considers the relevant schedule and whether eligible agents can accept a new chat. Existing chats can finish; new live-chat entry resumes when the fallback condition clears. Test this independently of simply changing an agent's status.

Custom questions

Add up to ten questions. Each has Question text, an Answer type, and a Required switch. Types are Short answer, Long answer, Single choice, Dropdown, and Multiple choice. Choice questions support up to twenty options, with their order preserved.

Ask only for information needed to route or diagnose the request. Keep required questions short and clear. Test submission with missing required answers, attachments, and each choice type you use.

Messages and customer-facing copy

Group	Fields	Writing guidance
Header	Header title; Header message.	Tell visitors what help is available.
Notification	Enable notification; Notification message; Background color; Text color. Available only when supported.	Use a concise notice above knowledge content. Basic HTML and web addresses are supported; maintain readable contrast.
Bot conversation	Bot welcome message; Bot start message; End message; No-answer message.	Explain the assistant's role and the next step when it cannot answer. These fields are used by AI modes.
Live handoff	Chat start message; Direct-agent prompt.	Make the transition to an agent clear. These fields are used when live chat is available.
Conversation launcher	Conversation start title; Start button text; Conversation start message; Conversation continue title; Conversation continue message.	Distinguish starting a new conversation from reopening an existing one.
Chat rating	Chat rating switch; Rating question; Positive label; Negative label; Rating thank-you message.	Use neutral wording and clear response labels. The dependent fields appear when rating is enabled.
Transcript email	Transcript email switch; Transcript subject; Transcript intro.	Explain the transcript's purpose. These are widget-specific messages, separate from global email templates.

Appearance

Group	Controls	Recommendation
Brand assets	Logo upload/clear; launcher image upload/reset; Icon style.	Use a recognizable, legible image. Launcher images have a 250 KB limit; follow the uploader's validation for each asset.
Placement	Position: Right, Center, or Left.	Check mobile navigation, consent banners, and other floating website controls for overlap.
Launcher	Launcher background.	Make the entry point visible against the host website.
Widget frame	Main background; Header background; Header text; Container background; Container text.	Keep text/background contrast readable.
Buttons	Button background; Button hover; Button text; Start button background; Start button text.	Keep primary actions recognizable in normal and hover states.
Message bubbles	Sent message background/text; Received message background/text.	Distinguish the speakers while keeping both readable.

Use the preview to check visual choices, then test the installed widget on both a narrow phone-sized screen and a desktop. Notification colors are configured in Messages, not in the main Appearance color groups.

Install and validate

Save the widget, then open Install.
Copy the generated anonymous snippet or the recognized-user example appropriate to your website.
Place it in your website's supported script integration location. The generated code loads the Supportbench chat plugin from the API host.
For recognized users, supply values from the currently authenticated customer. Clear them at logout and test switching between users on the same browser.
Check that the website host matches Allowed domains.
Test a new conversation, continuation/reopening, an answerable and unanswerable question, live handoff, outside-hours fallback, and case submission.

The Install tab also shows supported controls such as hideChatApp, showChatApp, onChatLaunch, and onChatHide. Use the generated examples rather than copying another widget's key or hard-coding a visitor identity.

Recommended configurations

Business-hours B2B support: use AI + live chat, a staffed queue, verified knowledge, and an explicit outside-hours case fallback.
Self-service launch: start with Knowledge base only if your goal is article discovery before introducing AI or live staffing.
A signed-in customer application: supply identity after website authentication and test recognized-contact requirements independently for live, AI, and cases.
A team introducing abuse limits: monitor before enforcing, especially when many legitimate users share the same company network.

Example: live support with an after-hours case form

Select AI bot + live chat and the customer-support queue.
Choose the queue's working hours and verify its schedule.
Select the appropriate Community and knowledge answer source. Test a known published article.
Under Case form, choose automatic switching Outside working hours and Open the case form directly, where supported.
Write a form intro explaining when the team will respond. Keep required questions limited to information needed for triage.
Save and test during opening hours and outside them. Confirm the visitor sees the intended channel and a submitted case reaches the expected team.

Troubleshooting

Problem	What to check
The widget does not appear.	Installation snippet, saved key, Active state, Allowed domains, selected mode, working hours, and outside-hours settings.
AI is unavailable or cannot answer.	The selected mode, account AI availability, answer source, selected Community, article visibility, and the actual question/source content.
No agent receives the chat.	Queue membership, working hours, eligible agents, availability/capacity, and automatic fallback settings.
The case form appears unexpectedly.	Case form only mode first, automatic switching second, and regular form-link rules third. Test the actual outside-hours/no-agent condition.
A recognized-contact restriction blocks a visitor.	Whether the website passed the correct existing Contact only after sign-in, whether the Company is linked, and whether logout cleared old identity.
A control is missing.	Module/permission access and any unavailable-feature notice. Conditional controls are not guaranteed on every account.
Branding or FAQ edits behave differently when saved.	FAQ dialogs and image uploads have separate immediate operations; most other fields need the main Save.
Save reports a partial result.	Read the full message. Widget settings can save while an adjacent abuse-policy update fails. Reopen and verify both areas before claiming protection changed.
A new domain is rejected.	Commit the domain chip, check the normalized host, and fix validation errors rather than leaving an unfinished typed value.

Audit shows Created and Last modified information for the widget. Use conversation and case evidence to verify runtime outcomes; those timestamps alone do not prove successful visitor interactions.

Organization → Queues, Agent Status, and Roles.
Self-Service → Customer portal; Knowledge Base → Topics and Review groups.
Account → AI Configuration and Feature Modules.
Configuration → Workflows; Cases → Priorities and Policy.

Was this article helpful?