Embed reference

Purpose

The configurator generates the embed code; anyone who writes it by hand, builds it into templates or connects it to their own JavaScript will find all attributes, variables, events and endpoints here. Everything below applies to the script tag that Chapters 8 and 9 describe.

The chat loader

<script src="https://<instance>/js/embed.js"
        data-project="93"
        data-title="Musterfirma Service-Chat"
        data-accent="#1f4e79"></script>

The loader fetches the stylesheet, the chat logic and, if needed, the voice function itself and reads the collection's settings from the server. Only deviations are placed as attributes on the tag.

Collection, assistant, language

Attribute	Meaning
`data-project`	Number of the collection. Mandatory.
`data-task`	Number of an assistant. Greeting, starter questions, accent colour and knowledge scope then come from the profile.
`data-language`	Language of the page; `auto` reads it from `<html lang>`. Answers, knowledge base and texts follow it.
`data-llm`	Number of an additional LLM configuration of the collection.
`data-endpoint`	Only for special cases: a different address of the instance.

Display and behaviour

Attribute	Meaning
`data-mode="inline"`	Fixed in the page instead of as a bubble; `data-target="#selector"` mounts it into an element, otherwise behind the script tag.
`data-position`	Corner of the bubble: `bottom-right`, `bottom-left`, `top-right`, `top-left`.
`data-offset-x`, `data-offset-y`	Distance of the bubble from the edges in pixels.
`data-open="1"`	Panel starts open. `data-open-delay="5"` after seconds, `data-open-scroll="50"` from a scroll depth in percent.
`data-open-selector`	CSS selectors of your own elements whose click opens the panel.
`data-remember="0"`	No longer remembers open/closed for the visit.
`data-mobile`	`full`, `bubble` or `hidden` on smartphones.
`data-pages`	Paths on which the chat loads; as a wildcard, `!` excludes: `/support/``, !/support/intern`.
`data-stream="0"`	Answers without streaming.
`data-voice="1"`	Voice chat on, if the collection offers it.
`data-off`	Hide functions of this embed, comma-separated: `upload`, `feedback`, `sources`, `reset`, `simple`, `help`, `escalation`, `attest`. The microphone is controlled by `data-voice`.

Appearance

Attribute	Meaning
`data-theme`	`light`, `dark` or `auto` according to the system setting.
`data-accent`	Accent colour `#rrggbb`.
`data-header`, `data-header-text`	Header bar and its text colour.
`data-text`, `data-bg`, `data-surface`, `data-border`	Text colour, background, input field and buttons, border.
`data-bubble`, `data-user-bubble`	Answer and visitor bubble.
`data-chip-hover`, `data-send-hover`	Colours when hovering over the starter questions and the send button.
`data-radius`	Corner radius of the chat in pixels.
`data-shape`	Controls: empty = round, `square` = subtly rounded, `sharp` = angular.
`data-shadow="0"`	Without shadow.
`data-font`, `data-font-size`	Font family and size in pixels.
`data-width`, `data-height`	Dimensions of the panel in pixels.
`data-css="0"`	Load no stylesheet; you supply the CSS (see variables).

Texts and links

Attribute	Meaning
`data-title`, `data-greeting`, `data-label`, `data-placeholder`	Title line, greeting, label next to the bubble, placeholder. With `data-language="auto"` the texts come per language from the server; the attributes override them.
`data-privacy-url`, `data-help-url`	Privacy link in the widget and help link behind the ? button.

Consent

Attribute	Meaning
`data-consent`	`cookiebot:<category>`, `usercentrics:<service>`, `event:<name>` or `cookie:<name>[=<value>]`. The widget loads only after consent.
`data-consent-text`	Text in the chat's place until then, only with in-page embedding.

With the event mode, your website fires an event with the given name on window after consent.

Signed-in visitors

data-user-token passes the signed token (Chapter 13). Alternatively, your page sends it after loading with the event aic:user-token. The token is an HS256 JWT, signed with the collection's identity secret, with the claims sub (mandatory), exp (mandatory, at most 24 hours), name, groups (list) and attrs (object).

JavaScript interface

window.aicChat is available after loading: open(), close(), toggle(), isOpen() and ask("question"), which asks a question as if it came from the visitor.

Events on document:

Event	When
`aic:ready`	The widget has loaded.
`aic:open`, `aic:close`	The panel was opened or closed.
`aic:sent`, `aic:answer`	A question was sent, an answer has arrived.
`aic:navigate`	The visitor clicks a source or a link; for websites that control page changes themselves.
`aic:help`	The help overlay is opened.
`aic:lang`	The conversation language was detected or changed.
`aic:restored`	A conversation history was restored from session storage.

CSS variables

With data-css="0" you supply the stylesheet yourself. The configurator generates a CSS or SCSS template with all variables; the most important:

Variable	Meaning
`--aic-chat-primary`	Accent colour.
`--aic-chat-bg`, `--aic-chat-surface`, `--aic-chat-text`, `--aic-chat-muted`, `--aic-chat-border`	Base colours.
`--aic-chat-assistant-bg`, `--aic-chat-user-bg`	Bubbles.
`--aic-chat-chip-hover`, `--aic-chat-send-hover`	Hover colours.
`--aic-chat-radius`, `--aic-chat-shadow`, `--aic-chat-font`, `--aic-chat-font-size`	Rounding, shadow, font.
`--aic-embed-accent`, `--aic-embed-header-bg`, `--aic-embed-header-text`, `--aic-embed-width`, `--aic-embed-height`, `--aic-embed-x`, `--aic-embed-y`, `--aic-embed-radius`, `--aic-embed-shadow`	Bubble and panel.

The search loader

<script src="https://<instance>/js/search-embed.js"
        data-project="93"
        data-target="#site-search"></script>

Attribute	Meaning
`data-project`	Number of the collection. Mandatory.
`data-language`	Search language; `auto` reads `<html lang>`.
`data-mode`	`hybrid`, `keyword` or `semantic`.
`data-limit`	Results per page, 5 to 50.
`data-live="1"`	Search while typing.
`data-target`	Element into which the search is placed.
`data-title`, `data-placeholder`, `data-button`	Heading, placeholder, button text. Per additional language with a language suffix, for example `data-title-en`; with `data-language="auto"` the version of the page language applies, otherwise the attribute without suffix. The configurator writes them.
`data-accent`, `data-border`, `data-shape`, `data-font`	Appearance.
`data-css="0"`	No stylesheet; variables `--aic-s-primary`, `--aic-s-border`, `--aic-s-muted`, `--aic-s-text`, `--aic-s-font`, `--aic-s-radius`.

After loading, window.aicSearchInit is available for pages that mount the search themselves; a click on a result fires aic:search-navigate.

Public endpoints

Address	Purpose
`/api/chat`, `/api/chat/stream`	The widget's questions, streamed or in one piece.
`/api/chat/help`, `/api/chat/starters`, `/api/chat/attest`	Settings and help text of the embed, automatic starter questions, proof of the processing region.
`/api/search`	The search.
`/api/mcp`	Endpoint for AI agents (Chapter 14).
`/js/embed.js`, `/js/search-embed.js`	The loaders, with version stamp.

All of them check the collection's allowed websites. If the embedding page uses a Content Security Policy, the instance's address must be in script-src, style-src, connect-src and img-src, for the voice chat additionally the WebSocket address in connect-src.