Customise the website widget

The widget is customised in three places. Its script tag takes six optional data- attributes for its label, position and behaviour. If your page defines a window.mithunaiWidget object, that object gains five methods once the script has loaded, so your own button or search box can open the widget and ask a question, and the widget reports what happened as events on window. Everything visual, colours, logo, product name and light or dark appearance, comes from your organisation’s branding, so one snippet stays correct when you rebrand. There are no CSS variables to override.

Snippet options

Add options to the one-line snippet the console gives you under Integrations → Website widget:

<script
  src="https://app.mithunai.com/widget/mithunai-widget.js"
  data-api-base-url="https://app.mithunai.com/mithunai/api/v1"
  data-widget-key="mithunai_wk_..."
  data-title="Acme docs assistant"
  data-launcher-label="Ask the docs"
  data-position="left"
  data-shortcut="true"
  defer
></script>

Attribute	Object field	Required	Description
`data-api-base-url`	`apiBaseUrl`	Yes	Your MITHUNAI API base URL, ending in `/mithunai/api/v1`
`data-widget-key`	`widgetKey`	Yes	The embed’s public key, starting with `mithunai_wk_`
`data-title`	`title`	No	The panel’s title. Defaults to your brand’s product name. Up to 60 characters
`data-launcher-label`	`launcherLabel`	No	What the launcher button reads. Defaults to `Ask AI`. Up to 60 characters
`data-launcher`	`launcher`	No	`false` hides the built-in launcher. Defaults to `true`
`data-position`	`position`	No	`right` (default) or `left`
`data-default-open`	`defaultOpen`	No	`true` opens the panel on page load. Defaults to `false`
`data-shortcut`	`shortcut`	No	`true` makes `Ctrl`+`K` / `Cmd`+`K` open and close the widget. Defaults to `false`
`data-mode`	`mode`	No	`chat` (default), `sidebar`, `search` or `deflector`. See Ways it can appear
`data-target`	`target`	For `search` and `deflector`	CSS selector of the element it appears in
`data-form`	`form`	For `deflector`	CSS selector of your support form
`data-fields`	`fields`	For `deflector`	The form’s fields to read, comma-separated CSS selectors

An on-or-off attribute takes exactly true or false, in lower case. data-shortcut on its own, data-shortcut="yes" and data-shortcut="TRUE" are all refused. An attribute the widget does not know is ignored. A known attribute with a value it cannot accept is refused: the widget logs one message to the browser console naming the attribute, and renders nothing. See Website widget for setup, installation, allowed origins and limits.

The object form

The same options can be written as fields of an object your page defines before the script tag. This is the advanced form: use it when your page calls the widget’s JavaScript API, or when your platform removes data- attributes from script tags.

<script>
  window.mithunaiWidget = {
    apiBaseUrl: 'https://app.mithunai.com/mithunai/api/v1',
    widgetKey: 'mithunai_wk_...',
    title: 'Acme docs assistant',
    launcherLabel: 'Ask the docs',
    position: 'left',
    shortcut: true,
  }
</script>
<script src="https://app.mithunai.com/widget/mithunai-widget.js" defer></script>

On the object, on-or-off options are real booleans (shortcut: true), not strings. A field the widget does not know is ignored, and a known field with the wrong type is refused in the same way as an attribute. You can use both at once. A field set on the object wins, and the tag’s attributes fill in whatever the object leaves out. So the shortest way to get the JavaScript API is an empty object before the one-line snippet:

<script>
  window.mithunaiWidget = {}
</script>
<script
  src="https://app.mithunai.com/widget/mithunai-widget.js"
  data-api-base-url="https://app.mithunai.com/mithunai/api/v1"
  data-widget-key="mithunai_wk_..."
  defer
></script>

Every snippet took the object form until mid-October 2026, and a page that carries one needs no change.

Open it from your own page

After the script loads, the window.mithunaiWidget object your page defined has five methods. The widget never creates that object itself: with the one-line snippet alone there is no object and there are no methods, although the events below are still dispatched. To use the methods, define the object before the script tag, empty or with options, as the object form shows.

Method	What it does
`open()`	Opens the panel
`close()`	Closes the panel. The conversation is kept
`toggle()`	Opens it if closed, closes it if open
`ask(question)`	Opens the panel and sends `question` exactly as if the visitor had typed and sent it
`isOpen()`	Returns `true` or `false`

ask() takes one string of up to 2,000 characters, the same limit as the widget’s own question field. An empty question, a longer one or a value that is not a string is ignored, with a warning in the browser console. A question asked while the widget is still loading the visitor’s conversation, or while an answer is arriving, is sent as soon as the widget is free. Only one question waits at a time: if ask() is called again before the waiting question has been sent, the later one replaces it. The methods return nothing, and cannot set which assistant answers, who the visitor is, or what the widget is allowed to do. Those are fixed by the embed. A snippet pasted before the rename, which defines the widget object under its older name, gets the same five methods on the object it defines. The events are named mithunai: either way. See Add the snippet to your site.

Wait for the script to load

The methods do not exist until the script has run. Guard a call with optional chaining and it is safe at any time, and listen for mithunai:ready when something must happen as soon as the widget can do it:

// Safe before and after the script loads, on a page that defined the object.
// Before, it does nothing.
window.mithunaiWidget.open?.()

