WebbleWebble

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

  1. Open Blocks in the dashboard.
  2. Start from a template or a blank block.
  3. Edit JSX, functions, variables, and test data.
  4. Turn AI Access on when the agent should be allowed to render it.
  5. Save. Use a slug name: letters, numbers, _, and - only.

Component reference

Layout

ComponentPurposeKey props
BoxGeneric container (column flex)padding, background, border, radius, width, height, spacing (mt, mb, …)
ColVertical stackgap, align, justify, spacing
RowHorizontal stackgap, align, justify, spacing
CardElevated panelpadding, background, border, radius, shadow (xs–lg), status
CarouselScrollable row/column of childrengap, orientation (horizontal | vertical)
CarouselItemItem 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

ComponentPurposeKey props
TextBody textvalue (or children), size (xs–xl), weight, color / colour, maxLines, spacing
TitleHeadingvalue (or children), size, weight, color, spacing
CaptionSecondary linevalue (or children), size, color, spacing
LabelForm labelvalue, fieldName (associates with input id)
ImageImagesrc, alt, height, width, fit (cover | contain), radius, background

Prefer value={…} for dynamic text. Children work when value is omitted.

Actions

ComponentPurposeKey props
ButtonPrimary controllabel, action, params, variant (solid | outline), size (sm | md | lg), color (primary | secondary | danger), block, disabled, iconStart, iconEnd

Bind a named function:

<Button
  label="Add to cart"
  action="addToCart"
  params={{ id: product.id, name: product.name }}
/>
<Row action="toggleFaq" params={{ id: item.id }}>
  <Text value={item.question} />
</Row>

Forms

ComponentPurposeKey props
InputSingle-line fieldname (state key), placeholder, type, disabled, value (optional; bound from state)
TextAreaMulti-line fieldname, placeholder, rows, disabled
<Label value="Email" fieldName="formEmail" />
<Input name="formEmail" type="email" placeholder="you@example.com" />

Typing updates block state under name. Values are buffered for performance and flushed on blur / short debounce.

Common patterns

Map over arrays:

{products.map((product) => (
  <Card>
    <Title value={product.name} />
    <Button label={product.cta} action="addToCart" params={{ id: product.id }} />
  </Card>
))}

Conditionals:

{!submitted ? (
  <Button label="Submit" action="submitForm" />
) : (
  <Text value="Thanks!" />
)}
{item.id === openFaqId && (
  <Text value={item.answer} />
)}

Expressions

A restricted expression language supports:

  • !path
  • path === 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".

TypeBehavior
setVariablesUpdates block state (client-side). Can chain onSuccess.
sendMessagePosts a message into the chat thread.
serverFunctionServer HTTP call using config on the render snapshot (secrets never sent to the browser).
clientFunctionDispatches messenger:function-call for the host page.
openLink / hideBlock / dismissWidgetNavigation 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:

{
  "name": "submitForm",
  "type": "setVariables",
  "config": { "variables": { "submitted": true } },
  "onSuccess": {
    "type": "sendMessage",
    "config": {
      "message": "Submitted by {{formName}}"
    }
  }
}

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:

window.addEventListener('messenger:function-call', (e) => {
  const { callId, functionName, params, state } = e.detail
  // …run host logic…
  window.dispatchEvent(
    new CustomEvent('messenger:function-response', {
      detail: { callId, result: { ok: true } },
    }),
  )
})

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/TextArea with name, and setVariables + onSuccess: sendMessage for submit.
  • Agent never shows my block — Enable AI Access and ensure the name is unique in the workspace.