How to customize the complete chatbot widget
Build a branded, accessible widget and verify its behavior on desktop and mobile.
Widget Integration separates appearance, images, behavior, positioning, triggers, action bar and advanced settings. Built-in controls should handle the majority of designs before custom CSS is considered.
A visual preview is useful, but production QA must include the actual website, responsive breakpoints, keyboard focus and overlap with consent or checkout elements.
What you will have at the end
- A brand-aligned theme and imagery
- A focused welcome flow with prompt buttons
- A copied floating-widget embed and verified live answer
Before you start
- Brand colors and accessible contrast targets
- Optimized logo/avatar files
- A staging or test page with the widget
Design, guide, verify
Appearance defines the visual system, Images add identity, Behavior controls the first interaction and Positioning prevents overlap. Advanced settings cover language detection, branding and CSS.
The floating widget reads its saved configuration live, so changes do not require a new embed code.
01–06
Set it up step by step
Set appearance, colors and font
Create a readable visual foundation.
Choose the widget theme, title and font, then set header, bot, user and button colors. Check text contrast in every bubble state rather than judging color swatches alone.
Add avatar, button and welcome images
Use small, purpose-specific assets.
Upload an avatar, optional custom chat button and welcome image. Use optimized square assets with clear silhouettes and verify that transparent edges work in light and dark page contexts.
Configure behavior and prompt buttons
Make the first useful question obvious.
Write a short welcome message and two or three prompt buttons tied to common visitor goals. Decide deliberately on sources, microphone, automatic translation, speech bubble and excluded paths.
Set desktop and mobile position
Avoid cookie banners and primary actions.
Adjust desktop and mobile X/Y offsets separately. Test the smallest supported viewport, mobile browser chrome and open cookie banner so the chat button never blocks navigation or purchase controls.
Preview and test on the real page
Verify open, close, prompts and keyboard use.
Use the dashboard preview, then test the embedded widget on the staging site with mouse, keyboard and touch. Verify welcome content, prompt actions, scroll behavior, focus order and the privacy notice.
Copy the floating-widget embed code
Install one script and the chatbot-specific custom element.
At the bottom of Widget Integration, copy the complete HTML block. It loads the WebChatAgent script asynchronously and renders the `web-chat-agent` element with the current chatbot ID. Paste it once before the closing `body` tag or into the site-wide custom-code area of your CMS.
Publish first to staging and inspect the browser console, consent behavior and allowed-domain setting. Saved visual changes are loaded by the widget automatically; you do not need to replace the snippet after every design edit.
Example & result
See the practical test and its result
Every tutorial includes a fixed input, the expected outcome and a transparent record of what was actually verified locally.
Practical example: How to customize the complete chatbot widget
This exact scenario was completed with the temporary tutorial account.
Exact test input
Change the title to “Tutorial Lab”, use a blue user bubble, copy the floating embed and open the live preview.
Expected result
The live widget reflects the design, the embed contains the correct chatbot ID and a real question receives a readable answer.
What was actually verified
The saved preview showed Tutorial Lab, the blue user-message color and a grounded answer; the complete asynchronous script and web-chat-agent element were verified in Widget Integration.
Tips & tricks
Make the setup reliable
Test with realistic examples, record your baseline and change one setting at a time. That makes real improvements visible.
Start with built-in controls
Use Custom CSS only for the remaining details; built-in colors and offsets are less fragile across updates.
Prompt buttons should express intent
“Compare plans” is clearer than “Learn more” and gives the chatbot useful context immediately.
Test content before polishing the shell
A beautiful widget cannot compensate for missing knowledge. Verify the most important answers first, then finalize welcome text, prompts and visuals.
Choose the model for the conversation, not the colors
Use a fast, economical model for routine support and compare a stronger model only when fixed test questions show a measurable quality gain.
When something does not work
Troubleshooting
Check status, permissions and test data systematically before changing the model or prompt.
The expected option is missing
Confirm the account plan, feature permissions and selected chatbot. Paid or beta features can be hidden when prerequisites are not met.
The test result is inconsistent
Reset the test conversation, keep the input identical and change one setting at a time so the cause remains measurable.
Ready for a production-style test
Publish the design to a staging page, collect screenshots at desktop and mobile widths and record a short accessibility and overlap checklist before production rollout.