- Improve Dev Experience
- Website support widget
Improve Dev Experience
Website support widget
Prepare a secure website integration with the DocsAlot support widget private pilot.
Add a support launcher to your website so visitors can ask questions and follow citations to your published documentation.
Private pilot draft. The widget is not generally available. The SDK is not published to npm and there is no public hosted script to install. Follow this guide only after DocsAlot has enabled your pilot and supplied the matching SDK artifacts and credentials. These examples document the pilot integration, not a live self-service installation flow.
Before you begin
- Publish a public DocsAlot documentation site and index its documentation. The anonymous widget does not support password-protected or SSO sites, including their public sections.
- Ask DocsAlot support about pilot enrollment. Confirm your exact website origin, such as
https://app.example.com, and your documentation site. - Obtain your public widget ID, a dedicated server credential, and the approved browser/server SDK artifacts. The widget ID is not your documentation ID or an API token.
- Have a website backend that can verify a signed-in site session or a bot challenge and issue short-lived widget sessions. A static HTML snippet alone is not enough.
Indexing and AI Answers reporting require access to the documentation’s PRO workspace. Pilot enrollment is separate from that dashboard access; confirm both with DocsAlot before integrating.
Origins include the scheme, hostname and port, but no path or trailing slash. https://example.com, https://www.example.com and https://app.example.com are different origins. Use the exact enrolled origin; there is no wildcard-origin setting in this pilot.
The widget retrieves only indexed documentation that matches the current published public files and is listed in the site’s navigation. Drafts, private or hidden pages, snippets and supplementary knowledge-base uploads are not widget sources. Publish and reindex changes before expecting new answers.
How the connection works
The browser asks your backend for a session
Your website calls its own /api/support-session endpoint. Your backend verifies the visitor and applies abuse controls.
Your backend requests a five-minute token
Your backend authenticates to DocsAlot using the dedicated server credential. The returned token is bound to one widget, documentation site, approved origin and active credential.
The browser sends the question to DocsAlot
Return only the short-lived token to the browser. The SDK streams an answer and displays links to the cited documentation pages. Your server credential never leaves your backend.
1. Prepare the pilot SDK
The source package is named @docsalot/support-widget, with browser and server entry points. Its current pilot version is 0.1.0, marked private. Do not run an npm installation command for it until a public distribution is announced.
The examples below assume you have placed the approved built artifacts as follows:
| Artifact from the pilot build | Location in your website project |
|---|---|
dist/index.js | Serve as /vendor/docsalot-widget.js from your website |
dist/server.js and dist/server.d.ts | src/lib/docsalot-widget/server.js and server.d.ts, used by your backend only |
These paths are self-hosted example locations, not DocsAlot CDN URLs. For a bundled TypeScript frontend, keep the browser module and its index.d.ts together in your chosen local module directory. Adjust the imports to match your project.
Never copy credentials into the browser module, HTML, source control or logs. Do not substitute a DocsAlot account API token. Keep the server helper out of client components and browser bundles.
2. Configure your backend
Store these values in your backend’s environment or secret manager. Replace the placeholders with the values supplied for your pilot:
DOCSALOT_WIDGET_ID=YOUR_PUBLIC_WIDGET_ID
DOCSALOT_WIDGET_SERVER_CREDENTIAL=YOUR_SERVER_CREDENTIAL
SUPPORT_WEBSITE_ORIGIN=https://app.example.com
The credential must remain server-only. Do not use a public environment-variable prefix such as NEXT_PUBLIC_ or VITE_ for it.
Create a same-origin POST /api/support-session endpoint. The following examples use a Next.js App Router route at src/app/api/support-session/route.ts or route.js.
Required application adapter: implement verifySupportSessionAccess(request) in your own server-only src/lib/support-session-access module. It must return true only after verifying your site’s authenticated session or a server-validated bot challenge. Apply CSRF protections and rate limits appropriate to your site. Checking for a cookie’s presence or allowing an Origin header is not authentication. Do not replace this check with an unconditional true.
If your access check requires a CSRF token or bot-challenge proof, include it in the browser’s getSessionToken request using your site’s existing flow, then verify it on your backend. The minimal browser examples below send only same-origin site cookies; they do not implement a bot challenge for you.
import { createWidgetSession } from "@/lib/docsalot-widget/server.js";
import { verifySupportSessionAccess } from "@/lib/support-session-access";
export const runtime = "nodejs";
const headers = { "Cache-Control": "private, no-store" };
export async function POST(request: Request): Promise<Response> {
try {
const widgetId = process.env.DOCSALOT_WIDGET_ID;
const serverCredential = process.env.DOCSALOT_WIDGET_SERVER_CREDENTIAL;
const origin = process.env.SUPPORT_WEBSITE_ORIGIN;
if (!widgetId || !serverCredential || !origin) {
return Response.json({ error: "Support is unavailable" }, { status: 503, headers });
}
if (request.headers.get("origin") !== origin ||
!await verifySupportSessionAccess(request)) {
return Response.json({ error: "Forbidden" }, { status: 403, headers });
}
const session = await createWidgetSession({ widgetId, origin, serverCredential });
return Response.json({ token: session.token }, { headers });
} catch {
return Response.json({ error: "Support is unavailable" }, { status: 503, headers });
}
}
Use a trusted configured origin, not an arbitrary origin supplied by the visitor. The server helper calls POST https://docsalot.dev/api/widget/v1/{widgetId}/session with the dedicated credential. That DocsAlot endpoint is server-to-server only, does not offer browser CORS access, and returns { token, expiresAt }. Your website forwards only { token } and must not cache it.
3. Mount the browser widget
The JavaScript example can run in a page’s <script type="module"> after the document body exists. The TypeScript example belongs in your browser application entry point; the local import assumes the supplied browser module and declaration are colocated there. Replace YOUR_PUBLIC_WIDGET_ID and https://docs.example.com in either example.
import { mountSupportWidget } from "/vendor/docsalot-widget.js";
const widget = mountSupportWidget({
widgetId: "YOUR_PUBLIC_WIDGET_ID",
documentationUrl: "https://docs.example.com",
title: "Ask our docs",
async getSessionToken(signal) {
const response = await fetch("/api/support-session", {
method: "POST",
credentials: "same-origin",
cache: "no-store",
signal,
});
if (!response.ok) throw new Error("Support is unavailable");
const data = await response.json();
if (typeof data.token !== "string") throw new Error("Invalid support session");
return data.token;
},
});
// When removing this page in a single-page app:
// widget.destroy();
documentationUrl must be your documentation site’s origin, without a path, query or fragment. It is used for citation links; changing it does not select a different knowledge base. DocsAlot selects the enrolled documentation site on the server.
mountSupportWidget attaches to document.body by default. It returns open(), close() and destroy() methods. In a single-page app, mount it once and destroy it on unmount to avoid duplicate launchers. Run it in the browser, not during server rendering.
The SDK obtains a fresh session through getSessionToken for each question. Keep tokens out of local storage and URLs; there is no need to retain them between questions. Requests to DocsAlot omit DocsAlot sign-in cookies and do not send conversation history. Human handoff is not part of this pilot.
If your site uses a Content Security Policy, review the self-hosted module, connect-src access to https://docsalot.dev, and the SDK’s inline Shadow DOM styles with your security team. Do not broadly weaken the site’s policy to make the widget load.
Test the integration
Use an enrolled test origin
Open the integration on its exact approved HTTPS origin. For local HTTP development, both the DocsAlot API and pilot configuration must explicitly support development mode and the exact localhost or 127.0.0.1 port. A production pilot does not automatically allow localhost. Do not send a production credential to a local mock or unapproved service.
Check the session boundary
Confirm your session endpoint rejects a visitor who has not passed your site-session or bot check. After authorization, verify that it returns only a short-lived token with Cache-Control: private, no-store. The dedicated server credential must not appear in page source, browser network requests, frontend bundles or logs.
Ask a question with a known answer
Open the launcher and ask about a specific published public page. Confirm that an answer appears and a citation opens the correct page on your documentation site. An answer without relevant citations is not a successful retrieval check.
Find the question in AI Answers
In your documentation dashboard, open AI Answers, select Readers, and use a reporting period that includes your test. Widget events are included with reader events; there is no separate Widget selector in the current UI. Check the question and recorded source count.
Rotate or revoke a credential
Coordinate credential changes with DocsAlot support during the private pilot; there is no customer credential-management command in this guide.
Request a replacement
Ask for a new dedicated server credential over the approved secure channel. DocsAlot can temporarily accept both the old and new credentials for your pilot.
Update your backend secret
Replace only DOCSALOT_WIDGET_SERVER_CREDENTIAL, reload or redeploy your backend as needed, and verify a new session. Do not send either credential to the browser or attach it to a support ticket.
Retire the old credential
Ask DocsAlot to revoke the old credential after the switch. Revocation invalidates outstanding tokens minted using that credential, even before their five-minute expiry. Removing the pilot disables access altogether.
For suspected credential exposure, request immediate revocation rather than waiting for an overlap period. Review your backend’s logs and deployments for copies without printing the secret while investigating.
Troubleshooting
| Symptom | What to check |
|---|---|
| No launcher, or duplicate launchers | Check the browser module URL, JavaScript errors and CSP. Mount only in the browser, once, and clean up with destroy(). |
Your /api/support-session returns 403 | Check your own session/bot verification, CSRF policy and configured website origin. This is your backend’s response, not the DocsAlot session API. |
DocsAlot session API returns 404 | Confirm pilot activation, widget ID, exact enrolled origin and active server credential with support. The API also deliberately returns 404 for invalid configuration or browser-originated session calls. |
| Chat fails on another domain, port or preview URL | The origin is not enrolled. Do not bypass this with a wildcard or by forwarding a browser-supplied origin. |
Chat returns 401 | The browser token is expired, invalid or revoked. Obtain a fresh token from your protected backend endpoint. Check clock accuracy and credential rotation. |
Chat returns 429 | The current pilot permits six questions per UTC minute and 60 per UTC day per widget, shared by its visitors. Avoid automatic retry loops; wait for the relevant window or contact support. Requests rejected before an answer may still consume a reserved quota slot. |
Chat returns 400, 413 or 415 | Send JSON containing only message, a nonempty question of up to 1,500 characters. The chat request body is limited to 8 KiB. The supplied SDK formats this request for you. |
| Assistant unavailable or no indexed documentation | Confirm a published, fully public site, a configured knowledge base, navigable public pages and a completed documentation index. A session token alone does not prove the site’s publication or index is ready. |
| Missing citations or an answer ignores recent edits | Publish the changes, reindex the published documentation and try a specific question. Stale indexed content that no longer matches the published file is excluded rather than used as a fallback. Supplementary uploads and private/hidden pages are not widget sources. |
Chat returns 503 or a generic error | Check your backend and network health without logging credentials or tokens. Contact support if it persists. The browser deliberately does not display raw service errors. |
| The test is absent from AI Answers | Select Readers and the right date range. Preflight, authorization, quota and publication failures may stop before an answer event is recorded; a successful cited answer is the useful smoke test. |
Related guides
This website widget is separate from the documentation site’s built-in assistant and the Authoring MCP connection. It does not require a visitor to sign in to DocsAlot and cannot be used to access protected documentation.