Customer enquiries
Website chatbot integration
Embedded Support Chatbot is a working name used for this write-up. The client isn't identified, so their actual product name isn't either.
A customer-facing chat widget dropped into a site someone else built — answering from that site’s own pages, and handing over to a human when it should.
Build effort, not elapsed calendar time. Engagements ran alongside study and employment, so this figure is the work itself rather than the span it sat in.
Interface built in code for this case study — not a client screen capture.
01Business problem
A business wants a chatbot on the site it already has. Nobody wants to rebuild the site to get one, and nobody wants a bot that confidently answers questions about their pricing incorrectly.
Who feels it
The request arrives in the same shape every time: there is an existing site, built by someone else, maybe on a platform nobody has the credentials for any more, and the owner wants visitors to be able to ask questions instead of hunting through pages. Enquiries currently arrive by phone during opening hours and by contact form the rest of the time, and the same six questions account for most of them.
The constraint that makes this an integration problem rather than an AI problem is that I do not control the host page. I get one script tag. Whatever I ship has to survive the site’s existing CSS, not fight its z-index stack, not shift its layout, not slow its Lighthouse score enough for anyone to notice, and not break if the site is later edited by someone who has never heard of me.
The second constraint is that a wrong answer is worse than no answer. If the widget invents a price, a delivery time or a warranty term, the business inherits that claim in front of a customer. That risk is the reason most of the engineering here is about refusing to answer, not about answering.
02Product overview
One script tag, a widget isolated from the host page in a shadow root, answers grounded in the client’s own pages with a citation, and a handover to a real channel the moment the question stops being routine.
Engineering notes
The embed is a single deferred script under three kilobytes. It renders nothing on load — it registers an idle callback and a click target, and the widget itself is only fetched when a visitor actually opens it or after the page has been quiet for a few seconds, whichever comes first. Until then the host page pays almost nothing.
Everything the widget renders lives inside a shadow root with its own styles, so the host site’s stylesheet cannot leak in and my styles cannot leak out. This is the part that decides whether an embed is a support burden or not: without isolation, every future edit to the host site is a potential visual bug in my widget, and I would be debugging someone else’s CSS for free indefinitely.
Answers come from the client’s own content, chunked from their pages and indexed at build time, never crawled live. Each answer carries the page it came from as a visible link. When retrieval returns nothing relevant enough, the widget says it does not know and offers the handover instead — that path is not a failure state, it is the designed behaviour for roughly a third of real conversations.
Handover means the conversation so far is attached to a WhatsApp deep link or an email draft, prefilled, so the visitor does not retype their question and the business does not start from nothing. If the model service is unreachable, the widget degrades to that same handover form and shows no error, so a bad day upstream looks like a contact form and not a broken site.
03Key features
8 capabilities, of which 2 are model-backed. The rest are ordinary deterministic software, and the distinction is marked so the AI claim stays honest.
A single deferred script with data attributes for the account and accent colour. No framework assumption, no package to install, nothing that requires access to the host site’s build pipeline — because there usually is not one.
The widget renders inside a shadow root with its own stylesheet. The host page’s CSS cannot reach in and reset a button; my CSS cannot reach out and restyle their headings.
Nothing renders until idle or intent. The launcher is fixed-position and reserves no document space, so the host page’s cumulative layout shift is unchanged.
Every response links the page it was drawn from. A visitor can check the claim in one click, and the business can see which page a wrong answer came out of.
Below the relevance threshold, the widget says it does not know and offers a person. Pricing, legal and warranty questions are routed to a human regardless of retrieval score.
WhatsApp deep link or a prefilled email, carrying the transcript so far. The visitor does not repeat themselves and the business does not start cold.
If the model endpoint is unreachable, the widget shows the handover form instead of an error. An outage upstream looks like a contact form to a visitor.
Focus moves into the panel on open and returns to the launcher on close, Escape closes, new messages are announced through a live region and never silently appended.
04User flow
The path from the trigger to the finished record, with each step attributed to whoever performs it — a person or the system.
05Architecture
The processing path first, then the layers it runs on, then the constraints that shaped both.
Path through the system
A deferred loader script resolves the account config and attaches a launcher. It registers listeners and returns; the widget bundle is a separate request that has not happened yet.
First click, or an idle callback after the page settles, fetches the widget bundle and mounts it into a shadow root. The launcher is interactive before the bundle exists, so an early click is queued, not dropped.
The question is embedded and matched against chunks built from the client’s own pages at index time. Top matches come back with their source URL and a similarity score.
Below the score threshold the model is never called — the refusal is cheaper, faster and safer than asking a model to be honest about not knowing.
The model sees only the retrieved passages and is instructed to answer from them alone. The source link is attached from the retrieval result, not from anything the model produced.
Handover builds a WhatsApp deep link or mailto with the transcript, truncated to fit URL limits, oldest messages dropped first.
Layers
Why it is shaped this way
06Technical decisions
Every decision here was contested by a reasonable alternative. The trade-off column is the part usually left out.
Why
An iframe isolates perfectly but cannot overlay the page cleanly, needs postMessage for every resize, and behaves badly on mobile keyboards. A shadow root gives isolation while staying in the host’s layout.
Trade-off
Styles have to ship inside the root, not through a stylesheet link, and a few host-level properties — font smoothing, reduced motion, colour scheme — still inherit and have to be handled explicitly.
Why
Answers stay fast and stay available even when their site is slow. It also makes the corpus reviewable: the business can see exactly what the widget is allowed to answer from.
Trade-off
Content changes are not reflected until the next index run, so a price change on their site can be stale in the widget. The mitigation is that pricing questions escalate to a person regardless.
Why
A model asked to say "I do not know" will still sometimes answer. A threshold check in code cannot be talked out of it, and it costs nothing to run.
Trade-off
The threshold is a blunt instrument and will occasionally refuse a question the corpus could have answered. For a customer-facing widget on someone else’s brand, that is the right direction to be wrong in.
Why
The businesses asking for this already run on WhatsApp. Introducing a helpdesk they would have to check daily would have quietly broken the whole flow.
Trade-off
No queue, no assignment, no SLA tracking — and no history beyond the owner’s phone. If volume grew, this is the first thing that would need replacing.
07Challenges
Not the setup work. These are the problems where the first implementation was wrong and had to be reconsidered.
Approach
Moved from a plain div mount to a shadow root with an adopted stylesheet, then audited which properties still inherit through the boundary and set them explicitly at the root.
Outcome
The widget now looks the same regardless of the host stylesheet, and a later redesign of the host site required no changes on my side.
Approach
The loader attaches its own listener immediately, records that intent, and replays it once the bundle mounts, with the launcher showing a loading state in the interim.
Outcome
An early click now opens the panel as soon as it is ready instead of being swallowed — the failure that would otherwise read as "the chat is broken".
Approach
Sized the panel against the visual viewport, not the layout viewport, locked host scroll while open without changing body position, and restored scroll offset on close.
Outcome
Typing on a phone no longer moves the page underneath, and closing the widget returns the visitor to exactly where they were.
Approach
Budgeted the transcript against a conservative length limit, dropping the oldest turns first, keeping the visitor’s most recent question intact, and marking that earlier context was omitted.
Outcome
The handover always arrives readable, with the newest and most relevant part of the exchange preserved.
08Business value
Stated qualitatively on purpose. Invented percentages are the easiest thing to put on a portfolio and the easiest thing to see through.
Operational effect
What would change at scale
09Interface
Dense operational views rather than dashboards. These are used for hours at a time, so the priorities are legibility, keyboard flow and state that is never ambiguous.
Widget panel
The visitor-facing conversation, with the source page shown under a grounded answer.
Refusal path
A question the corpus cannot support, declined and offered to a person — the behaviour for about a third of real conversations.
Retrieval trace
What the widget matched against and with what score — the only way to judge whether an answer was earned.
Handover
The prefilled message the business receives, with the transcript carried over.
The screen above is built in HTML and CSS for this case study. It reproduces the layout, states and vocabulary of the real build without exposing client data, which is why it exists rather than a screenshot. It is evidence of design and of the decisions behind it. It is not a photograph of a deployed system, and no part of it is a capture of anyone else’s product.
10Technologies
Chosen for the shape of the problem, not for novelty. Anything unusual is justified in the decisions section above.
Implementation detail
11Technical preview
There is no repository link on this site. What is available instead is the module structure, the data model, the interface contracts and annotated excerpts written for this case study — enough for a technical reviewer to judge the engineering.
Technical preview
Selected implementation details are available for technical review: component structure, data models, architecture notes and sanitized code excerpts. Some client-specific source material stays private because of confidentiality. Enter the project access keyword if you have been given one — the same one works across every case study.
A presentation convenience, not authentication. This is a static site, so the keyword ships to your browser with the page and anyone reading the bundle can find it — worth saying plainly rather than dressing it up. Nothing confidential is stored behind it.
Inside this section
For private client work, contact me for a walkthrough.
Next step
Send the process, the constraints and the deadline. You will get an honest scope, an architecture sketch and a timeline before any commitment.