Embed widget
The embed widget is a floating AI chat button that readers use to ask questions about your documentation. It appears in the corner of every published site, and you can copy a script tag to put it on a page outside Topicary.
The embed widget and the reader AI behind it are available on every plan, including the free tier. Plans differ in AI query capacity, not in capability.
Configure the widget
Go to Settings in the sidebar.
Open the General category and find the AI chat widget card.
Change any setting below. Changes save automatically: the card shows Saving…, then Saved.
Setting | What it does | Default |
|---|---|---|
Welcome message | The greeting shown in the empty chat panel before the first question (up to 200 characters) | "Ask a question about this documentation" |
Suggested questions | Up to 3 clickable buttons shown under the greeting (up to 100 characters each) | "What is this about?" and "How do I get started?" |
Position | Where the chat button sits: Bottom-right or Bottom-left | Bottom-right |
Theme | Color scheme: Auto (match user), Light, or Dark | Auto (match user) |
There is no on/off switch for the widget. On a Topicary-hosted site it appears whenever your plan includes reader AI, which every plan does. On a third-party page it appears whenever the script tag is present.
The welcome message is not the input's placeholder. The input always reads Ask about <site name>..., which you cannot change.
Write your 3 suggested questions as tasks readers actually arrive with ("How do I reset a password?"), not feature names. They set expectations for what the widget can answer. Leave them blank and the widget falls back to its two generic questions, which rarely match your content.
How the widget answers
The widget uses AI (Gemini 3.5 Flash) to answer from your published content. It:
Receives the reader's question.
Searches the published site content.
Generates an answer with citations to the pages it used.
Streams the response as it is written.
Each answer carries a Was this helpful? prompt. Reader votes go to your feedback data alongside page feedback.
Open the widget from a link
Two URL forms open the widget on arrival, on any page that loads it:
URL | Behavior |
|---|---|
| Opens the chat with an empty input |
| Opens the chat and answers that question immediately |
Use the ?ask= form in release notes, support macros, or in-app help links to send a reader straight to an answer.
Embed the widget on another site
Publish the target whose content the widget should answer from.
Go to Settings > General > AI chat widget and find Embed code.
Click the copy button next to the snippet for that target.
Paste the snippet into the page, before the closing
</body>tag.
The snippet looks like this, with your target's ID already filled in:
<script src="https://www.topicary.com/embed/chat.js" data-target-id="YOUR_TARGET_ID"></script>The widget reads the target ID from the data-target-id attribute and calls back to the same host the script was loaded from.
Copy the snippet from the app rather than typing it. The host must be www.topicary.com: a snippet pointing at any other Topicary hostname fails to load and the widget never appears.
Embed code offers a snippet only for targets that are already published, because the widget loads its configuration and its answers from a published target. Until you publish one, the field reads "Publish a site first. The widget loads its configuration and answers from a published target, so a snippet copied now would never respond." When several targets are published, each snippet is labeled with its target name.
Where the widget works today
Where the script runs | Result |
|---|---|
Your | Works, including on password-protected sites |
Your custom domain | Works |
Any other domain | The widget renders, then cannot answer |
On a third-party domain the browser blocks the answer request, because the domain is not on the target's allowed-origins list. That list is not configurable from the dashboard: contact support to add an external origin. Until it is added, readers see a chat button that opens and then fails on every question, so hold the snippet back from external pages rather than shipping a broken one.
Technical details
Self-contained vanilla JavaScript, no framework dependencies
Uses Shadow DOM (a browser feature that isolates widget styles from the host page), so the host site's CSS cannot affect it and it cannot affect the host site
Streams answers over server-sent events (SSE)
See also
AI-ready published sites: all machine-readable endpoints including the Ask endpoint that powers the widget
Published site features: full list of reader-facing features on published sites including AI search
Plans and limits: reader AI is available on every plan; check your plan's query capacity
Customize your site's branding: configure the widget's theme and position alongside other branding settings