Chatbot
Build a site chatbot
A question is matched to pages already on this site. A small model answers from those excerpts and the reply links back. Accept comes first. The question is not stored.
Understanding the labHow to use it and why you'd want to
Why you'd want to
You want an assistant that answers from pages you already published. It should show the source and not store the question.
How to use it
- Accept measurement, then ask a starter or type a question.
- Watch the stages, then open Track for the event list.
- Read the excerpts and open a source link.
- Open How we built it for the code and the event map.
WalkthroughHow we built itShowHide
Example vendor setup is marked below. eVar and event numbers are examples. This lab does not call Adobe.
The chatbot lab asks the same /api/chat route as the corner assistant. Retrieval picks excerpts from the labs, the How we built it tables, and the notes. A small model answers only from those excerpts when AI_GATEWAY_API_KEY or the Vercel OIDC token is set. Otherwise the route quotes the closest page. After Accept, both surfaces push chat events to dataLayer. The question and the answer are not parameters. This lab does not call Adobe.
Load the assistant only after Accept
ChatGate renders nothing until consent is granted, then imports the chat chunk. Decline and a missing choice leave the corner empty. The lab’s Try it panel uses the same gate and does not call the route before Accept.
Search an index built from the repo
chatIndex reads the walkthrough prose, the example Adobe and GA4 rows, and the blog notes when the module loads. retrieve scores the question against that text and returns the top chunks with their URLs. It does not call the model.
Ground the model on those excerpts
The system prompt says to use only the excerpts, to skip invented numbers, and to answer in Spanish when the question is Spanish. The route sends the excerpts. It does not send a secret, and it does not log the prompt.
Refuse a live property
asksAboutLiveAccount stops questions about a live Launch property, a live GA4 property, or an account before any model call. The example Adobe column on this page is still allowed. The refusal says the tables are examples.
Cap the route and fail in the open
allowChat stops the ninth question from one IP inside ten minutes on that instance. A firewall rule in front is the durable cap. If the model errors, times out, or the key is missing, the route returns the opening of the closest page and the source links.
Push the event, not the message
After Accept, trackChatEvent pushes a dataLayer object and returns without pushing when consent is off. It does not call gtag for these events. chat_open, starter_used, question_asked, answer_shown, and source_clicked fire on the corner and on this panel. chat_close fires when the corner panel closes. The question and the answer are not fields.
From the code
The corner assistant is imported only after Accept.
export function ChatGate() {
const { consent } = useConsent()
const [Chat, setChat] = useState<ComponentType | null>(null)
useEffect(() => {
if (consent !== "granted") return
let cancel = false
void import("@/components/chat/site-chat").then((mod) => {
if (!cancel) setChat(() => mod.SiteChat)
})
return () => {
cancel = true
}
}, [consent])
if (consent !== "granted" || !Chat) return null
return <Chat />Length and latency become buckets. The question text and the millisecond count are not sent.
/** 1–80 characters is short, 81–200 is medium, 201 or more is long. */
export function questionLengthBucket(length: number): QuestionLength {
const size = Number.isFinite(length) ? Math.max(0, Math.floor(length)) : 0
if (size <= 80) return "short"
if (size <= 200) return "medium"
return "long"
}
/** Under 2 seconds, 2 through 5 seconds, or over 5 seconds. */
export function latencyBucket(ms: number): LatencyBucket {
if (!Number.isFinite(ms) || ms < 2000) return "under_2s"
if (ms <= 5000) return "2_5s"
return "over_5s"
}The Gateway call. The key stays in the environment. Telemetry is off so the prompt is not exported.
try {
const result = streamText({
model: gateway(chatModelName() as GatewayModelId),
system: systemPrompt(language),
prompt: userPrompt(question, chunks),
maxOutputTokens: 450,
maxRetries: 0,
abortSignal: AbortSignal.timeout(12_000),Google and Adobe
Google queues chat_open after Accept. Adobe is an example of the same fields.
After Accept, the corner assistant and this Try it panel push these objects with dataLayer.push. They do not call gtag for these events. chat_open, starter_used, question_asked, answer_shown, and source_clicked fire on both surfaces. chat_close fires when the corner panel closes. The lab panel stays on the page, so it does not push chat_close. Every object includes chat_surface and chat_locale. The question, the answer, and the IP are not parameters. Register chat_surface, chat_locale, chat_starter_id, chat_question_length, chat_status, chat_latency_bucket, and chat_source_path as event-scoped custom dimensions, and chat_source_count as an event-scoped custom metric. This site does not call gtag('set') or Adobe.
Pushed when the panel is available after Accept. No further fields.
dataLayer.push({
event: "chat_open",
chat_surface: "lab",
chat_locale: "en",
})The starter id only. Not the sentence on the chip.
dataLayer.push({
event: "starter_used",
chat_surface: "lab",
chat_locale: "en",
chat_starter_id: "datalayer",
})short is 1 to 80 characters, medium is 81 to 200, and long is 201 or more.
dataLayer.push({
event: "question_asked",
chat_surface: "lab",
chat_locale: "en",
chat_question_length: "short",
})ok, fallback, or refused. The count is an integer. The bucket is under_2s, 2_5s, or over_5s.
dataLayer.push({
event: "answer_shown",
chat_surface: "lab",
chat_locale: "en",
chat_status: "fallback",
chat_source_count: 2,
chat_latency_bucket: "under_2s",
})The pathname only. The query string is not included.
dataLayer.push({
event: "source_clicked",
chat_surface: "lab",
chat_locale: "en",
chat_source_path: "/lab/datalayer",
})The corner panel sends this when it closes. The lab panel does not.
dataLayer.push({
event: "chat_close",
chat_surface: "corner",
chat_locale: "en",
})Example implementation. This site does not call Adobe. eVar118, prop118, and event118 are example variable numbers. In Launch, a data element reads the value and a rule sends it when the value changes. In the report suite, enable eVar118 with Most Recent allocation and expire it on the hit. A processing rule is unnecessary if the data element maps straight to that eVar.
Example alloy payload. _example is a placeholder schema, not a real tenant.
alloy("sendEvent", {
xdm: {
eventType: "web.webinteraction.linkClicks",
_example: {
chatSurface: "lab",
},
},
})Example hit. eVar118 is hit-scoped in this example. prop118 dies at the same hit.
s.eVar118 = "lab"
s.prop118 = "lab"
s.events = "event118"
s.linkTrackVars = "eVar118,prop118,events"
s.linkTrackEvents = "event118"
s.tl(true, "o", "chat_open")Translation
Each lab field, the GA4 name, and the example Adobe variable. Scope is the part that usually gets lost in the translation.
Chat opened
GA4. Event chat_open after Accept. Parameters are chat_surface, corner or lab, and chat_locale, en or es.
Adobe. Example event118. Example eVar118 could hold chat_surface. This site does not call Adobe.
Scope. Event. A user property would remember that the chat was opened.
Starter used
GA4. Event starter_used. chat_starter_id is datalayer, beacon, utm, or adobe. Also chat_surface and chat_locale. Not the starter sentence.
Adobe. Example eVar118 for the starter id, Most Recent, expire on the hit. This site does not call Adobe.
Scope. Event. The id is enough. The sentence is already on the page.
Question asked
GA4. Event question_asked. chat_question_length is short, medium, or long. short is 1 to 80 characters, medium is 81 to 200, and long is 201 or more. The question text is not sent.
Adobe. Example prop118 with short, medium, or long. Do not put the question in a prop. This site does not call Adobe.
Scope. Event. A user property would keep the last length bucket after the next question.
Answer shown
GA4. Event answer_shown. chat_status is ok, fallback, or refused. chat_source_count is an integer. chat_latency_bucket is under_2s, 2_5s, or over_5s. The answer text is not sent.
Adobe. Example prop118 for chat_status and example event118. This site does not call Adobe.
Scope. Event. A user-scoped status would stick after the next answer.
Source clicked
GA4. Event source_clicked. chat_source_path is a pathname such as /lab/datalayer. Also chat_surface and chat_locale. Not the question.
Adobe. Example eVar118 for the path, expire on the hit. This site does not call Adobe.
Scope. Event. The path is a page on this site, not a profile trait.
Chat closed
GA4. Event chat_close when the corner panel closes. Parameters are chat_surface and chat_locale only. The lab panel does not send it.
Adobe. Example event118. This site does not call Adobe.
Scope. Event. A user property would remember that the panel was closed.
Try it
This panel calls POST /api/chat, the same route as the corner assistant. The stages below light up as the answer arrives. Excerpts are the retrieved pages. The prompt and the key stay on the server.
Accept measurement to ask a question. Until then this panel does not call the route.
- Question
- Retrieval
- Excerpts
- Model
- Answer
Events fired
0 this tab
Accept measurement before these events are pushed. Decline and a missing choice push nothing.
Build your own
- Install the AI SDK and call the AI Gateway with a small model, such as gpt-4o-mini.
- Set AI_GATEWAY_API_KEY on the host. The page never prints the key.
- Build an index of your pages when the server starts, and keep each chunk’s URL.
- Send the model only the top excerpts, and tell it to answer from those.
- Refuse a question about a live Launch property, a live GA4 property, or an account.
- Rate-limit the route and add a firewall rule. Do not log the question or the answer.
- Load the assistant only after the visitor accepts measurement.
- After Accept, push chat_open, starter_used, question_asked, answer_shown, source_clicked, and chat_close to dataLayer. Send chat_surface, chat_locale, and the event’s own fields. Never send the question or the answer, and do not call gtag for these events.
Recommended next
Why these picksReading path transitions…