The widget
One script tag, installed once. Show nothing and carry feedback from your own agent, or the whole help corner: surveys, messages, search, the assistant and a person. Everything is set in FunctioningHQ.
One script tag, installed once. What it shows, how it looks and what it gathers are set in FunctioningHQ under Settings › Help widget and reach every page with the snippet on its next load — your developers never touch it again. It can show nothing at all and only carry feedback from your own AI agent's chat, or it can be the whole help corner: surveys, messages you approved, the assistant and a way to write to a person.
<script src="https://app.example.com/widget.js" data-key="saw_…" async></script>
That is the whole snippet. There is no module list, preset, color or option in it, and there never needs to be.
The core and its modules
The script is a small core that runs in your page (about 5 KB gzipped, with the loader that fetches it) and modules, each with a manifest that says what it gathers, what it shows, what it needs and what it costs (lib/widget/modules):
| Module | Gathers | Shows | Costs |
|---|---|---|---|
| Feedback (always on) | Ratings, "this didn't help", asking for a person, a note — for your own agent's conversations | Nothing | No model call |
| Surveys | Answers to questions you approved: "did this fix it?", satisfaction, effort | One card with the question, when one is waiting | No model call |
| Messages | Whether the people you messaged read it | A card with a message you approved | No model call |
| Assistant | Questions, the answers given, whether each helped | A question box answered in a conversation from what you keep for answering customers; while it is off or its allowance is spent, the box searches your articles instead | A model call per question, from its own allowance; searching costs nothing |
| Message a person | Questions, feedback and problem reports, and their answers to your replies | A message box, and their conversations with your team | No model call |
Four presets name the usual sets: Collect only (feedback, no interface), Surveys, Surveys and messages, and Everything. Any other mix is yours to toggle. The core fetches the interface (an iframe on our origin) only when a module that shows something is on, so with Collect only a page view costs the core and one cached request.
A module is what the widget shows, never a permission. The assistant answers only when it is turned on under What happens without asking; a survey or a message reaches somebody only after a person approves its exact words and the contact rules allow it; a plan without the widget refuses every module. Turning a module off hides it and grants nothing back: a follow-up its module does not show is not marked read, and expires unseen — counted as such on its play, never as delivered. With the messages module off (and surveys off), a play cannot send an in-widget message at all: it reads "available if" the module is turned on.
A widget saved before modules existed shows Everything, which is what it showed then. Nothing an older snippet relied on has gone.
How the config reaches your page
The core reads GET /api/widget/config?key=<key id> at load: the published config, with a version (a digest of all of it) and the public API version it speaks. It is kept five minutes at the edge (then served stale for a day while it refreshes) and not at all in the browser, and every save in FunctioningHQ deletes it from the edge, so a change reaches a page on its next load. If the config cannot be fetched the core asks once more after thirty seconds; until it arrives nothing is shown and nothing is captured, and feedback sent with FunctioningHQ('feedback') still goes.
The core and the interface load from our origin by version (a hash of their contents, cached for a year), and /widget.js is cached for five minutes, so a new module or a fix reaches every installed site without anybody touching it.
An older snippet that carries options of its own (data-button-label, data-accent, data-side, data-assistant-first, data-launcher, data-theme) keeps working. Where the same option is set in FunctioningHQ, FunctioningHQ's wins; where it is not, the attribute still applies, so a site styled in its snippet before anything was saved looks as it did. data-version and data-open are still read where present.
Colors are light, dark, or the visitor's own device setting (Settings › Help widget). Light is the default, so no installed widget changes by itself. The device setting is read in the host page and handed to the frame, because inside a frame prefers-color-scheme follows the frame element rather than the visitor; it is read when the widget loads.
A site with a Content-Security-Policy allows the app's address in script-src, connect-src (the core's config and feedback requests) and frame-src (the interface).
The public API, version 1
FunctioningHQ.v is 1. A version adds commands and never removes or changes one, so a call your page makes today keeps working. The page global is FunctioningHQ, and it is the only one:
| Call | What it does |
|---|---|
FunctioningHQ('open', question?), 'close', 'toggle' | Open the box, where the workspace shows one |
FunctioningHQ('identify', tokenOrFunction), 'logout' | Say who is signed in (below) |
FunctioningHQ('feedback', item) | Report feedback on your own agent's answer (below) |
Calls made before the script has loaded are queued and run when it does.
Feedback from your own agent
If you built your own support AI, the thumbs, the "this didn't help" and the "talk to a person" button in its chat are the evidence of whether its answers worked. There are three ways to send them, and the same shape for all three:
FunctioningHQ('feedback', { conversationId: 'conv_123', kind: 'rating', rating: 'up' })
FunctioningHQ('feedback', { conversationId: 'conv_123', kind: 'not_helpful', text: 'It skipped step 2' })
FunctioningHQ('feedback', { traceId: '4bf92f3577b34da6a3ce929d0e0e4736', kind: 'escalated' })
| Field | |
|---|---|
conversationId | Your id for the conversation, as your agent sent it to us (signals API or OpenTelemetry) |
traceId | Or the OpenTelemetry trace id of the answer, which we keep from your traces |
kind | rating, not_helpful, escalated, copied, source_opened or comment |
rating | For a rating: up, down, or a whole number from 1 to 5 |
text | What the person wrote. Redacted before it is stored |
url | For source_opened: the address opened. Only its path is sent, and it is only counted |
at | ISO 8601. Defaults to now |
Each becomes what the product already has, never a new kind of record:
- A rating is the customer's rating of the AI's answer, out of five (a thumb is five or one). It counts in the satisfaction vitals as the customer's own word, and at two or under it is a low rating like a helpdesk's.
- "This didn't help" counts against the answer: the conversation reads as a resolution that did not hold, it joins the patterns, and on a traced answer it is what the failing part is read from.
- Asking for a person is recorded as your agent handing the conversation over: your record, stored the way a vendor's AI outcome is.
- A note is kept, redacted, as the remark on the rating.
- A copy of the answer and a cited source opened are counted on the conversation and shown on its page. Neither is a verdict.
Feedback joins a conversation you already sent us, and nothing else: by your id for it under any of your ingest keys' sources, or by the trace of an answer in it from the last thirty days. A helpdesk's conversations and the widget's own are never reachable from here, and from the page only a conversation an AI answered in is. Feedback for a conversation that has not arrived stores nothing and comes back as unknown; the core in the page sends it again after twenty seconds and after two minutes, then drops it. Feedback is batched (a second after the last, at twenty, or as the page goes), and POST /api/widget/feedback is rate limited per address and per workspace like every widget route.
From your server, send the same items as feedback in a signals batch, or as functioninghq.feedback.* attributes over OpenTelemetry — see Sending signals.
Without code: point us at your controls
Under Settings › Help widget › Feedback from your own agent, say where the conversation's id is — a data attribute on the page (data-conversation-id), a parameter in the address, or a global (chat.conversationId) — and give a CSS selector for each control you want counted: thumbs up, thumbs down, "this didn't help", "talk to a person", the element that holds an answer (for copies), and the same for cited sources opened. The core listens for exactly those, from the next page load.
- Opt-in per signal. Each is off until it has a selector. None is on by default.
- No page text. What is read is the id where you said it is (on the control or an element around it — the page is never searched for it), and for a link its address without the query. Never the words of an answer, what was copied, or anything typed. A free-text note needs the JS API, because only your page knows which box holds one.
- A selector can break. When your front end renames a class, the capture stops and nothing fails. So once feedback has arrived from your page, seven days without any reads as a connection that may have broken, and the person who looks after connections is told once, like any source that went dark.
- Test it. Paste a piece of your page on the settings page to see what each selector matches and which conversation it joins, read in your browser and sent nowhere; or add
#functioninghq-testto your page's address, and the widget outlines what each selector matches and logs to the console what it would send, sending nothing.
Help, feedback and the assistant
What the box does, where its modules are on.
A small script you put on your site, and a hosted form if you do not want to install anything. Both collect questions, feedback and problem reports. Those become the same conversation rows a helpdesk sync produces, and from there the loop is identical: findings, problems, experiments, measurement.
The widget's one action is an approved follow-up shown in-widget ("this is fixed", "did it help?"). Nothing is shown until a person approves the exact text. A widget key can only submit widget signals; it cannot dump conversations through POST /api/signals, start a playbook, or read anything back.
The widget is one assistant box: ask the assistant, or send a message a person reads. The assistant is off until the workspace turns it on under Settings › Help widget (it is an autonomy setting underneath, and shows under What happens without asking too). Searching is its fallback rather than a mode of its own: while the assistant is switched off or has spent its allowance, the same box searches your articles, which costs nothing. See "The assistant" and "Searching, when the assistant cannot answer" below.
What a visitor sees
One box that grows sideways. Closed, it is a pill in the corner carrying the button label, filled with the accent. Opened, the same element widens in place to 520px: the conversation above, oldest first and pinned to the newest turn, the question field at the bottom. An answer reads as a conversation: no citation, chip or quoted passage under it, only "Read the full article" where it answered from an article you published publicly, and "Did this answer it?". Anything the assistant could not answer, a No, or "Leave it for a person" opens a longer message box in place, with the question already in it. When the assistant is off, or its allowance is spent, the box searches instead — your articles for answering customers, no model, nothing spent — and the message box is one link away; where nothing is written down at all, it opens on the message box with the three kinds as chips. The footer names the modes you are not in, so moving between them is one press and the words you typed come with you.
An approved follow-up is looked for on page load, and only when the browser holds a visitor token. It shows once: as one line above the pill, with a dot on the pill, and as a note at the top of the conversation.
Setting it up
Settings › Help widget is the one page, in three panels: let it answer (the assistant and its daily cap), make it fit your page (the four options beside a live preview), and put it on your site (the key and the embed). The first two have no Save button; every control writes on change. The preview is the shipped /widget.js on a blank page, opened, identified by the workspace's help slug rather than a key, so a question typed there is a real question against the real help pages.
Options
Set under Settings › Help widget and published with the rest of the config, where they win over an older snippet's attributes. Six, and no more (lib/widget/settings): the button label (at most 24 characters), an accent color (a six-digit hex; it fills the button and underlines links, and the text on it is chosen for contrast — it is never a text color on paper), the side of the page, whether the assistant is offered before the form when it is on, the launcher (the corner pill, or none), and the attribution: a small "Powered by FunctioningHQ" mark in the footer of the box, linked to our site, on by default and off by choice (only the setting turns it off, never a snippet). Stored on the control-plane tenant row and read by the embed through GET /api/widget/config on every page load, so no workspace database is opened per visitor. Cached at the edge for five minutes.
The home screen
Under Settings › Help widget › Home screen, five things make the widget's first screen your own. Each is optional, and the widget looks right with none of them:
- Your logo, in the widget's header and beside your team's replies, in place of our shield. Upload a PNG, JPEG or WebP; it's cut to a 128-point square in your browser. Pages fetch it from its own address (
/api/widget/logo), cached until you change it, so it adds nothing to what every page of your site loads. - What the button to a person says, in place of "Message the team" (up to 28 characters).
- When you reply, in your words ("We usually reply within a day"), beside that button and on the form. Left empty, nothing is said.
- A banner: one line at the top of the home screen, with an optional
httpslink, for an outage or a holiday. Give it a last day and it goes by itself. - Up to four pinned articles, under the search box as "Popular articles". Only articles your customers may read that you publish publicly can be pinned, the same ones search would show. Their titles and addresses are read again whenever your knowledge changes, and one that's no longer published drops off.
Custom fields on the message form are not offered. Each one is more of your customers' words to redact, keep and delete.
Your own button
With the launcher set to none there is no pill; the site opens the widget itself. Either works with the pill too:
<a href="#" data-functioninghq-open>Contact support</a>
<button data-functioninghq-open="How do I change my plan?">Ask about plans</button>
<script>FunctioningHQ('open')</script>
A value on data-functioninghq-open is put in the question box. FunctioningHQ('close') and FunctioningHQ('toggle') also work, and calls made before the script finishes loading are queued by the loader and run when it does. Without a pill, anything the widget starts on its own — an approved follow-up, and later a survey question — still appears in the corner.
Knowing who is asking
Optional, under Settings › Help widget › Know who is asking. Without it a visitor is a random token in one browser and an email they typed. With it, the site vouches for the signed-in person, so what you approve for them reaches them on any device, and nobody can ask as them by typing their email.
Two ways, and a workspace may use both (lib/widget/identity):
- A signing secret. Create one on the settings page (it is shown once). The site's server signs a short-lived HS256 token with
subset to its user id:
const token = await new SignJWT({})
.setProtectedHeader({ alg: 'HS256' })
.setSubject(String(user.id))
.setIssuedAt()
.setExpirationTime('10m')
.sign(new TextEncoder().encode(process.env.FUNCTIONINGHQ_WIDGET_SECRET))
- The site's own sign-in provider. Enter its OpenID issuer (and audience, if its tokens carry one). The issuer's keys address is discovered once, on save; both must be public https names. The widget is handed the token the app already has and it is checked against those published keys. No secret is held.
On the page, hand the widget a token, or better a function that returns a fresh one, which it calls when it needs to:
FunctioningHQ('identify', () => fetch('/api/support-token').then((r) => r.text()))
FunctioningHQ('logout')
A token must name a subject (sub), be current, and expire within a day. The secret path accepts only HS256 and the provider path only RS256, ES256 or EdDSA, so neither can be passed off as the other. The token travels in the body of the widget's requests — never a header, never storage — and each of POST /api/widget, /api/widget/answer and /api/widget/inbox checks it before anything is stored, answering 401 identity_invalid when it fails. The embed then asks for a token once more and, if that fails too, carries on as for anyone not signed in. A verified sub is hashed like every other person (widget-user:<sub> under the participant salt) and replaces any typed email; neither the id nor an email is kept. Put the person's email in the token too and it is asserted together with the subject: the widget conversation joins the person that email already names, from an inbound message or a helpdesk contact. A token with email_verified: false vouches for no email. A typed email is never joined to anyone.
Embed
<script src="https://app.example.com/widget.js" data-key="saw_…" async></script>
Create the key under Settings › Help widget. It is shown once, inside the snippet.
An older snippet may carry data-version, your app version; the widget still copies it onto every submission, and a new snippet needs none.
Where it runs
The widget runs in an iframe on our origin (/widget/frame/<version>), sized to what it shows in the corner, so the host page's styles cannot reach it and its visitor tokens are out of reach of the host page's scripts. The host page keeps a small script (/widget/<version>.js, loaded by /widget.js) that reads the allowlisted context below and hands it to the frame when a request needs it, holds the site's sign-in token function, takes FunctioningHQ() commands and data-functioninghq-open clicks, and sizes the frame. The two talk only to each other: the host script posts only to our origin and accepts only the frame's window; the frame accepts only its parent. The frame page may be embedded by any site and may load only our scripts and call only our API. It is fetched when the page is idle, or at once when something opens it.
In a mobile app
The same widget runs in an app. The app's WebView opens /widget/app?native=1: the frame page at an address that does not change, short-cached, so a fix reaches every installed app the next time the widget opens, with no app release. The page talks to the app through a bridge the app installs (React Native's, a WKScriptMessageHandler named functioninghq, or an Android JavaScript interface named FunctioningHQAndroid). It sends the same messages it sends a host page, and the app answers by calling window.__functioninghq(message). That function exists only in a top-level document opened with native=1, so nothing on the web can reach it. In an app the box fills the screen the app shows it in, and there is no launcher: the app opens it from its own button.
An approved message, a survey question or a reply from your team pops up, as the corner card does on a website: a panel along the bottom of the screen, as tall as the card, with the rest of the app usable above it. The question is answered on the card, and tapping "Read it" or a reply opens the box. A follow-up aimed at a page shows only on that screen. The card rests above the bottom safe area, and an app with its own tab bar sets cardBottomInset to its height so the card sits just above it. While closed, the widget stays loaded in the app (one clear point when there is no card), so a reply arrives while the app is open, and it looks again whenever the app comes back to the foreground. An app where a pop-up would get in the way (in the middle of checkout, say) can switch it off (showFollowUps: false). Nothing is then fetched until the person opens the widget, so nothing counts as seen before they see it. The app is told, in counts only, how many replies and follow-ups are waiting, so it can badge its own help button either way. Links open outside the app. The app keeps the visitor tokens in its own secure storage and hands them back each time.
A screen is reported as app://<app id>/<screen>. Its path is masked and matched exactly like a website's page path, so a follow-up aimed at /billing shows on the billing screen. Presence counts the app being in the foreground, the way it counts a visible tab.
For React Native and Expo, @functioninghq/react-native does all of this (packages/react-native). It runs in Expo Go and needs no config plugin:
<FunctioningHQProvider widgetKey="saw_…" appId="com.acme.shop" screen={pathname}>
{children}
</FunctioningHQProvider>
useFunctioningHQ() gives open, close, toggle, identify, logout, feedback and waiting.
Apps written natively have their own packages, with the same calls and no dependencies:
- iOS (
packages/ios), a Swift package for iOS 15 and later. It keeps the visitor tokens in the Keychain and shows the widget full screen.
FunctioningHQ.shared.configure(widgetKey: "saw_…")
FunctioningHQ.shared.screen = "/billing"
FunctioningHQ.shared.open()
- Android (
packages/android), a Kotlin library for Android 7.0 and later. It keeps the visitor tokens in the app's private storage, shows the widget in a full-screen dialog, and the back button closes it.
FunctioningHQ.configure(application, widgetKey = "saw_…")
FunctioningHQ.screen = "/billing"
FunctioningHQ.open(activity)
None of the three packages is published yet. Flutter and push notifications for replies are not built yet.
Presence and limits
With Upstash configured (.env.example), the frame tells POST /api/widget/presence it is on a page once a minute while its tab is visible, and that it left as the page goes. That gives People "online now", the page a person is on, and when they were last seen, so a follow-up can later be aimed at somebody who is here. It is not analytics: the page is kept as its path only (no query, fragment, email or opaque id), only while the visitor is online; an anonymous page session is forgotten when it stops; a person's last-seen time is kept at most 90 days and removed on erasure; nothing counts page views. A heartbeat opens no database.
The same store rate limits every public widget route per workspace and client address (hashed), with a sliding window generous for a person and small for a script (lib/widget/presence-model WIDGET_LIMITS); a limited request gets 429 rate_limited. Without the store, presence is off and nothing is limited.
What a page view costs
/widget.js is a loader of a few hundred bytes, cached for five minutes. It copies its data attributes onto a script tag for the versioned bundle, /widget/<version>.js, and loads it asynchronously. The version is a hash of the bundle's contents, so the bundle is cached for a year and a deploy changes its address rather than its contents.
The core then asks GET /api/widget/config?key=<key id> — the public half of the key, and no Authorization header, so there is no CORS preflight and the answer is cached at the edge for five minutes (served stale for a day while it refreshes), tagged with the workspace. Saving an option deletes that tag, so it reaches visitors on their next page load; if the delete ever fails, within five minutes. The key id alone can read only this display config; everything that writes or reads workspace data still needs the whole key. The config also says whether the assistant answers, mirrored to the control plane when that setting is saved, so opening the widget opens no database. Every widget route lets the browser reuse its preflight for a day.
Hosted form
/h/<your-help-slug>/ask — no script, no key. The public help index links to it. It is the same conversation at page scale. There is no separate form to look for a reply: an approved follow-up appears at the top of the conversation when the page opens, read by the visitor cookie on that help address.
The script can also be identified by the slug instead of a key (data-workspace="<your-help-slug>"); that is what the settings preview does. Either way it can do exactly what the hosted form can: submit, read approved follow-ups for a typed email, and ask the assistant.
What it reads from the host page
Only these:
| What | Where it comes from |
|---|---|
| Page URL | window.location.href |
| App version | data-version on the script tag |
| Last error text | window.__FUNCTIONINGHQ_LAST_ERROR__, if you set it |
| Recent product events | window.__FUNCTIONINGHQ_EVENTS__, an array of { name, at }, if you set it. At most 20. |
| A question to open with | data-functioninghq-open on the link or button a person clicked — that element only |
| Your conversation's id, for feedback | Only where you set capture up: the attribute, address parameter or global you named |
| A cited source's address | Only where you set capture up for sources opened: the link's address without its query |
What it never reads
Cookies, localStorage, sessionStorage, indexedDB, password fields, or anything else in the DOM beyond the attribute or link a capture you set up names. A key in the page is a widget-scoped key: it can submit a question, feedback or a problem report, and it can collect approved follow-ups for the email the person typed. It cannot post a conversation dump.
Replies
Somebody who writes to a person through the widget gets an answer. Their message opens a conversation your team replies to from its page in FunctioningHQ (For You lists everyone waiting, longest first), and the reply reaches them two ways:
- In the widget, under Your conversations, the next time they open it on any page with the snippet — or straight away, if they are on one, at the next heartbeat. They can write back there, and say whether it answered them.
- By email, to the address they gave when they wrote (or the one your sign-in vouched for, where you [identify](#knowing-who-is-asking) visitors). Replying to that email adds to the same conversation.
Somebody your site hasn't signed in always gives an email for the reply: the widget asks for it before Send, and POST /api/widget refuses a message without one (email_required). Without it, a person who wrote once and left was answered into a widget they never opened again. A signed-in person is known by your site's token and isn't asked.
Somebody who chooses Message the team says what it is: a question (the default), feedback, or something broken. Somebody handed over from the assistant or search asked a question, so it goes as one, with nothing more to choose.
Sending a reply approves its exact words: they are stored as sent and cannot be edited afterwards. A reply is your team answering somebody who asked, so the contact limits that hold outreach do not hold it; pausing the workspace, an unsubscribe and quiet hours still do. The address is kept, encrypted, on that one conversation and goes with it. A message that arrived by email is shown back in the widget only where your sign-in vouched for the address, because anybody can type somebody else's address into a form.
Somebody still on your site when you reply sees it in the widget first; the email waits five minutes and is sent only if they have not opened it by then. Somebody who has left is emailed straight away.
Answering from your own inbox or helpdesk. Under Settings › Help widget, Also email each message to takes one address — your support inbox, or your helpdesk's. Every new message is emailed there as it arrives, from "dana via Acme" with the conversation's reply address as its Reply-To. Reply from there and the answer comes back into the conversation and reaches them in the widget and by email, exactly as a reply sent from FunctioningHQ does. An answer is taken from that address or another on the same company domain, where the sending server passed SPF; an out-of-office or a helpdesk's automatic acknowledgement is ignored. The message in the email is the stored one, with emails, phone numbers and card numbers already redacted.
Somebody is waiting until a person replies, and waiting again when they write back. On the conversation's page, beside the reply box, you can also:
- Assign it to one teammate, or to nobody. The Answer view filters to everybody's, yours or unassigned. It says whose a conversation is and nothing more: there are no counts or rankings per person.
- Remind me: set it aside for an hour, four hours, a day, three days or a week. Until then it is not counted as waiting. When the time comes it is back where it stood, and whoever it is assigned to (or whoever set the reminder) is emailed a link. A new message from the customer, or your reply, clears it.
- Close or reopen it by hand. If they write again, it reopens.
There are no SLAs, macros or automatic assignment: it is a queue that works, not a helpdesk.
Follow-ups
When a playbook reaches "show this is fixed in the widget", a person approves the exact text. That text waits against the same salted person hash conversations use, and the next time that person is on a page with the widget they see it once, as a card above the pill (or in the corner when there is no pill).
The message can carry one question, answered on the card:
- Did this fix it? — the default. The step mints a "did this fix it?" request for the person's conversation, exactly the one an emailed link would carry, and the card offers Yes, it is fixed / Not really. "Not really" is a finding against the fix, not a new ticket.
- A survey question — when the step is configured
ask: 'ces'. The step mints a survey only for someone the survey rules allow (closed, settled, recent, not asked anything this quarter); anyone else gets no message at all. The card shows the scale's question verbatim, a 1–7 row, and one optional note.
A follow-up can also be aimed at a page: the approver may fill in "only on pages starting with", like /billing, and that is part of the approved revision, so changing it at approval is a new revision like changing the text. The inbox returns (and marks read) only messages whose page is a prefix of the page the visitor is on, masked as presence keeps it; anything meant for another page waits for it. The hosted help form, which is not a page of your site, withholds nothing. With presence on, queuing a follow-up flags the people it is for, and a visitor already on the site is told at their next heartbeat (due: true, which says nothing about what or for whom) and the frame looks straight away.
Answers go to POST /api/widget/reply with the question's token and are recorded by the same functions as the /f and /s link pages: the first answer stands, a score outside the scale is refused rather than clamped, and the note is redacted. A question is offered only while it is unexpired and unanswered, and is marked sent when it is shown.
The assistant
Narrow by design. It answers only from knowledge for answering customers — articles and short answers written here (a short answer is one fact, its conditions, the wording to use, never-say rules; never published at any address), and, where a helpdesk is connected, the current snapshot of its help center or a docs site — with citations that pass the same passage check the grader applies. Knowledge only for checking answers never reaches it. The visitor reads an answer, not its citations: where it answered from an article published publicly it offers "Read the full article", and nothing else of where it came from is sent — the answer rests on it and the stored exchange records it. A question it could not answer gets a snippet drafted overnight, which waits under Your list for a person to publish. An answer whose citations fail is withheld and the visitor reads one sentence: "I don't have that written down; I've passed it on." It has no tools, no actions, and no view of accounts, billing or refunds: a question that asks for any of those is declined and passed on.
Every exchange is stored as a conversation through the signal path with aiParticipated set, provenance and the articles cited on it, so the AI audit grades it exactly as it grades a helpdesk's AI agent. Every question it could not answer, withheld, declined or was capped on is a finding (assistant_unanswered); "No" on Did this help? is another (assistant_unhelpful). Both join assignment like any other finding, so repeated questions cluster into a pattern with no new machinery.
Controls: on or off (off by default), on Settings › Help widget beside its daily cap and under Automation › What runs, and a daily cap on answers per workspace. The workspace's daily model budget applies too.
Searching, when the assistant cannot answer
POST /api/widget/search takes { question, workspace? } through the same two doors as the assistant — a widget key, or the public help slug — and returns { results: [{ title, passage, url }], message, empty }.
It costs nothing: no model is asked, no allowance is read and no budget is checked, which is the point. It answers where the assistant cannot — switched off, its allowance spent, the day's budget reached, on the free audit, and in a language nothing was written in — so a workspace with no assistant still has a widget that answers rather than one that only forwards messages to people. It is never offered beside the assistant: the box searches only while the assistant is switched off or its allowance is spent, and a workspace that turned the assistant's part off has no box but the message to a person.
It searches articles for answering customers, and nothing else. A result is an article — written in Knowledge, synced from the helpdesk's help center, or read from a docs site — with its title, the matching passage as plain words, and url where it is published publicly. A short answer (whose body carries its never-say line) and knowledge only for checking answers are never shown to a visitor, so they are not searched. A workspace with no such article is not offered search at all: whether there is one is mirrored into the widget's config (visitorKnowledge), and the box searches only where it is true or not yet known.
The narrowing is the database's: a generated tsvector and a GIN index on kb_articles (tenant 0210), in the article's own language, at most twelve rows read and five shown. Everything the visitor typed is asked for first; if nothing has all of it, any of its words is asked for, ranked. A search wrapped in double quotes is an exact phrase and gets no second pass.
Rate limited like every public route, out of robots and analytics. Every search is recorded with its result count and nothing that identifies anybody — no visitor token, no email, no address — because a search that found nothing is a demand signal nothing else produces: somebody saying in their own words what they looked for and did not find, with no conversation needed for it to exist. Knowledge › Gaps reports those apart from the gaps and counted in searches, because with no person on the row they cannot honestly be counted in people. Retention deletes them by age.
Each plan includes assistant sessions a month (lib/plan/assistant): Starter 300, Core 1,000, Plus 3,000, and a trial the same as Starter. A session is one visit's conversation, however many questions it holds: the widget and the hosted form send the page load's session id with each question, and sessions are counted per calendar month (UTC), a capped question not counting. Past the allowance a new session's questions get the one sentence and go to a person; a session already under way carries on. Settings › Help widget shows the count. Billing sells one plan per workspace and no metered add-ons yet, so more sessions means a higher plan, or an operator granting extra with npm run tenant:assistant-sessions -- --tenant <id> --extra <n>. The plan on each workspace is mirrored from Stripe by POST /api/webhooks/stripe, verified with STRIPE_WEBHOOK_SECRET, and corrected by the nightly reconciliation, from the prices on the subscription so a plan switch lands on the new plan. The same text limits as the hosted form apply to a question. Cost is metered and written into the audit event for each answer.
Endpoints, with a widget key or the help slug, exactly as the form:
| Method | Path | What |
|---|---|---|
| GET | /api/widget/config | The published config: options, modules, capture, its version |
| POST | /api/widget/feedback | { signals: [ … ], workspace? } → { received, recorded, unknown[], rejected[] } |
| GET | /api/widget/answer | { enabled } — whether this workspace answers |
| POST | /api/widget/answer | { question, context?, person?, workspace? } → { outcome, text, citations[], conversationId } |
| POST | /api/widget/answer/feedback | { conversationId, helpful, note?, workspace? } |
outcome is answered, withheld, unanswered, declined or capped. A workspace with the assistant off answers 403 assistant_off, and the embed falls back to the plain form. "Leave it for a person" submits the question through POST /api/widget as before.
Before a native help-page revision reaches its approval, the assistant is re-run against the questions that failed on that pattern with the revised text in place, and the result is shown on the approval. It blocks nothing.
Something missing, or a field that does not behave as this says? Tell us — the contracts here are what the code is held to, so a page that is wrong is a bug in the same sense the code would be.