Embed Widget
Overview
Learn how the Tolki Chat embed widget works and how to customize it.
The <tolki-chat> widget is a self-contained web component that renders a floating chat interface on your website. It handles everything from the toggle button to message history persistence.
Display Modes
Floating Widget
By default, the widget appears as a floating button in a corner of the page. Clicking it opens the chat window.
<!-- Bottom-right (default) -->
<tolki-chat bot="..." position="right"></tolki-chat>
<!-- Bottom-left -->
<tolki-chat bot="..." position="left"></tolki-chat>
<!-- Bottom-center -->
<tolki-chat bot="..." position="center"></tolki-chat>
Inline Mode
In inline mode, the chat is embedded directly in the page flow without a toggle button.
<tolki-chat bot="..." position="inline"></tolki-chat>
Customization
The widget is fully customizable through HTML attributes. You can control:
- Layout — Position, window size, toggle size, margin
- Behavior — Auto-open, expandable, unclosable
- Appearance — Dark mode, border radius, backdrop effects
- Colors — Toggle button and message bubble colors
- Content — Bot name, placeholders, welcome message, suggestions
- i18n — Interface language and available locales
See the Attributes section for the complete reference.
Priority System
Attributes follow a three-level priority:
| Priority | Source | Description |
|---|---|---|
| 1 (highest) | HTML Attributes | Values set directly in the tag |
| 2 | Backend | Values from the Tolki API |
| 3 (lowest) | Defaults | Built-in fallback values |
An attribute set via HTML always overrides the backend value.