Skip to content

Embed widget

The embed widget is a floating AI chat that readers can use to ask questions about your documentation. It appears as a small button in the bottom-right corner of published sites.

The embed widget and the reader AI that powers it are available on every plan, including the free tier. Plans differ only in AI query capacity, not capability. Check your plan's usage limits for details.

Configuration

Configure the widget in Settings > General, in the Embed Widget part of the Branding section:

Setting

Description

Default

Welcome message

Greeting shown when the widget opens (up to 200 characters)

"Ask a question about this documentation"

Suggested questions

Up to 3 pre-filled question buttons (each up to 100 characters)

None

Position

Bottom-right or bottom-left

Bottom-right

Theme

Color scheme: auto, light, or dark

Auto

How it works

The widget uses AI (Gemini 3.5 Flash) to answer reader questions based on the published content. It:

  1. Receives the reader's question

  2. Searches the published site content

  3. Generates an answer with relevant citations

  4. Streams the response in real-time

Embed snippet

You can also embed the widget on external pages outside of your published Topicary site. Add the following script tag before the closing </body> tag:

<script
  src="https://app.topicary.com/embed/chat.js"
  data-target-id="YOUR_TARGET_ID">
</script>

Replace YOUR_TARGET_ID with the publication target's ID. The widget reads the target ID from the data-target-id attribute and calls back to the same host the script was loaded from.

Embedding on your own published site works automatically. To embed on a different domain, that domain must be on the target's allowed-origins list. This allowlist is not yet configurable from the dashboard; contact support to add an external origin.

Technical details

  • Built as a self-contained vanilla JavaScript widget (chat.js)

  • Uses Shadow DOM (a browser feature that isolates widget styles from the host page) for style encapsulation, with no conflicts with the host site's CSS

  • Communicates through server-sent events (SSE) for streaming responses

  • No framework dependencies

Add up to 3 suggested questions that reflect common reader tasks. Well-chosen suggestions help readers discover the widget's capabilities and reduce the friction of typing a first question.

Framework-specific embed packages

For teams that want tighter integration than the script tag embed, Topicary provides framework-specific packages:

@topicary/embed-react

React 18+ components for embedding Topicary features directly in a React application:

  • TopicaryChat: floating iframe chat widget

  • TopicarySearch: inline streaming search

  • TopicaryDocs: full documentation site iframe

@topicary/embed-web

Custom elements using Shadow DOM for framework-agnostic integration:

  • <topicary-chat>: chat widget

  • <topicary-search>: inline search

  • <topicary-docs>: full documentation site

@topicary/embed-node

Node.js client for server-side access to published site content:

  • TopicaryClient with search(), getPages(), getPage(), and chat() (async generator) methods

Availability

The embed widget and the reader AI behind it are available on every plan, including the free tier. Plans differ only in AI query capacity. Check current plan limits for details.

See also

Was this page helpful?