# Webkomponenten-API

### Authentifizierung (erforderlich) <a href="#authentication-required" id="authentication-required"></a>

| Name        | Typ    | Erforderlich? | Modus      | Beispiel                   | Beschreibung                                   |
| ----------- | ------ | ------------- | ---------- | -------------------------- | ---------------------------------------------- |
| `orgId`     | String | Ja            | Alle       | `"org_123"`                | Ihre Blockbrain-Org-ID.                        |
| `uid`       | String | Ja            | Alle       | `"bot_abc"`                | Eindeutige Bot-/App-Instanz-ID.                |
| `clientId`  | String | Ja            | Öffentlich | `"pub_456"`                | Öffentliche Client-ID von Blockbrain.          |
| `secretKey` | String | Ja            | Öffentlich | `"sk_live_xxx"`            | Geheimnis für den Public-Modus; privat halten. |
| `issuer`    | String | Ja            | Privat     | `"https://…blockbrain.ai"` | OAuth-Issuer-URL für Ihren Mandanten.          |

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

| Name      | Typ    | Erforderlich? | Standard                              | Beschreibung                                                                                                     |
| --------- | ------ | ------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `userUid` | String | Nein          | Bei jedem Besuch neue anonyme Sitzung | Stabile Benutzer-ID (E-Mail, Benutzername, Telefonnummer usw.), die zum Beibehalten des Verlaufs verwendet wird. |

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

| Name         | Typ                                | Erforderlich? | Standard   | Beschreibung                                                                                                                           |
| ------------ | ---------------------------------- | ------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `layout`     | `"compact" \| "minimal" \| "full"` | Nein          | `"full"`   | Wählt aus, wie viel UI-Rahmen/Platz der Chat verwendet (siehe Hinweise unten).                                                         |
| `width`      | String (CSS)                       | Nein          | `"100%"`   | Komponentenbreite. Legen Sie einen expliziten Wert fest (z. B. `"420px"`), um zu verhindern, dass sie sich horizontal ausdehnt.        |
| `height`     | String (CSS)                       | Nein          | `"100dvh"` | Komponentenhöhe. Verwenden Sie einen festen Wert (z. B. `"600px"`), damit der Chat innerhalb eines festen Containers scrollbar bleibt. |
| `themeColor` | String (CSS-Farbe)                 | Nein          | —          | Primäre Theme-Farbe für Schaltflächen und Akzente.                                                                                     |

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

* `full` – Am besten für Chat-Erlebnisse auf der gesamten Seite oder wenn der Chat der Hauptfokus ist. Es füllt den verfügbaren Platz und zeigt alle Steuerelemente.
* `minimal` – Anpassungsfähiger, leichterer Rahmen. Gut zum Einbetten in Dashboards, Seitenleisten oder Bereiche, in denen Chat wichtig, aber nicht dominant ist.
* `compact` – Extrem kompaktes, mobilähnliches Layout. Ideal für kleine Widgets, Popovers oder beengte UI-Bereiche.

> **Tipp:** Für präzise Kontrolle sollten Sie Ihr gewähltes `layout` immer mit expliziten `width` und `height`kombinieren. Lassen Sie das Layout den Rahmen wählen; lassen Sie CSS-Größen den Platzbedarf festlegen. Wenn Sie Größen weglassen, `full` nimmt gern alles, was es bekommen kann.

### Symbole & Avatare <a href="#icons-and-avatars" id="icons-and-avatars"></a>

| Name         | Typ    | Erforderlich? | Standard | Beschreibung                              |
| ------------ | ------ | ------------- | -------- | ----------------------------------------- |
| `iconUrl`    | String | Nein          | —        | Ersatzsymbol für Nachrichten.             |
| `iconSize`   | String | Nein          | —        | Größe des Ersatzsymbols (z. B. `"50px"`). |
| `userAvatar` | String | Nein          | —        | URL des Benutzer-Avatars.                 |
| `botAvatar`  | String | Nein          | —        | URL des Bot-Avatars.                      |

`introImageUrl` — URL des Startlogos, das vor der ersten Chatnachricht angezeigt wird

### Nachrichtenüberschreibungen <a href="#message-overrides" id="message-overrides"></a>

| Name       | Typ           | Erforderlich? | Beschreibung                                                                                   |
| ---------- | ------------- | ------------- | ---------------------------------------------------------------------------------------------- |
| `messages` | String (JSON) | Nein          | Anpassen `Titel`, `Beschreibung`, `iconUrl`, `iconSize` pro Status (`loading`, `error`, usw.). |

**Beispiel**

`{ "messages": { "loading": { "title": "Nur einen Moment…", "description": "Antworten werden abgerufen", "iconUrl": "/spinner.svg", "iconSize": "32px" } } }`

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

| Name                      | Typ                                 | Erforderlich? | Standard | Beschreibung                                  |
| ------------------------- | ----------------------------------- | ------------- | -------- | --------------------------------------------- |
| `defaultWebSearchEnabled` | boolesch oder `"true"/"false"`      | Nein          | `true`   | Websuche standardmäßig aktivieren.            |
| `hideReference`           | boolesch oder `"true"/"false"`      | Nein          | `false`  | Referenzlinks ausblenden.                     |
| `openDocumentMode`        | `"auto" \| "same_tab" \| "new_tab"` | Nein          | `"auto"` | Wie Dokumente geöffnet werden sollen.         |
| `disableRecording`        | boolesch                            | Nein          | `false`  | Audioaufnahme deaktivieren.                   |
| `hideTopbar`              | boolesch                            | Nein          | `false`  | Die obere Leiste der Chat-UI ausblenden.      |
| `defaultSidebarOpen`      | boolesch oder `"true"/"false"`      | Nein          | `false`  | Sidebar standardmäßig ein-/ausblenden steuern |

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

| Name               | Typ           | Erforderlich? | Beschreibung                                             |
| ------------------ | ------------- | ------------- | -------------------------------------------------------- |
| `proxyUrl`         | String        | Nein          | Proxy-Basis-URL für API-Anfragen.                        |
| `customHeaders`    | Objekt (JSON) | Nein          | Statische Header, die mit jeder Anfrage gesendet werden. |
| `getCustomHeaders` | Funktion      | Nein          | Callback zum Festlegen von Headern pro Sitzung/Anfrage.  |


---

# 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.en.theblockbrain.ai/de/fur-administratoren/webkomponenten/webkomponenten-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.