> ## Documentation Index > Fetch the complete documentation index at: https://docs.openmic.ai/llms.txt > Use this file to discover all available pages before exploring further. # Chat Widget > Embed the OpenMic chat widget so visitors can message your AI agent from any web page — HTML and React setup, attribute reference, and troubleshooting. The chat widget adds a floating chat button to your site. Clicking it opens a panel where visitors type to the same agent that answers your calls — same prompt, same knowledge base, same tools. The widget renders inside a **Shadow DOM**, so your site's CSS cannot break it and its styles cannot leak into your page. It works on sites using Tailwind, Bootstrap, aggressive CSS resets, and strict Content Security Policies. ## Quick start Paste this before the closing `` tag of any page: ```html theme={null} ``` A chat button appears in the bottom-right corner of the page. The dashboard generates this snippet pre-filled under any agent's **Widget** tab. The package is **scoped** — `@openmic/openmic-chat-widget`. The unscoped name `openmic-chat-widget` has no published versions, so a script URL without the `@openmic/` prefix will 404. The chat widget identifies agents with `bot-uid`, while the [voice widget](/web-calls/voice-widget) uses `assistant-id`. Both take the same agent UID — only the attribute name differs. ### Complete working page ```html theme={null} Support

Support

Questions? Use the chat button in the corner.

``` ## Attributes | Attribute | Required | Default | Description | | ---------------- | -------- | ---------------------------- | -------------------------------------------------------------------- | | `bot-uid` | **Yes** | — | UID of the agent to chat with. Required unless you use `bot-id`. | | `bot-id` | — | — | Numeric agent ID, an alternative to `bot-uid`. | | `public-api-key` | **Yes** | — | Your organization's public key (`omic_pub_...`). Never a secret key. | | `title` | No | `OpenMic Agent` | Heading shown at the top of the chat panel. | | `status-text` | No | `Online now` | Status line under the title. | | `placeholder` | No | `Ask a detailed question...` | Placeholder text in the message input. | | `api-base` | No | `https://api.openmic.ai/v1` | API base URL. Override only for local development. | Every attribute also accepts a `data-` prefix (`data-bot-uid`, `data-public-api-key`, and so on) for stricter HTML validators. The unprefixed form takes precedence when both are present. `subtitle` and `primary-color` are **not supported** by the current build. They appear in the package README and in the dashboard's generated snippet, but the widget never reads them — setting either has no effect. Unlike the voice widget, the chat widget has no demo fallback. If `bot-uid` and `bot-id` are both missing it logs `Missing bot-uid or bot-id attribute` and disables itself rather than connecting to something unexpected. ## Using it in React The chat widget watches the DOM for elements being added and removed, so it initializes correctly in React and other SPAs with no extra work. Render the script and the element together: ```jsx theme={null} import { useEffect } from "react"; const WIDGET_SRC = "https://unpkg.com/@openmic/openmic-chat-widget@latest/widget/widget-standalone.js"; export default function ChatWidget() { useEffect(() => { if (document.querySelector(`script[src="${WIDGET_SRC}"]`)) return; const script = document.createElement("script"); script.src = WIDGET_SRC; document.body.appendChild(script); }, []); return ( ); } ``` Re-loading the script is a no-op and multiple widgets on one page work independently, so you do not need to coordinate mounting the way the [voice widget](/web-calls/voice-widget#using-it-in-react) requires. When the element unmounts, the widget tears down its listeners and cancels in-flight requests automatically. ### TypeScript ```ts theme={null} declare global { namespace JSX { interface IntrinsicElements { "openmic-chat-widget": { "bot-uid"?: string; "bot-id"?: string; "public-api-key"?: string; title?: string; "status-text"?: string; placeholder?: string; "api-base"?: string; }; } } } export {}; ``` ## Behaviour worth knowing The active chat session is persisted in `localStorage`, so a visitor who reloads or navigates keeps their conversation. Sessions that have expired server-side recover gracefully with a "session expired" message rather than failing silently. Transient network errors and 5xx responses are retried up to three times with exponential backoff (250ms, 500ms, 1000ms). 4xx responses — bad key, wrong agent UID — fail immediately without retrying. Closing the panel aborts any in-flight request, so a message the visitor never sees is not billed. The chat panel's DOM is only built the first time a visitor clicks the launcher, so pages where nobody opens chat pay almost nothing for having the widget present. Chrome 89+, Firefox 85+, Safari 14+, Edge 89+. The widget checks at load time for `fetch`, `ReadableStream`, `MutationObserver`, `AbortController`, and Shadow DOM; if any are missing it logs a clear error and disables itself instead of half-working. To point the widget at a backend running on your machine, set `api-base`: ```html theme={null} ``` Unlike the voice widget, the chat widget works normally when served from `localhost`. ## Troubleshooting | Symptom | Cause | Fix | | ------------------------------------------------------------------ | ---------------------------------- | -------------------------------------------------------------------------------------- | | No chat button; console says `Missing bot-uid or bot-id attribute` | Neither identifier was set | Add `bot-uid` with your agent's UID | | Script 404s | Unscoped package name | Use `@openmic/openmic-chat-widget` in the URL | | Button appears, messages fail with 401 | Wrong or inactive key | Confirm the key starts with `omic_pub_` and the agent belongs to the same organization | | `subtitle` or `primary-color` does nothing | Not supported by the current build | Use `status-text` for a second line; colors are not yet configurable | | Nothing at all, console mentions unsupported browser | Missing required browser features | Test on a current version of a supported browser | All widget logs are prefixed with `[openmic-chat-widget]`, so filtering the console by that string shows exactly what happened.