Chat Widget

Introduction

The DocsGPT Widget is a powerful tool that allows you to integrate AI-driven document assistance directly into your web applications. This guide will walk you through embedding the DocsGPT Widget into your projects, whether you’re using React, plain HTML, or Nextra. Enhance your user experience by providing seamless access to intelligent document search and chatbot capabilities.

Try out the interactive widget showcase and customize its parameters at the DocsGPT Widget Demo .

Setup

npm install docsgpt

import { DocsGPTWidget } from "docsgpt";

<DocsGPTWidget
  apiHost="https://gptcloud.arc53.com"
  apiKey="your-agent-api-key"
  avatar="https://your-cdn/avatar.png"
  title="Get AI assistance"
  description="DocsGPT's AI Chatbot is here to help"
  heroTitle="Welcome to DocsGPT !"
  heroDescription="This chatbot is built with DocsGPT and utilises GenAI,
  please review important information using sources."
  theme="dark"
  buttonIcon="https://your-icon"
  buttonBg="#222327"
/>

<script src="https://unpkg.com/docsgpt@0.8.0/dist/legacy/browser.js"></script>

<div id="app"></div>

<!DOCTYPE html>
<div id="app"></div>
<script src="https://unpkg.com/docsgpt@0.8.0/dist/legacy/browser.js"></script>
<script>
  window.onload = function() {
    renderDocsGPTWidget('app', {
      apiHost: 'https://gptcloud.arc53.com', // self-hosted: your API URL, e.g. http://localhost:7091
      apiKey: "your-agent-api-key",
      avatar: 'https://your-cdn/avatar.png',
      title: 'Get AI assistance',
      description: "DocsGPT's AI Chatbot is here to help",
      heroTitle: 'Welcome to DocsGPT!',
      heroDescription: 'This chatbot utilises GenAI, please review important information.',
      theme:"dark",
      buttonIcon:"https://your-icon",
      buttonBg:"#222327"
    });
  }
</script>

npm install docsgpt

import { DocsGPTWidget } from "docsgpt";
 
export default function MyApp({ Component, pageProps }) {
    return (
        <>
            <Component {...pageProps} />
            <DocsGPTWidget
                apiHost="https://gptcloud.arc53.com"
                apiKey="your-agent-api-key"
            />
        </>
    )
}

Properties Table

The DocsGPT Widget offers a range of customizable properties that allow you to tailor its appearance and behavior to perfectly match your web application. These parameters can be modified directly when embedding the widget in your React components or HTML code. Below is a detailed overview of each available prop:

Attachments and Voice Input

Both features are off until you turn them on, and each has a cost worth knowing about.

Attachments are enabled by allowedFileExtensions, which acts as both the switch and the filter. Every attached file is uploaded to /api/store_attachment, parsed, and its text sent with the question, billed against the token budget of the key owner’s account. Which types are worth that depends on your assistant, so there is no default list. A leading dot is optional ('pdf' works) and matching is case-insensitive.

Files that finish uploading before the question is sent are attached to it, and the send waits while any are still uploading or parsing, so a file is never silently dropped. The list only filters what the picker offers: a file it allows but the backend cannot parse is still refused by the server, and the reason appears under that file’s chip.

Voice input is enabled by showMicButton and uses the browser’s Web Speech API. Words appear in the input as they are spoken and extend whatever was already typed, so a question you had started typing survives. Nothing is uploaded to DocsGPT and no STT_PROVIDER is needed.

It is off by default because of where the audio goes. Outside the Chromium builds that expose on-device recognition, the browser forwards the microphone to its vendor’s speech service — Google’s, in Chrome’s case. That is a third-party data flow on your page, so it is your decision to enable.

Browser support is uneven, and the microphone hides itself where it cannot work. Chrome, Edge and Safari have the API, Firefox does not enable it, and it requires a secure origin (HTTPS, or localhost).

<DocsGPTWidget
  apiKey="your-agent-api-key"
  allowedFileExtensions={['.pdf', '.docx', '.md', '.png']}
  showMicButton
/>

Sources and citations

Each answer that used your documents shows a Sources row with the number of sources. It starts collapsed, so the answer comes first; selecting it opens the list.

• A source that is a web page, such as a page ingested with the crawler or sitemap loader, is a link that opens the page in a new tab.
• A source that is an uploaded file shows its title and the passage that was used. It is not a link, because a visitor has no way to open a file from your library.

When the agent cites its sources with [1], [2] and so on, each number becomes a small button in the answer. Selecting it opens the Sources list, scrolls to that source and highlights it. A grouped citation such as [1, 3] becomes one button per number. To get numbered citations, ask for them in the agent’s prompt; see Citations in Customizing Prompts.

Links in an answer open in a new tab, so the visitor stays on your page. A plain web address the model writes out, such as https://example.com, becomes a link too.

Branding

Three properties change what the widget shows of DocsGPT:

• avatar sets the image in the chat header.
• heroIcon sets the image on the welcome card. It defaults to the DocsGPT mark.
• poweredBy sets the credit line under the input. Pass false to hide it, or an object with your own label and href. When the label starts with “Powered by”, only the name after it becomes the link.

<DocsGPTWidget
  apiKey="your-agent-api-key"
  avatar="https://your-cdn/assistant.png"
  heroIcon="https://your-cdn/logo.png"
  poweredBy={{ label: 'Powered by Acme', href: 'https://acme.example' }}
/>

Notes on Widget Properties

• Full Customization: Every property listed in the table can be customized. Override the defaults to create a widget that perfectly matches your branding and application context. From avatars and titles to color schemes, you have fine-grained control over the widget’s presentation.
• API Key Handling: Set apiKey to the API key of a published agent; the widget answers with that agent’s knowledge, prompt and tools. See Agent API keys. If you leave apiKey out, the widget falls back to a built-in key for a public DocsGPT demo agent: on DocsGPT Cloud it silently answers from that demo agent instead of your documents, and on a self-hosted instance the key is invalid and requests fail. apiHost for DocsGPT Cloud is https://gptcloud.arc53.com.

Explore and Customize Further

The DocsGPT Widget is fully open-source, allowing for deep customization and extension beyond the readily available props.

The complete source code for the React-based widget is available in the extensions/react-widget directory within the main DocsGPT GitHub Repository . Feel free to explore the code, fork the repository, and tailor the widget to your exact requirements.