Blocks are interactive UI cards your AI agent can render inside the chat widget — product carousels, FAQ lists, contact forms, booking slots, and more.
What are blocks?
A block is a reusable template (JSX layout + state + actions). When the agent needs rich UI, it calls a render tool (if AI Access is enabled) and the widget shows the card in the conversation.
Operators design blocks in Dashboard → Blocks. Visitors interact with them in the embedded messenger. Staff can also interact with the same cards in the inbox and Test Agent.
Create a block
- Open Blocks in the dashboard.
- Start from a template or a blank block.
- Edit JSX, functions, variables, and test data.
- Turn AI Access on when the agent should be allowed to render it.
- Save. Use a slug name: letters, numbers,
_, and-only.
Component reference
Layout
| Component | Purpose | Key props |
|---|---|---|
Box | Generic container (column flex) | padding, background, border, radius, width, height, spacing (mt, mb, …) |
Col | Vertical stack | gap, align, justify, spacing |
Row | Horizontal stack | gap, align, justify, spacing |
Card | Elevated panel | padding, background, border, radius, shadow (xs–lg), status |
Carousel | Scrollable row/column of children | gap, orientation (horizontal | vertical) |
CarouselItem | Item in a carousel (often clickable) | action, params |
Spacing values are unitless numbers multiplied by 4px (e.g. padding={4} → 16px), or CSS strings.
Colors / backgrounds accept design tokens: primary, secondary, surface, surface-elevated, surface-secondary, text, text-secondary, border, success, error, transparent, or any CSS color.
Clickable layout: Box, Col, Row, Card, and CarouselItem support action / params the same way as Button. When bound, they become keyboard-focusable buttons.
Content
| Component | Purpose | Key props |
|---|---|---|
Text | Body text | value (or children), size (xs–xl), weight, color / colour, maxLines, spacing |
Title | Heading | value (or children), size, weight, color, spacing |
Caption | Secondary line | value (or children), size, color, spacing |
Label | Form label | value, fieldName (associates with input id) |
Image | Image | src, alt, height, width, fit (cover | contain), radius, background |
Prefer value={…} for dynamic text. Children work when value is omitted.
Actions
| Component | Purpose | Key props |
|---|---|---|
Button | Primary control | label, action, params, variant (solid | outline), size (sm | md | lg), color (primary | secondary | danger), block, disabled, iconStart, iconEnd |
Bind a named function:
Forms
| Component | Purpose | Key props |
|---|---|---|
Input | Single-line field | name (state key), placeholder, type, disabled, value (optional; bound from state) |
TextArea | Multi-line field | name, placeholder, rows, disabled |
Typing updates block state under name. Values are buffered for performance and flushed on blur / short debounce.
Common patterns
Map over arrays:
Conditionals:
Expressions
A restricted expression language supports:
!pathpath === literal/!==/==/!=&&/||- Ternaries:
a ? b : c - String concat:
'Selected: ' + selectedSlot
Paths resolve against block state and map item scope (e.g. item.id, product.name).
Arbitrary JavaScript is not evaluated (no function calls, no property assignment).
Actions (functions)
Functions are defined on the block and invoked by action="functionName".
| Type | Behavior |
|---|---|
setVariables | Updates block state (client-side). Can chain onSuccess. |
sendMessage | Posts a message into the chat thread. |
serverFunction | Server HTTP call using config on the render snapshot (secrets never sent to the browser). |
clientFunction | Dispatches messenger:function-call for the host page. |
openLink / hideBlock / dismissWidget | Navigation and UI helpers. |
params from the component become available as {{params.*}} or {{additionalInputs.*}} in variable templates.
Example submit that sets state then sends a message:
AI Access & schema
When AI Access is on, the agent receives a tool named after the block. Provide a JSON Schema (Schema tab) so the model knows which data to pass (products, FAQ items, etc.).
Without AI Access, blocks can still be used via other integrations, but the default agent tools will not include them.
Host page: client functions
clientFunction actions emit:
Respond within 30s or the call times out.
Troubleshooting
- Raw
__BLOCK__:{…}in chat — Older surfaces without the block renderer showed markers as text. Inbox and Test Agent now render interactive blocks. - Clicks do nothing on a Row — Use
action="…"; layout components forward clicks when an action is bound. - Form never submits — Prefer
Input/TextAreawithname, andsetVariables+onSuccess: sendMessagefor submit. - Agent never shows my block — Enable AI Access and ensure the name is unique in the workspace.

