> For the complete documentation index, see [llms.txt](https://docs.blockbrain.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blockbrain.ai/for-admins/web-components/webcomponent-api.md).

# Webcomponent API

### Authentication (Required) <a href="#authentication-required" id="authentication-required"></a>

| Name     | Type   | Required? | Mode    | Example                    | Description                       |
| -------- | ------ | --------- | ------- | -------------------------- | --------------------------------- |
| `orgId`  | string | Yes       | All     | `"org_123"`                | Your Blockbrain org ID.           |
| `uid`    | string | Yes       | All     | `"bot_abc"`                | Unique bot/app instance ID        |
| `issuer` | string | Yes       | Private | `"https://…blockbrain.ai"` | OAuth issuer URL for your tenant. |

### User Identification <a href="#user-identification" id="user-identification"></a>

| Name      | Type   | Required? | Default                          | Description                                                            |
| --------- | ------ | --------- | -------------------------------- | ---------------------------------------------------------------------- |
| `userUid` | string | No        | New anonymous session each visit | Stable user ID (email, username, phone, etc.) used to persist history. |

### Appearance & Layout <a href="#appearance-and-layout" id="appearance-and-layout"></a>

| Name         | Type                               | Required? | Default    | Description                                                                                                 |
| ------------ | ---------------------------------- | --------- | ---------- | ----------------------------------------------------------------------------------------------------------- |
| `layout`     | `"compact" \| "minimal" \| "full"` | No        | `"full"`   | Chooses how much UI chrome/space the chat uses (see guidance below).                                        |
| `width`      | string (CSS)                       | No        | `"100%"`   | Component width. Set an explicit value (e.g., `"420px"`) to prevent it from stretching horizontally.        |
| `height`     | string (CSS)                       | No        | `"100dvh"` | Component height. Use a fixed value (e.g., `"600px"`) to keep the chat scrollable inside a fixed container. |
| `themeColor` | string (CSS color)                 | No        | —          | Primary theme color for buttons and accents.                                                                |

#### Choosing a `layout` <a href="#choosing-a-layout" id="choosing-a-layout"></a>

* `full` – Best for full‑page chat experiences or when the chat is the main focus. It expands to fill available space and shows all controls.
* `minimal` – Adaptive, lighter chrome. Good for embedding in dashboards, side panels, or sections where chat is important but not dominant.
* `compact` – Ultra‑tight, mobile‑style layout. Ideal for tiny widgets, popovers, or cramped UI areas.

> **Tip:** For precise control, always pair your chosen `layout` with explicit `width` and `height`. Let the layout pick the chrome; let CSS sizes define the footprint. If you skip sizes, `full` will happily take everything it can.

### Icons & Avatars <a href="#icons-and-avatars" id="icons-and-avatars"></a>

| Name         | Type   | Required? | Default | Description                          |
| ------------ | ------ | --------- | ------- | ------------------------------------ |
| `iconUrl`    | string | No        | —       | Fallback icon for messages.          |
| `iconSize`   | string | No        | —       | Fallback icon size (e.g., `"50px"`). |
| `userAvatar` | string | No        | —       | User avatar URL.                     |
| `botAvatar`  | string | No        | —       | Bot avatar URL.                      |

`introImageUrl` — URL of the starter logo displayed before the first chat message

### Message Overrides <a href="#message-overrides" id="message-overrides"></a>

| Name       | Type          | Required? | Description                                                                                    |
| ---------- | ------------- | --------- | ---------------------------------------------------------------------------------------------- |
| `messages` | string (JSON) | No        | Customize `title`, `description`, `iconUrl`, `iconSize` per status (`loading`, `error`, etc.). |

**Example**

`{ "messages": { "loading": { "title": "Just a sec…", "description": "Fetching answers", "iconUrl": "/spinner.svg", "iconSize": "32px" } } }`

### Feature Toggles <a href="#feature-toggles" id="feature-toggles"></a>

| Name                      | Type                                | Required? | Default  | Description                          |
| ------------------------- | ----------------------------------- | --------- | -------- | ------------------------------------ |
| `defaultWebSearchEnabled` | boolean or `"true"/"false"`         | No        | `true`   | Enable web search by default.        |
| `hideReference`           | boolean or `"true"/"false"`         | No        | `false`  | Hide reference links.                |
| `openDocumentMode`        | `"auto" \| "same_tab" \| "new_tab"` | No        | `"auto"` | How to open documents.               |
| `disableRecording`        | boolean                             | No        | `false`  | Disable audio recording.             |
| `hideTopbar`              | boolean                             | No        | `false`  | Hide the chat UI top bar.            |
| `defaultSidebarOpen`      | boolean or `"true"/"false"`         | No        | `false`  | Control Show/Hide Sidebar by default |

### Proxy / Advanced <a href="#proxy-advanced" id="proxy-advanced"></a>

| Name               | Type          | Required? | Description                                  |
| ------------------ | ------------- | --------- | -------------------------------------------- |
| `proxyUrl`         | string        | No        | Proxy base URL for API requests.             |
| `customHeaders`    | object (JSON) | No        | Static headers sent with every request.      |
| `getCustomHeaders` | function      | No        | Callback to set headers per session/request. |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.blockbrain.ai/for-admins/web-components/webcomponent-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.