Add an AI chat widget to your website

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

Create a widget embed

An Owner, Administrator or Editor creates one embed per site.

Console
API

Open Operations → Widget embeds and select New embed.
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.
Select Create embed. The embed appears in the list with its Embed snippet, which contains its widget key (arukz_wk_…).

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.

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.

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:

<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.

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.

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, 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 Escape, 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. Sending a new list replaces the old one. 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.

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 immediately.

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. 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. To build a custom interface instead, call the public widget endpoints from the browser with the widget key and visitor token. 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 works through each, including the case where the widget appears but every question fails.

Get started

Knowledge

Assistants & Agents

Channels & Integration

Architecture & Solutions

Administration

Trust and support

Add an AI chat widget to your website

Set it up

Configuration options

Allowed origins

The widget key is public by design

Visitor conversations

Revoke an embed

Limits

Build your own widget

If the widget does not appear

​Set it up

​Configuration options

​Allowed origins

​The widget key is public by design

​Visitor conversations

​Revoke an embed

​Limits

​Build your own widget

​If the widget does not appear

Set it up

Configuration options

Allowed origins

The widget key is public by design

Visitor conversations

Revoke an embed

Limits

Build your own widget

If the widget does not appear