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

# Configuration reference

> Every widget option, inline panel attribute, interface string and storage key

The widget reads `window.OsviChatConfig` and the `data-*` attributes of its script tag; an attribute wins over the config object. The inline `<osvi-chat>` element takes the same settings as attributes or properties. For how to use them, see [Customise the widget](/website-chat/customise) and [Inline panel](/website-chat/inline).

## Widget options

| Option | Script attribute | Panel attribute | Type and default | Description |
| - | - | - | - | - |
| `agentId` | `data-agent` | `agent-id` | `string`, required | The agent's ID in its `agent_…` form (not a bare UUID). |
| `baseUrl` | `data-base-url` | `base-url` | `string`, `https://api.osvi.ai` | Osvi AI API base URL. Change it only for a non-production API. |
| `position` | `data-position` | | `"right" \| "left"`, `"right"` | Side of the page for the launcher and panel. Widget only. |
| `launcher` | `data-launcher` | | `"bubble" \| "none"`, `"bubble"` | `none` hides the launcher; open the panel with `OsviChat.open()`. Widget only. |
| `greeting` | `data-greeting` | | `string`, none | A dismissible bubble beside the closed launcher. Not the [welcome message](/website-chat/dashboard-settings#welcome-message). Widget only. |
| `theme.colors.primary` | `data-primary-color` | `primary-color` | CSS colour | Launcher, user bubbles and accents. The other colours are under [Theme](#theme). |
| `theme.radius` | `data-radius` | `radius` | `none`, `sm`, `md`, `lg`, `full` or pixels; `md` | Corner radius. |
| `theme.mode` | `data-mode` | `mode` | `"light" \| "dark"`, `"light"` | Colour scheme. |
| `variants.buttons` | `data-buttons` | `buttons` | `"chips" \| "list"`, `"chips"` | How button choices look. |
| `variants.carousel` | `data-carousel` | `carousel` | `"slider" \| "list"`, `"slider"` | How cards look. |
| `header.title` | `data-title` | `header-title` | `string`, the agent's name | Header title. On the panel, a bare `title` attribute is only the browser tooltip. |
| `header.subtitle` | `data-subtitle` | `header-subtitle` | `string`, none | Header subtitle. |
| `header.avatarUrl` | `data-avatar` | `header-avatar` | HTTPS URL, initial letter | Header avatar image. |
| `poweredBy` | `data-powered-by` | `powered-by` | `boolean`, `true` | Show the Powered by Osvi AI footer. |
| `newChat` | `data-new-chat` | `new-chat` | `boolean`, `true` | Show the New chat button in the header. |
| `newChatHistory` | `data-new-chat-history` | `new-chat-history` | `"clear" \| "keep"`, `"clear"` | What New chat does with the current conversation: `clear` empties the panel; `keep` leaves it above a divider. |
| `strings` | | `strings` (JSON) | object | Override interface text. See [Interface strings](#interface-strings). |
| `theme` | | `theme` (JSON) | object | The full theme. See [Theme](#theme). |
| `auth` | | | `ChatAuth`, anonymous | Anonymous, or server mode with a `getToken` callback. See [Logged-in users](/website-chat/server-mode). |

The welcome message and limits are set in the [dashboard](/website-chat/dashboard-settings), not here.

## Theme

`theme.colors` accepts `primary`, `background`, `surface`, `text`, `userBubble` and `assistantBubble`. Colours you leave out come from the light or dark defaults.

```js theme={null}
{
  mode: "dark",
  colors: {
    primary: "#6366f1",
    background: "#0a0a12",
    surface: "#1c1c27",
    text: "#f4f4f5",
    userBubble: "#6366f1",
    assistantBubble: "#1f1f2b"
  },
  radius: "lg"
}
```

## Inline panel only

| Attribute or property | Description |
| - | - |
| `closable` | Boolean attribute: when present, the panel shows a close button, even with `closable="false"`. Omit it to hide the button, or set `chat.closable = false`. |
| `client` (property) | A client you created with `createChatClient`. It takes precedence over `agent-id`, and the element does not destroy it. With only `agent-id`, the element creates an anonymous client when connected and destroys it when removed. |
| `variants`, `header` (properties) | Object forms of the variant and header attributes. |

## Interface strings

Override any of these through the `strings` option (widget) or the `strings` attribute or property (inline panel). Keys you leave out keep their English default.

| Key | Default purpose |
| - | - |
| `placeholder` | Composer placeholder. |
| `send` | Send button label. |
| `typing` | Typing indicator. |
| `humanJoined` | Human takeover indicator. |
| `chooseOption` | Pending interaction status. |
| `typeAnswer` | Typed-answer instruction. |
| `sending` | Interaction response in progress. |
| `pausedForHuman` | Choices paused during human takeover. |
| `sendFailed` | Failed message status. |
| `retry` | Retry action. |
| `sessionEnded` | Conversation divider. |
| `reconnecting` | Reconnection status. |
| `offline` | Offline status. |
| `unavailable` | Unavailable agent status. |
| `originBlocked` | Blocked origin status. |
| `rateLimited` | Rate-limit status for request-level limits. |
| `tryAgain` | Retry connection action. |
| `closeChat` | Close button accessible label. |
| `poweredBy` | Footer attribution. |
| `newChat` | New chat action. |
| `emptyState` | Empty transcript prompt. |
| `defaultTitle` | Fallback header title. |
| `chatDisabled` | Shown when Anonymous usage has been switched off ("This chat is no longer available"). The composer is disabled and the transcript stays visible. |
| `chatBusy` | Shown when the agent's daily conversation cap is reached and the visitor tries to start a conversation ("This chat is busy right now. Please try again later."). The composer re-enables after up to 5 minutes so the visitor can try again. |
| `sessionLimit` | Shown when the conversation reaches the agent's per-conversation message limit ("This conversation has reached its message limit. Start a new chat to continue."). A **New chat** button appears next to it, even when the header New chat button is turned off. |
| `rateLimitedRetry` | Shown with a countdown when the per-minute or per-hour limit is reached ("Too many messages. Retrying in {time}…"); `{time}` is replaced with the remaining wait, formatted as seconds under a minute and minutes beyond (for example "45s" or "28 min"). Custom strings may use `{seconds}` instead, which receives the raw number of seconds. The message is retried automatically up to three times, then shown as not sent with **Retry**. |
| `rateLimitedWait` | Shown instead of `rateLimitedRetry` when no wait time is known ("Too many messages. Your message will be sent automatically."). |

The defaults are English labels such as “Type your message…”, “Send”, “Retry”, and “Powered by Osvi AI”.

## Browser storage

Anonymous mode uses browser storage to remember a visitor and resume its active session. Clearing these keys changes that browser's local chat state:

| Key | What clearing it does |
| - | - |
| `osvi.chat.visitor` | Creates a new anonymous visitor identity. |
| `osvi.chat.session.<agentId>` | Removes the local session hint; the next bootstrap may discover an active session again. |
| `osvi.chat.seen.<agentId>` | Resets the local unread comparison marker. |
| `osvi.chat.greetingDismissed.<agentId>` | Allows a dismissed greeting to appear again. |

The SDK falls back to memory if browser storage is unavailable. Server mode writes none of these values.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.