/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
Guides Recipes Recipe: Embed the AI Widget Anywhere

Recipe: Embed the AI Widget Anywhere

Add your docs' AI assistant to your marketing site, app, or support portal.

2 min read

Your doc site's AI assistant can live on any page you control — turn "Contact support" into "Ask the docs" on your marketing site, inside your app, or in your support portal.

Basic Embed

In your project, open Integrations › Chat widget, turn it on, and add every site that will embed it under Allowed origins (for example https://www.acme.com). Then copy the snippet from Embed and add it to your pages:

html
<script
src="https://api.syntext.dev/v1/widget/<project-id>.js"
defer>
</script>

<project-id> is your project's UUID. The loader answers 404 while the widget is off and 403 on a site that isn't in Allowed origins.

This renders a floating chat button. The widget:

•
Uses the settings you saved — position, accent colour, welcome message — which the loader inlines
•
Streams answers from /v1/widget/<project-id>/chat with citations linking back to your docs
•
Applies per-visitor rate limits automatically
Warning

Public sites only. For a site behind a password, or behind access control in password or invite-only mode, the widget's chat (/v1/widget/*) answers 403 PRIVATE_SITE: the widget runs on other people's pages and can't sign a reader in, so it never answers from a private site's pages. Readers of a private site use the assistant on the site itself. Public sites are unaffected.

Page context

The widget sends the path of the page it's on (for example /dashboard/billing) with each question, so answers can take into account what the reader is looking at. There's nothing to configure.

Building a Custom UI

Skip the widget entirely and call the API from your own frontend:

typescript
const res = await fetch(
`https://api.syntext.dev/v1/projects/${PROJECT_ID}/chat`,
{
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
question,
visitorId, // stable anonymous ID you generate
sessionId, // from previous X-Session-Id header, for follow-ups
}),
}
)
const sessionId = res.headers.get('X-Session-Id')
const messageId = res.headers.get('X-Message-Id') // this answer, for feedback
const reader = res.body!.getReader()
// ...consume the stream

A sessionId only continues the conversation when it's sent with the same visitorId that started it — otherwise a new session starts. Always keep the X-Session-Id you get back.

Add feedback buttons that call the feedback endpoint with that messageId once the stream has finished — thumbs-down answers feed your documentation gaps report (Insights › Assistant). For suggested next questions, call follow-ups with the sessionId and visitorId.

Things to Know

•
The chat endpoint is public by design (it's what your doc site uses) — abuse is contained by visitor rate limits and your org's monthly AI quota
•
Answers only draw from your indexed documentation
•
A custom UI works for public sites only. For a password-protected or invite-only site, calls straight to the chat endpoint get 403 FORBIDDEN; only requests that come through the doc site (/_chat) are answered
•
Handle the 429 and 402 USAGE_LIMIT_EXCEEDED responses gracefully in custom UIs — show a cooldown message rather than an error
Was this page helpful? Yes No
Product
Resources
Company
© 2026 SyntextBuilt with Syntext