# 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.       |
| `clientId`  | string | Yes       | Public  | `"pub_456"`                | Public client ID from Blockbrain. |
| `secretKey` | string | Yes       | Public  | `"sk_live_xxx"`            | Public‑mode secret; keep private. |
| `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: 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:

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

The question should be specific, self-contained, and written in natural language.
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.