Message blocks

A message is not a string. It is an envelope containing an ordered list of blocks, each of which knows how to draw itself. Think of it less as a letter and more as a tray: several things arrive together, and each one has its own shape.

This matters because it is why an agent can answer “do you have this in blue” with a picture, a price and a button, rather than a paragraph describing all three.

The blocks

Block	What it renders
text	Markdown. The workhorse.
quick_replies	Tappable suggested answers.
buttons	Explicit actions. See below.
card	One item: image, title, body, actions.
carousel	Several cards, swipeable.
media	An image, video or file on its own.
form	Several fields collected in one go.
input_request	A single value, asked for inline.
live_tracker	Live status for an order, shipment or ticket.
divider	A labelled break in the thread.
typing	The three dots.

Button kinds

Buttons are typed rather than free-form, so the widget knows what a tap means without guessing.

Kind	Does
url	Opens a link, in a new tab or the same one.
postback	Sends a payload back to the agent as if the visitor had said it.
escalate	Asks for a human.
auth	Starts sign-in.
phone	Dials a number.
open_product	Opens a catalog item in the widget.

The distinction between url and postback is worth internalising. A url button ends the conversation and starts a page load. A postback keeps the person exactly where they are and moves the conversation forward. When in doubt, prefer the one that does not throw away the context you just built.

Quick replies

Quick replies are the widget’s way of asking a closed question without closing the door. They render as tappable chips, and the visitor can still ignore them and type whatever they like. They are suggestions, not a menu, and an agent that treats them as a menu will frustrate the one person who wanted something else.

Sources

An assistant message can carry sources, each with a title and a URL. If the answer came from your knowledge base, this is what lets the widget show its working. Citations are cheap to display and expensive to omit: an answer nobody can verify is an answer somebody will escalate.