Webcomponent API

Authentication (Required)

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

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

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

• 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

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

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

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

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.