Chat Widgets
Chat Widgets are interactive Liquid HTML + CSS UIs rendered inside an agent chat message. An agent shows one during a turn to present data in a richer layout; the end user can interact, and configured events turn clicks into a chat message back to the AI.
These are not iframe widgets (dashboard and sidebar pages with window.vt).
When to use
- Display data in a UI-friendly format instead of plain chat text
- Collect input from the user and send it as a message to the AI
- Offer clicks and picks in-chat so the user does not have to type a free-text reply
Create a chat widget
Open Build → Chat Widgets for a workspace-wide widget, or open an agent’s builder and use the Chat Widgets panel for one scoped to that agent.
- Click Create Widget (or Build With AI to draft it in Studio).
- Enter a Name and optional Description.
- Click Create — Vettero opens the chat widget detail page.
Workspace chat widgets appear under Global in the agent tools picker; agent-scoped ones appear under Local.
Configure the chat widget
From the detail page, click Edit. Use the sticky Live preview with sample args from your schema.
| Section | What you configure |
|---|---|
| Name / Description | Identity; the description becomes agent tool help text |
| Input arguments (schema) | JSON Schema for render-time args → {{ args.* }} in HTML |
| Events | Maps emit("id", …) to chat text the user and AI see |
| HTML (Liquid) | Markup fragment — no <script> tags. Prefer vt-card, vt-btn, and the other vt-* classes |
| CSS | Optional custom rules. Use var(--vt-surface), var(--vt-text), var(--vt-primary), and the other theme variables |
Define events
Click Add event for each interaction you want to send back into chat.
| Field | What it does |
|---|---|
| Event ID | The string you pass to emit("…") in HTML |
| Display Message | What the user sees in the chat transcript |
| AI Message (optional) | What the model receives; defaults to the display message when empty |
Message fields support simple {{ path }} placeholders over the emit payload (for example {{ orderId }}), not full Liquid.
Write HTML and CSS
Use Liquid against args, state, and decision. Interactivity uses allowlisted handlers only:
| Helper | What it does |
|---|---|
updateState({…}) | Merge into local widget state |
setState({ path, value }) | Set a single state path |
emit("eventId", {…}) | Fire a configured event and post chat text |
Allowed DOM events: @click, @input, @change, @submit. HTML is sanitized — no scripts. Write the handler in single quotes, for example @click='emit("confirm", {"orderId": args.orderId})'. The object can use args.*, state.*, and event.target.value.
The chat UI injects the current theme (company primary color and dark mode) before your CSS. Prefer the built-in classes so the widget matches the rest of the app.
| Class | What it is |
|---|---|
vt-grid | Auto-fit card grid |
vt-card | Bordered panel |
vt-label / vt-value | Metric label and value |
vt-muted | Secondary text |
vt-btn / vt-btn-primary | Buttons |
vt-input | Text input |
<div class="vt-card">
<div class="vt-label">Order</div>
<div class="vt-value">{{ args.orderId }}</div>
<button type="button" class="vt-btn-primary" @click='emit("confirm", {"orderId": args.orderId})'>
Confirm
</button>
</div>
For custom layout, use the theme variables. They follow dark mode without a separate palette:
.note {
background: var(--vt-surface-muted);
color: var(--vt-text);
border-radius: var(--vt-radius);
padding: var(--vt-space);
}
Attach to an agent
In the agent builder, open Config → Tools → Manage Tools → Chat Widget. Pick a chat widget.
When the agent calls the tool, the chat UI renders the HTML/CSS as an in-message widget. User events post a text message back into the conversation.
You can also type # in the agent Task and select the chat widget to mention and attach it.
Limits
- Name is required (cannot be empty).
- No
<script>tags — only allowlisted event attributes and the three runtime helpers. - CSS is isolated to the Shadow DOM.
- Only usable in agent chat.
- Delete moves the widget to trash for the workspace retention period.
Where chat widgets are used
| Place | How |
|---|---|
| Agents | Tools → Chat Widget, or # mention in the Task |