Help center Core configuration Portals & chat Configure a chat widget Updated Friday, October 30, 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.Choose Save Changes. 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 Changes 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 SettingMeaningGuidance NameAn internal label for the widget.Include the site, audience, or purpose, such as “Customer support portal.” ActiveWhether the widget is enabled.Review this before installing or changing a customer-facing widget. Widget keyThe 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 domainsThe 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. ModeVisitor experienceWhen to use it AI bot + live chatAI assistance and live-agent conversation.Self-service with a staffed handoff path. Live chat onlyLive conversation without AI answers.A team that wants direct human service during supported hours. AI bot onlyAI answers without a live-chat channel.An automated information channel with a clearly configured case fallback. Knowledge base onlyArticle browsing without AI-generated answers or live chat.A lightweight self-service entry point. Case form onlyOpens 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 SettingMeaning and recommendation QueueThe live-chat destination. Confirm queue membership, agent availability, and capacity; selecting a queue does not guarantee an agent can accept a chat. Working hoursUse queue hours, Manual widget hours, or Always. A new widget starts with queue hours. Time zoneThe timezone used for the widget's configured schedule. Verify the zone before entering a weekly schedule. Monday–Sunday start/endShown for Manual widget hours. Set the intended opening interval for each day and test a boundary time. Disable widget outside working hoursControls outside-hours availability. Review it together with Case form automatic switching and the selected mode. Out-of-hours messageSets the explanation visitors receive when live service is outside its schedule. Auto-create caseControls automatic case creation for supported chat processing. It starts enabled on a new widget. A new case created during the move from the AI assistant to an agent runs Case-created workflows. Continuing a chat already linked to a case does not run Created again. For policy-managed live chats, a successful public reply from the current chat agent assigns an unassigned linked case to that agent. An existing case owner is preserved. Closing the chat does not discard a reply that is waiting for this assignment to finish. Division / PriorityDefaults for cases created through the widget where applicable. They do not replace routing and workflow checks. Chat timeoutThe supported wait/follow-up timeout setting. Review it with the waiting and timeout messages. Waiting message / Timeout messageExplain the current wait and what happens when the timeout is reached. Avoid promising a response time your team cannot meet. Follow-up QueueThe destination for supported timed follow-up cases. Show agent profile picturesOff by default. When enabled, the header shows “Connecting you with our Support Team” until the current agent sends their first public reply in that assignment. Assignment alone does not show the agent’s name or photo. A transfer returns the header to the connecting message until the new agent replies. Each agent’s own profile photo still appears beside their replies; bot replies keep the bot avatar. Missing photos use the existing icon or initials. Save, reload the widget, and test a public reply and transfer. The switch is available when your account supports this setting. Conversation historyControls the supported visitor history experience. Changing it affects active conversation/session behavior; communicate the change and test existing and new sessions. Reopen chat windowNever, 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 SettingPurpose and recommendation Bot nameThe name shown for the AI assistant. Use a name that makes its role clear. Bot avatarUpload 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. ToneThe desired communication style. Choose one consistent with the support team's voice. LanguageThe configured response language. Test the actual questions and source content your customers use. Natural typingWhen enabled, newly generated AI answers appear gradually with a natural typing cadence. When disabled, answers appear immediately. Saved conversation history and human agent replies appear immediately. This setting changes presentation, not the bot's knowledge. IntentDescribes the bot's purpose. Be specific about the help it should provide. Advanced promptAdditional 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 SettingMeaning Knowledge base enabledEnables the supported knowledge-browsing experience. Answer sourceChoose Q&A, Knowledge base, or Both for the bot's answer sources. CommunitySelects the customer portal used to scope external knowledge where applicable. Verify that the intended articles are readable in that portal. FAQ search / Show all topicsFind widget-specific topics, questions, and answers. Topic name / Topic descriptionOrganize the widget's FAQ content into recognizable topics. Each compact topic row shows its name and question count, such as 0 questions or 26 questions, with Edit and Delete alongside. The count is the number of FAQ questions in that topic; selecting a topic filters the Questions list. Question / AnswerProvide 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 windowNew policy: signed visitorNew policy: shared IP + widget New conversations / 1 minute530New conversations / 60 minutes15300 Customer messages / 1 minute60600AI requests / 1 minute15150 AI requests / 60 minutes1200; this IP field is fixed and not editable.New handoffs / 10 minutes550 Case submissions / 60 minutes5100Uploaded files / 10 minutes30300 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. SettingMeaning Switch automatically to case submissionOff, Outside working hours, When no agents can accept a chat, or Either. These runtime options are conditional on account support. What customers see during fallbackKeep AI and offer Submit a case, or open the case form directly and hide AI/knowledge browsing. When to show regular form linksNo 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 botPlacement of ordinary form links. They do not override a higher-priority case-form-only mode or fallback. Allow attachmentsWhether visitors can attach files to a case submission. Case form title / Case form introThe form's heading and explanation. Intro supports basic HTML; scripts and embedded content are removed. Subject label / Description labelThe labels for the main case fields. Ask for the information your team needs to begin work. Success messageExplains 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 GroupFieldsWriting guidance HeaderHeader title; Header message.Tell visitors what help is available. NotificationEnable 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 conversationBot 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 handoffChat start message; Direct-agent prompt.Make the transition to an agent clear. These fields are used when live chat is available. Conversation launcherConversation 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 ratingChat 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 emailTranscript email switch; Transcript subject; Transcript intro for the standard email; Use a custom branded email; Custom email body; Insert transcript when branding is supported.Explain the transcript's purpose. Custom branding replaces the standard body and hides Transcript intro; Transcript subject still applies. These controls are widget-specific, separate from global email templates. Appearance GroupControlsRecommendation Brand assetsLogo 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. PlacementPosition: Right, Center, or Left.Check mobile navigation, consent banners, and other floating website controls for overlap. LauncherLauncher background.Make the entry point visible against the host website. Widget frameMain background; Header background; Header text; Container background; Container text.Keep text/background contrast readable. ButtonsButton background; Button hover; Button text; Start button background; Start button text.Keep primary actions recognizable in normal and hover states. Message bubblesSent 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 Choose Save Changes, 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. Chat transcripts in My Tickets New chat transcript activities are public by default. When a chat is linked to a ticket, customers who are allowed to view that ticket can read its transcript under My Tickets, including in the Premiere theme. A chat without a linked ticket does not appear in My Tickets. Customer transcripts include the public conversation and files shared in public messages. Private agent notes and files attached to those notes are excluded from both the ticket transcript and transcript email. Agents can still read private notes in the Chat Console. Existing private transcript activities keep their current visibility. This change does not publish historical private transcripts automatically. The Transcript email switch controls email delivery; it does not control whether a new transcript activity is public on its ticket. Brand transcript emails and verify deliveryA transcript gives a customer a record of a live support conversation. A branded body can add a recognizable support-team identity, a useful introduction and contact details around that record. Keep the actual conversation intact and avoid a design that makes technical content or attachments difficult to read.Open Settings → Self-Service → Chat widgets, select the intended widget, and choose Messages & follow-up → Transcript email.Enable Transcript email if the widget should send eligible closed-chat transcripts. Set Transcript subject to a clear customer-facing subject.Leave Use a custom branded email off to use the standard email. If you want your own layout and the setting is available, turn it on. The Custom email body replaces the standard body; Transcript intro is hidden while branding is on, but its saved value is retained for the standard design.Wait for the email editor to finish loading. Add the logo, introduction, colors, header and footer. Use Source for supported email HTML and inline styles when appropriate. The server sanitizes saved HTML; do not depend on scripts or unsupported embedded content.Place {{chat_transcript}} exactly once on its own line at the place where the conversation should appear. Use Insert transcript if the placeholder is missing. Do not paste a real customer conversation into the reusable template.If an image is still loading, wait for completion before saving. Resolve any token or editor validation message.Choose the widget’s main Save Changes action. There is no separate transcript-email draft, test-send or email-preview control. The widget’s visual preview is not proof that a transcript email will render or be delivered.Reopen the saved widget to verify the subject, branding switch and body. Then complete a controlled end-to-end conversation and delivery check.Keep one transcript placeholderThe token is replaced in the email body with the public conversation. Public images appear inline; other public attachments appear as links in that body. They are not sent as separate email attachments. The token does not change the recipient, sender, message visibility or delivery timing. If it is missing or repeated, correct the template; do not work around validation by pasting a static transcript.Build the introduction and next steps around one {{chat_transcript}} placeholder on its own line. This is an illustrative editor setup, not a received email. Save through the widget’s main Save Changes action, reopen it, then separately test an eligible closed conversation and actual inbox delivery.Know when an email is eligibleCore queues the transcript after an actual chat close when Transcript email is enabled, the Contact has an email address, the chat is not bot-only and a live agent has replied. It is sent to that Contact email address. A bot-only conversation, merely opening the widget or assigning an agent without a reply is not a useful delivery test. A queued message is not proof of inbox delivery; normal email processing and recipient-mailbox handling still apply.The customer transcript excludes private agent messages/notes and their files. The branded body does not change those rules. The separate case-linked transcript activity has its own visibility behavior, described above under Chat transcripts in My Tickets.Test a B2B conversation safelyUse a designated test Contact with an inbox you can inspect and a widget/domain approved for testing.Start a conversation that reaches a live agent. Have the agent send a public reply containing a harmless sample resolution, such as a documented equipment-check result.If your test includes files or a private note, use non-sensitive sample material. Confirm that private content is absent from the customer email.Close the chat through the supported flow. Inspect the received message: subject, logo, introduction, complete public conversation, supported attachments and footer.Check the email on a narrow screen and in the email clients your customers use. Long technical text should remain readable.Turn custom branding off and choose Save Changes if you need to return to the standard layout. The saved custom design remains available for later use. Verify the next eligible conversation rather than expecting earlier emails to change.If the visual editor cannot load, the fallback field keeps the HTML available; reopen the widget to retry the editor. If a saved custom design cannot be loaded or rendered, the standard transcript email is used. Treat that fallback as a reason to review the template, not as confirmation that the intended branding appeared.SymptomWhat to checkThe custom branding switch is missingThe account/application capability may not support the control. Check with your administrator; ordinary transcript email can still use the standard design.Save rejects the templateCheck that {{chat_transcript}} occurs exactly once on its own line, and wait for any pending image upload. Read the actual validation message.No transcript email arrivesConfirm the chat really closed, a live agent replied, the Contact has the intended email, and Transcript email is enabled. Then check email processing and the receiving mailbox.The email uses the standard layoutReopen the saved widget and check the branding switch and body; a load/render failure can fall back to the standard email.Transcript intro disappeared in the editorExpected while custom branding is enabled: the custom body supplies the introduction. The standard intro is retained separately.Private content appears in an older case activityHistorical activity visibility is not automatically rewritten. Inspect the original activity and its access separately; changing the email template does not repair historical records.For the agent workflow, use Run chat as an accountable support channel. For unattended conversations, use Follow up on unanswered chats. Verify routing and actual customer delivery separately from the widget’s saved settings. Troubleshooting ProblemWhat 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 and related configuration 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. Validate continuation, greetings and case submission A customer can return to the widget home screen and choose Continue your conversation to resume the permitted conversation. Continuation uses the saved conversation identity and restores both sides of the transcript, including available files and original message times. It keeps an unsent composer draft. When history is disabled, only the active conversation authorized for that customer can be resumed; turning history off does not reveal older conversations. Configure the continuation cardOpen the widget under Chat widgets and review its continuation title and message in the existing message settings.Use a title such as “Welcome back!” and explain what happens next, for example “Pick up where you left off. Our team will reply during support hours.”Review the configured conversation button background, text and hover colors in Appearance. The Continue control uses the conversation card treatment, including keyboard focus styling.Save the widget, then open the installed widget as an authorized customer. Start a conversation, send a test question and receive an agent reply.Go Back and choose Continue your conversation. Verify both messages and an attachment, then repeat after a browser reload. A lost local transcript should reload from the server. If loading fails, use Retry without resubmitting the customer's question. Test the live greeting and form focusThe live prompt appears once the selected conversation and required visitor identity are ready. Optional bot metadata and realtime connection setup do not need to finish first. Sign-in requirements and availability still apply. Merely opening live chat does not create an empty chat or case; the customer must send content through the existing submission flow.Configure a helpful live prompt, such as “Tell us which product and account you need help with.” Test a recognized contact and a visitor who must sign in.Open the case form, check or complete Name and Email, then fill Subject, Description and the configured questions. A recognized contact can have prefilled identity values; verify those values before continuing. Move with Tab and Shift+Tab, use dropdowns and scroll through a long form while chat updates continue.On a narrow screen, open the keyboard and move to the next field. The current field and text selection should remain usable without a jump to the hidden chat composer.Navigate Back and forward quickly while loading. Verify that an old greeting does not appear in another conversation, and confirm the separate AI and live modes. Read and reply to a submitted caseNew widget case activities begin with the customer's description. When the form supplies answer data with a label or value, the activity then includes Additional details and compact question labels with their answers. Without that answer data, the description appears on its own. For example, “Cannot export the October attendance report” appears first, followed by “Product” and “Dance”, then “Affected location” and “North studio”. Line breaks are preserved and typed HTML is shown as customer text. Technical widget source, page and debug context do not appear in the public activity or the customer notification.Submit a case containing several description lines, a dropdown answer and an attachment.Open the resulting case as an authorized agent. Confirm the description appears first, question labels match the configured form, and files are available through the normal attachment area.Reply using the normal case workflow. Inspect the quoted activity and a narrow email preview: text should wrap naturally without a wide form table or widget diagnostics.If attachment completion reports a recoverable failure, retry the existing attachment recovery action for that case. Do not submit a duplicate case. Confirm the original case/activity and recovered file remain together.These presentation rules apply to new submissions. They do not rewrite earlier activities or introduce a second private activity. Review Run effective B2B support conversations in Chat for the Sent, Delivered and Seen statuses on public agent replies. Receipt support requires matching application packages and enabled tenant storage; it adds no customer-facing form setting. Was this article helpful? Yes No Thank you for your feedback.