AI chat widget

The Stainless Docs Platform includes a “Chat Widget” that you can connect to your AI provider in order to add a chatbox to your documentation site.

How it works

When connected to a chat service provider, the chat widget appears as a collapsible input field in the bottom-right corner of your documentation site.

To use this feature, you must provide your own backend functionality to handle user events.

Enabling the built-in chat

To enable the Stainless-provided AI chat widget in your astro.config.ts file, add the aiChat configuration:

astro.config.ts

import { defineConfig } from "astro/config";
import { stainlessDocs } from "@stainless-api/docs";

export default defineConfig({
  integrations: [
    stainlessDocs({
      title: "My API Docs",

      experimental: {
        aiChat: { handlerEntrypoint: "path/to/your/chat/provider/implementation.ts" }
      },

      // ... other options
    }),
  ],
});

The aiChat field accepts two values: an entrypoint for your handler implementation, and a set of example prompts to show when a new chat is opened. Both are covered in more detail below.

Handler interface

Your handlerEntrypoint file must export a default object that satisfies the DocsChatHandler type (importable from '@stainless-api/docs/chat'). This is comprised of two functions:

1. You need a generateResponse function that accepts a query and a series of previous messages, and returns a generator of ResponseChunks. This function will be invoked whenever the user sends a message to the chat widget.

2. You need an onRate function that accepts a spanId and a “score”, either 0 or 1. This function is invoked whenever a message is “rated” using the thumbs up or thumbs down buttons.

Here is a simple example handler implementation:

chat-handler.ts

import type { DocsChatHandler } from '@stainless-api/docs/chat';

const handler: DocsChatHandler = {
  async *generateResponse({ query }) {
    await new Promise((resolve) => setTimeout(resolve, 1000));
    yield { type: 'text' as const, text: `You just said: ${query}` };
  },

  onRate: (spanId, score) => {
    console.log('Message rating recieved', spanId, score);
    return Promise.resolve({ success: true });
  },
};

export default handler;

Example prompts

You can specify a series of default prompts to show when a new chat is created. These examples will display in the splash screen of the chat interface. When clicked, these will input a pre-constructed message into the chat.

When making example prompts, you must provide three fields:

1. shortPrompt: This is the prompt that will show on the splash screen.
2. longPrompt: This is the prompt that will be sent to the chat widget when an example is clicked.
3. icon: This is the name of the Lucide icon to display next to the ShortPrompt. Casing must be in title case, such as “GitBranch”, and must be a valid Lucide icon name.

Seeing your changes

After you save the configuration and rebuild your site, the AI chat widget appears in the bottom-right corner of your documentation pages.

Disabling the chat widget

If you have enabled the AI chat but want to disable it, remove or comment out the aiChat configuration from your astro.config.ts file:

astro.config.ts

export default defineConfig({
  integrations: [
    stainlessDocs({
      title: "My API Docs",

      experimental: {
        aiChat: true,
      },
    }),
  ],
});