> For the complete documentation index, see [llms.txt](https://verbatim-ai.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://verbatim-ai.gitbook.io/docs/widget-website/user-guide.md).

# User guide

The[ Verbatim AI](https://www.verbatim-ai.com) Chatbot Widget is a drop-in AI assistant you can embed on any website with a single `<script>` tag. It connects to the Verbatim AI API, answers questions from your document corpora, and can show the source documents behind each answer (with page previews). This guide covers installation, configuration, and every available option.

> 🔥 You can see the widget in action in our [Demo Website](https://chemcorp.verbatim-ai.com/) <https://chemcorp.verbatim-ai.com/>

Links to learn more

* [Verbatim AI website](https://www.verbatim-ai.com/)
* [Our docs](https://verbatim-ai.gitbook.io/docs)
* [GitHub repository](https://github.com/verbatim-ai/widget-website/tree/main)

![](https://566874314-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FrGD8XsNiXkCyWUTD7QeV%2Fuploads%2Fgit-blob-9041d8679872d3b6ea7a0870c3342611c54d68b1%2Fwidget.webp?alt=media)

***

## 1. Before you begin

You need:

* **An access token** *(required)*. Every request the widget makes is authenticated with a Verbatim **access token**, sent as the `X-Access-Token` header. See section [3. How to get an Access Token](#3-how-to-get-an-access-token-)
* **One or more corpus ready with theirs IDs** *(required)*. A *corpus* is a collection of documents the assistant is allowed to answer from. Your corpus must be init and ready before setup your widget. You must provide at least one corpus ID for the session to use. See section [4 where to get your Corpus ID?](#4-where-to-get-your-corpus-id-)
* **Access to your site's HTML**, so you can add a container element and a script tag.

> **Both `accessToken` and a non-empty `corpusIds` array are mandatory.** If either is missing, `mountChatbotWidget` logs an error to the console and throws instead of mounting — see [Troubleshooting](/docs/widget-website/troubleshooting.md).

> **Security note:** the access token is visible in the page. Use short-lived, org-scoped access tokens — never a long-lived master secret or a raw JWT.

***

## 2. Quick start

Add a container element where the widget should mount, load the script from the Verbatim CDN, then call `mountChatbotWidget`:

```html
<!-- 1. A container element for the widget -->
<div id="verbatim-chatbot"></div>

<!-- 2. Load the widget from the Verbatim CDN -->
<script src="https://cdn.verbatim-ai.com/widget/chatbot/v1/chatbot-widget.iife.js"></script>

<!-- 3. Mount it -->
<script>
  ChatbotWidget.mountChatbotWidget("#verbatim-chatbot", {
    accessToken: "YOUR_ACCESS_TOKEN",
    corpusIds: ["YOUR_CORPUS_ID"]
  });
</script>
```

That's the minimum. **`accessToken` and `corpusIds` (at least one id) are both required**; everything else has a sensible default. If either required option is missing, `mountChatbotWidget` logs an error to the console and throws — the widget does not mount.

**Styles are included automatically.** By default the widget renders inside a Shadow DOM and injects its own CSS, so you do **not** need to add a stylesheet. (If you turn style isolation off, you must add the stylesheet yourself — see [Options](/docs/widget-website/options.md).)

***

## 3. How to get an Access Token ?

**IMPORTANT**

> Your access token required 4 scopes : `session:read`, `session:create`, `post:read` and `post:create`

Without these scopes, the widget will log an error in the console and display an error.

### By API

use `POST /v1/auth/access-token` Your query should look like for a 1-hour Access Token

```shell
curl -X 'POST' \
  'https://api.verbatim-ai.com/v1/auth/access-token' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer MY_JWT_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "ttl": 3600,
  "issuer": "widget-frontend",
  "scope": [
    "session:read",
    "session:create",
    "post:read",
    "post:create" 
  ]
}'
```

### Using your back office

*not ready yet, coming soon*

## 4. Where to get your Corpus ID ?

### By API

use `GET /v1/corpus/` to list your corpus.

Your query should look like,

```shell
curl -X 'GET' \
  'https://api.verbatim-ai.com/v1/corpus/?pageSize=25&pageIndex=0' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer MY_JWT_TOKEN'
```

The ID is the body of each item

```json
{
  "orgId": "YOUR_ORG_ID",
  "pageIndex": 0,
  "items": [
    {
      "id": "YOUR_CORPUS_ID",
      "createdAt": "2026-04-23T04:06:51Z",
      "updatedAt": "2026-04-23T04:06:51Z",
      "name": "Support knowledge base",
      "description": "Tickets, FAQs and runbooks used by the support team.",
      "metadata": {
        "owner": "support-team",
        "language": "fr"
      }
    }
  ]
}
```

### Using your back office

Open your Corpus page, select your corpus. On the top of the page

![](https://566874314-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FrGD8XsNiXkCyWUTD7QeV%2Fuploads%2Fgit-blob-c023912f9e9450a68b5743d0e8484dca1baea2f3%2Fcorpus_header.png?alt=media)

> Click on the chips under the title of your corpus.

> The corpus id is copied in your clipboard. You just have to paste it in your configuration file.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://verbatim-ai.gitbook.io/docs/widget-website/user-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.