> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mithunai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add an AI chat widget to your website

> Embed a chat assistant on your documentation or support site with one script tag. Anonymous visitors get grounded, cited answers, from the origins you allow.

The widget puts an assistant on your own website. Visitors who have never signed in can ask questions and get grounded answers with citations, in a panel that opens from a launcher button.

## Set it up

<Steps>
  <Step title="Create a widget embed">
    An Owner, Administrator or Editor creates one embed per site.

    <Tabs>
      <Tab title="Console">
        1. Open **Operations → Widget embeds** and select **New embed**.
        2. Enter a **Name**, choose the **Assistant** that should answer, and list your site under **Allowed origins**, one per line. Only an active assistant can be chosen.
        3. Select **Create embed**. The embed appears in the list with its **Embed snippet**, which contains its widget key (`arukz_wk_…`).
      </Tab>

      <Tab title="API">
        ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
        curl --request POST "$MITHUNAI_URL/arukz/api/v1/widget-deployments" \
          --header "Authorization: Bearer $MITHUNAI_API_KEY" \
          --header "Content-Type: application/json" \
          --data '{
            "name": "Docs site",
            "assistant_id": "<assistant id>",
            "allowed_origins": ["https://docs.example.com"]
          }'
        ```

        The response contains `widget_key`. See [Create a widget deployment](/api-reference/widget-deployments/create-widget-deployment).
      </Tab>
    </Tabs>
  </Step>

  <Step title="Ask for your origin to be enabled on the deployment">
    Widget requests must be allowed by **two** allowlists: your embed's own list, and a
    deployment-wide list set by whoever operates your MITHUNAI deployment. Both start empty. Ask your
    MITHUNAI administrator to add your site's origin to the deployment-wide list.
  </Step>

  <Step title="Add the snippet to your site">
    In **Operations → Widget embeds**, select **Copy** beside the embed's **Embed snippet** and paste it, unchanged, before the closing `</body>` tag on every page that should show the widget. It looks like this:

    ```html theme={"theme":{"light":"github-light","dark":"github-dark"}}
    <script>
      window.arukzWidget = {
        apiBaseUrl: "https://app.mithunai.com/arukz/api/v1",
        widgetKey: "arukz_wk_...",
      }
    </script>
    <script src="https://app.mithunai.com/widget/arukz-widget.js" defer></script>
    ```

    The snippet can be copied again at any time, so losing it never orphans an embed. If you created the embed with the API, build the same snippet from its `widget_key`.
  </Step>

  <Step title="Test it">
    Open your page, select the launcher and ask a question your content covers. If the launcher does not appear, open the browser console: a misconfigured widget logs one message explaining what is wrong and renders nothing on your page.
  </Step>
</Steps>

## Configuration options

| Option        | Required | Description                                                                                    |
| ------------- | -------- | ---------------------------------------------------------------------------------------------- |
| `apiBaseUrl`  | Yes      | Your MITHUNAI API base URL, ending in `/arukz/api/v1`                                          |
| `widgetKey`   | Yes      | The embed's public key, starting with `arukz_wk_`                                              |
| `title`       | No       | The launcher label and panel title. Defaults to your brand's product name. Up to 60 characters |
| `position`    | No       | `"right"` (default) or `"left"`                                                                |
| `defaultOpen` | No       | `true` opens the panel on page load. Defaults to `false`                                       |

Colours, logo and product name come from your organisation's [branding](/administration/branding), so one snippet stays correct when you rebrand.

The widget renders inside a shadow root, so your site's styles do not change it and its styles do not leak onto your page. It is a non-modal panel: it moves focus in when opened, returns focus to the launcher when closed, closes on <kbd>Escape</kbd>, and never traps keyboard focus or locks page scrolling.

## Allowed origins

An origin is a scheme, host and optional port, such as `https://docs.example.com`.

* **Exact match only.** There is no wildcard. `https://example.com` does not match `https://www.example.com`; list each one.
* **No trailing slash or path.** `https://docs.example.com/` is invalid.
* **Empty means nowhere.** An embed with no allowed origins works on no site.

An allowed origin decides where a browser may show the widget. It is not authentication: a client outside a browser can send any `Origin` it likes, which is why the widget key grants so little on its own.

Update the list at any time from **Operations → Widget embeds** or with [Update a widget deployment](/api-reference/widget-deployments/update-widget-deployment). Sending a new list replaces the old one.

## The widget key is public by design

The widget key sits in your page's HTML where anyone can read it. That is expected: it is not a password and carries almost no authority. Holding it lets someone:

* start a conversation with the one assistant the embed names,
* ask questions in a conversation they started,
* read back their own conversation.

It does not let anyone read your knowledge, list documents, see your settings or members, or read another visitor's conversation. Requests must also come from an allowed origin and are rate limited.

<Danger>
  Never put an API key (`arukz_sk_…`) in a web page. API keys are secrets. The widget refuses one,
  but the value is still published in your page source. If this has happened, [revoke the
  key](/administration/api-keys) immediately.
</Danger>

## Visitor conversations

Each conversation belongs to the browser tab that started it:

| Situation                                      | Result                             |
| ---------------------------------------------- | ---------------------------------- |
| The visitor reloads the page                   | The conversation continues         |
| The visitor opens a second tab                 | A new conversation starts          |
| The visitor closes the tab                     | The conversation cannot be resumed |
| Another visitor tries to open the conversation | Refused                            |

Conversations deliberately do not survive a closed tab. Public pages are often read on shared computers, and remembering a conversation would show the next person what the previous visitor typed.

## Revoke an embed

Revoke an embed from **Operations → Widget embeds** or with [Revoke a widget deployment](/api-reference/widget-deployments/revoke-widget-deployment). It stops working on the next request, and revocation is permanent. To move a site to a different assistant, create a new embed, update your snippet, then revoke the old one. An embed's assistant cannot be changed after creation.

## Limits

* Each embed has its own request budget of **20 requests per minute**, separate from your API traffic. Over budget, requests receive `429` with a `Retry-After` header.
* If the rate-limiting service is unavailable, widget requests are refused rather than served without limits.

If a page will serve more traffic than this, talk to your MITHUNAI contact rather than splitting one site across several embeds.

## Build your own widget

To build a custom interface instead, call the [public widget endpoints](/api-reference/widget/bootstrap) from the browser with the widget key and visitor token.

## If the widget does not appear

A launcher that never renders is nearly always one of four things: the host page's origin is not in the embed's allowed origins, the key does not start with `arukz_wk_`, the snippet was edited after it was copied, or the embed has been revoked. The browser console names which. [Troubleshooting](/resources/troubleshooting) works through each, including the case where the widget appears but every question fails.