function whenWidgetReady(run) {
  if (window.mithunaiWidget?.isOpen) run()
  else window.addEventListener('mithunai:ready', run, { once: true })
}

Events

The widget dispatches these on window. Each is a CustomEvent; read event.detail.

Event	When	`event.detail`
`mithunai:ready`	Once, when the widget has loaded and any methods exist	`null`
`mithunai:open`	The panel opens	`null`
`mithunai:close`	The panel closes	`null`
`mithunai:question`	A question is sent, typed or through `ask()`	`{ question: string }`
`mithunai:answer`	An answer finishes	`{ outcome: string, sources: number }`
`mithunai:error`	A question could not be answered because a request failed	`{ code: string, retryable: boolean }`

outcome is answered, abstained (the assistant found no support in your sources), truncated, filtered or failed. Treat any value you do not recognise as not answered. sources is how many sources the answer cited. mithunai:open and mithunai:close report a change. A panel that starts open because of defaultOpen dispatches no mithunai:open; call isOpen() when mithunai:ready fires to learn where it started. mithunai:error cannot say why a request failed. A browser reports a revoked embed, a request over the rate limit and a dropped connection to the widget in the same way, so do not branch on code to tell them apart; use retryable to decide whether to suggest trying again. No event carries the answer’s text, a conversation ID, the visitor token or anything identifying the visitor. An answer read back after a reload dispatches nothing: mithunai:answer is for answers that arrive while the page is open.

Examples

Open the widget from your own button, and hide the built-in launcher:

<button id="ask-docs" type="button">Ask our docs</button>

<script>
  window.mithunaiWidget = {}
  document.getElementById('ask-docs').addEventListener('click', () => {
    window.mithunaiWidget.open?.()
  })
</script>
<script
  src="https://app.mithunai.com/widget/mithunai-widget.js"
  data-api-base-url="https://app.mithunai.com/mithunai/api/v1"
  data-widget-key="mithunai_wk_..."
  data-launcher="false"
  defer
></script>

When the visitor closes the panel with Escape or its close button, focus returns to your button. Ask from your own search box:

document.getElementById('docs-search').addEventListener('submit', (event) => {
  event.preventDefault()
  const question = new FormData(event.target).get('q')
  window.mithunaiWidget.ask?.(String(question ?? ''))
})

Show your support link when a question goes unanswered:

const support = document.getElementById('contact-support')

window.addEventListener('mithunai:question', () => {
  support.hidden = true
})
window.addEventListener('mithunai:answer', (event) => {
  if (event.detail.outcome !== 'answered') support.hidden = false
})
window.addEventListener('mithunai:error', () => {
  support.hidden = false
})

Keyboard shortcut

With data-shortcut="true" (or shortcut: true on the object), Ctrl+K on Windows and Linux and Cmd+K on macOS open and close the widget. It is off by default, because many sites already use that key for their own search. The widget leaves the key alone, and your page’s own handling of it still runs, when the visitor is typing in one of your page’s inputs, text areas, select boxes or editable regions, and when your page has already handled the key. It does not respond to the key combined with Shift or Alt. Without the option the widget listens for no keys outside its own panel.

Appearance from branding

Branding setting	What it changes in the widget
Identity: product name	The default panel title
Theme: colours, corner radius	The palette and shape. The widget loads no fonts
Theme: default appearance	Light, dark, or following the visitor’s system setting
Assets: logo mark	The brand mark in the panel header
Surfaces: Show branding in the embedded widget	Whether that brand mark appears at all

A branding change needs no change to the snippet. A browser tab that is already browsing your site picks it up within 30 minutes, and a new tab at once: the widget asks for your branding once per tab and reuses the answer, so page views do not spend your embed’s request budget. Your documentation, support and legal links are not sent to the widget. 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.

Adding it to a single-page application

Load the script tag once, in the layout that wraps every page rather than in a component that mounts and unmounts. If you use the object form, define the object before the script loads. Install it on your platform has the exact code for plain HTML, WordPress, Shopify, Webflow, Wix, Google Tag Manager, React and Next.js, and Docusaurus, says which of those MITHUNAI has verified itself, and lists the Content-Security-Policy directives the widget needs.

What you cannot customise

Greeting messages, example questions and a support call-to-action inside the panel.
Per-embed colours: every embed in an organisation uses the organisation’s branding.
Follow-up question suggestions under an answer.
Telling the widget who the visitor is. Widget visitors are always anonymous.
How the widget is presented: it is a panel in a corner of the page, not a modal dialog or a sidebar.

To build a fully custom interface instead, call the widget endpoints from your own front end.

MITHUNAI RAG

Knowledge sources

Answers and assistants

Deploy

Analyze

Customise the website widget

Snippet options

The object form

Open it from your own page

Wait for the script to load

Events

Examples

Keyboard shortcut

Appearance from branding

Adding it to a single-page application

What you cannot customise

​Snippet options

​The object form

​Open it from your own page

​Wait for the script to load

​Events

​Examples

​Keyboard shortcut

​Appearance from branding

​Adding it to a single-page application

​What you cannot customise

Snippet options

The object form

Open it from your own page

Wait for the script to load

Events

Examples

Keyboard shortcut

Appearance from branding

Adding it to a single-page application

What you cannot customise