Generative UI on Slack

The generative UI tree your assistant renders in the browser is plain JSON, so it does not have to stay in the browser. @assistant-ui/generative-ui/slack converts the same tree into Block Kit JSON, decodes the interactions Slack posts back, and parses Block Kit payloads into the tree.

The subpath is React-free, so a server action, queue worker, or webhook handler imports it without pulling React into the bundle.

Posting a tree

import { WebClient } from "@slack/web-api";
import { toSlackBlocks } from "@assistant-ui/generative-ui/slack";

const slack = new WebClient(process.env.SLACK_BOT_TOKEN);

const { blocks, warnings } = toSlackBlocks({
  $type: "Card",
  title: "Order #48213",
  children: [{ $type: "Text", value: "Shipped, arriving Thursday." }],
});

await slack.chat.postMessage({ channel: "#orders", blocks });

A spec from spec mode converts with specToUISpec from the React-free @assistant-ui/generative-ui/spec/tree first, as Moving to spec mode describes.

toSlackBlocks(node, options?) returns { blocks, warnings } and never throws: an input it cannot convert at all comes back as empty blocks plus one warning rather than an exception. Pass { surface: "modal" } to target a modal instead of a message; the surface changes the block budget and unlocks the native alert block.

Update a message as the spec streams

Feed complete JSONL patch lines into createSpecStream. Post when the root element exists and produces blocks, then update that message at most once every 1500 ms, and once more when the stream ends. specLines below is an async iterable of lines from your model:

import { WebClient } from "@slack/web-api";
import { createSpecStream, type Spec } from "generative-frame/spec";
import { specToUISpec } from "@assistant-ui/generative-ui/spec/tree";
import { toSlackBlocks } from "@assistant-ui/generative-ui/slack";

const slack = new WebClient(process.env.SLACK_BOT_TOKEN);
const stream = createSpecStream();
const channel = "#orders";
let message: { channel: string; ts: string } | undefined;
let lastUpdate = 0;

async function publish(spec: Spec, final = false) {
  if (!spec.elements[spec.root]) return;
  if (message && !final && Date.now() - lastUpdate < 1500) return;
  const { blocks } = toSlackBlocks(specToUISpec(spec));
  if (blocks.length === 0) return;

  if (!message) {
    const posted = await slack.chat.postMessage({ channel, blocks });
    if (!posted.channel || !posted.ts) throw new Error("Slack did not return a message location.");
    message = { channel: posted.channel, ts: posted.ts };
    lastUpdate = Date.now();
    return;
  }

  await slack.chat.update({ ...message, blocks });
  lastUpdate = Date.now();
}

for await (const line of specLines) {
  await publish(stream.push(`${line}\n`).spec);
}
await publish(stream.result().spec, true);

The host owns the stream transport and Slack rate limits. A control can be clicked as soon as an update shows it, so your action handler has to accept a click for an element a later update removed, or for one whose params had not streamed yet.

Warnings

Conversion is total. Every downgrade is reported rather than thrown, so one unsupported node does not fail the whole message:

type SlackConversionWarning = {
  code: "clamped" | "dropped" | "fallback";
  component: string; // the IR component name, or "Root" for whole-payload issues
  detail: string;
};

clamped means content was truncated to fit a Slack limit, dropped means a node or one of its props was discarded and may have left a placeholder note behind (an oversized button payload is dropped while the button itself is kept, a Chart becomes an omission note), and fallback means the node rendered through a different construct than requested. Warnings arrive in traversal order and are not deduplicated. Log them in development to see why a composition looks different on Slack than in the browser.

Component mapping

RadioGroup and CheckboxGroup option descriptions map to Slack option description text.

Slack has no undo surface, so a Button with undoable fires immediately.

An unknown component and a bare string child are both handled: the unknown one is dropped with a warning, and the string becomes a section.

Presentation props the converter does not map are dropped silently, without a warning, because the node itself still renders. That covers Box's width, height, radius, and background; Card's padding and background; gap on Row, Col, and Form, align on Row and Col, and justify on Row; Badge's variant; Carousel's label; CheckboxGroup's progress; and Button's block. Slack has no client-side form model to submit into, so Button's submit is dropped: a submit button and a click button both convert to the same button element carrying the node's $action. A Card marked asForm also cannot collect its child values into a browser-style form payload, but it keeps child Input actions passive so those inputs do not dispatch separately.

Date and time pickers

DatePicker.inputType defaults to "date", which emits a datepicker with a YYYY-MM-DD value. "time" emits a timepicker with HH:mm; nonzero seconds in an HH:mm:ss value are dropped with a dropped warning. Neither time-only pickers nor the time half of a local datetime set Slack's timezone field.

With "datetime", a value carrying Z or an offset such as +02:00 is an instant. It emits a datetimepicker initialized with Unix seconds, which Slack displays in the viewer's zone. Decoding preserves the original offset spelling at seconds precision. An empty datetime also emits a datetimepicker; once selected, it decodes with Z at seconds precision because Slack's payload carries no viewer offset. Nonzero fractional seconds are dropped with a dropped warning because Slack's instant picker only supports second precision.

A datetime without an offset, such as 2025-12-15T17:00, is local wall time. It emits separate datepicker and timepicker controls for the same field and decodes to YYYY-MM-DDTHH:mm. Nonzero seconds or fractions are dropped with a warning. A field reference resolves to "" when either half is empty; an action from either half returns undefined until both have a value. Pass the companion state values to decodeBlockAction so it can merge the selections.

min and max are dropped in all modes. A value that does not match its mode is omitted with a dropped warning. The mode, original offset, and split-pair identity travel in the existing block ID metadata, including for unnamed controls. The same 255-character cap and omission warning apply.

Cards

Card takes the native card block only when its children fit that block's fixed fields, because Slack's card carries hero_image, title, body, subtext, and up to three action buttons rather than nesting arbitrary blocks. The converter fills those from the first Image, the first Text or Markdown, and the first Caption.

Anything else in the card, including a second image, a Fact, or a loose Button, makes the card fall back to a header plus the children rendered inline plus an actions block, and reports a fallback warning. A card carrying none of an image, title, body, or actions is dropped outright.

On a Card marked asForm, the confirm button carries the confirm footer's $action, or the Card's own $action when the footer has none. A form card with its own $action and no confirm footer gets a primary "Submit" button where the confirm button would go, ahead of any cancel button.

Inside a Carousel that fallback is unavailable, so an over-full card is reshaped to title and body text instead, with a fallback warning. Text carried in a text, value, label, title, or description prop survives the reshape at any depth, which covers a Caption's text and a Button's label. An image, a Table, a Chart, and any control do not, since none of them is text, and those are reported separately as dropped so the two facts stay distinguishable. A control here is a Button, Select, Slider, DatePicker, Checkbox, RadioGroup, CheckboxGroup, Input, or Form, plus a ListViewItem or a nested Card footer that carries an action, and the "Submit" button a form card gets from its own $action. An $action on a layout node such as Box, Col, or Row does not count, because those render no control on the clean path either.

Limits

The converter clamps to Slack's published budgets rather than letting the API reject the payload. Caps on mrkdwn fields count the escaped text, where &, <, and > take five, four, and four characters (&, <, >), and a plain @here, @channel, or @everyone gains an invisible word joiner after its @ so Slack shows it as text instead of notifying the channel. Markdown blocks count their escaped text against the markdown budget the same way. The budgets you are most likely to hit:

Traversal itself is bounded too: 200 children per level, 5,000 nodes per call, and 32 levels of element nesting, each reported as a Root warning. These bounds exist because the tree arrives from a model.

Actions

Outbound

A node's $action is split across two Block Kit fields. $action.type becomes the element's action_id, and the remaining keys are JSON-serialized into the element's value.

{
  "$type": "Button",
  "label": "Approve",
  "$action": { "type": "approve_order", "orderId": "48213" }
}

becomes a button with action_id: "approve_order" and value: "{\"orderId\":\"48213\"}".

Inbound

A single-line Input outside a Form or Card with asForm, with a non-empty $action.type, enables block_actions on its containing input block and configures on_enter_pressed, so Slack sends its typed text when the user presses Enter. Inputs inside either form remain passive rather than firing their own action. Multiline inputs also remain passive: Slack's dispatch configuration does not expose the browser vocabulary's Ctrl/Cmd+Enter shortcut. A modal's view_submission handler can collect passive input values, including inputs without an actionable type.

Slack posts interactions to your request URL as a block_actions payload. decodeBlockAction takes one entry from its actions array and the payload's state values, then rebuilds the action your tree dispatched. Messages carry these values in payload.state.values, while modals and Home tabs carry them in payload.view.state.values. A control's runtime selection appears under $input when supplied; a button with a JSON-serialized value contributes its payload fields directly. { "$field": name } references in the action payload resolve from named controls in that state:

import { decodeBlockAction } from "@assistant-ui/generative-ui/slack";

const action = decodeBlockAction(payload.actions[0], payload.state?.values ?? payload.view?.state?.values);
// { type: "approve_order", orderId: "48213" }

It returns undefined for anything without a usable action_id, and never throws. type always comes from action_id, so a payload key named type cannot override it, and a $input key smuggled into the serialized payload is always stripped.

What lands in $input depends on the element:

A { "$field": name } reference to a named Checkbox resolves from state values to true when checked or false when unchecked.

For the two halves of a local datetime, $input is the merged YYYY-MM-DDTHH:mm value rather than the individual selection. A { "$field": name } reference uses the same canonical value. Keep the picker's block_id on the action entry passed to the decoder so it can recover the temporal metadata.

Reading a tree back

fromSlackBlocks is the inverse direction, mapping a Block Kit payload into vocabulary nodes and returning { nodes, warnings }. It accepts a bare array or a { blocks } wrapper.

The round trip is faithful on the plain building blocks (text, images, facts, controls, tables, simple cards) and documented-lossy elsewhere: context elements all return as Caption, so the Badge distinction is gone, a CheckboxGroup with a single option returns as a Checkbox, button styles beyond primary and danger are dropped, an alert's title and description come back merged into the description, and card layouts flatten to the fields the card block carries. Card footers are re-derived from button style, with the primary-styled button becoming confirm; when style cannot decide it, position does, and that emits a fallback warning. An input keeps its action_id as $action only when its block sets dispatch_action or the input is multiline, so a passive single-line input, including one from a form, returns without an action and stays passive when converted back.

Native timepicker and datetimepicker elements return as DatePicker nodes with inputType: "time" and inputType: "datetime". A native datetime's initial Unix timestamp becomes a Z value at seconds precision. Reverse conversion reads each control separately, so a local datetime pair returns as separate date and time nodes.

Before interactions work

Converting and posting a tree needs only a bot token with chat:write. Making its buttons do anything additionally needs, on the Slack app side:

• Interactivity enabled with a request URL, under Interactivity & Shortcuts. Slack posts every block_actions payload there.
• An acknowledgement within 3 seconds. Return HTTP 200 first and do the work afterwards; the payload's response_url accepts up to five follow-up posts within 30 minutes if you need to update or replace the message.
• Request signature verification on that endpoint, using your signing secret.

Receiving the webhook, verifying it, and routing the decoded action to your handler stay your application's responsibility. The converter only maps JSON to JSON.

Reference

The generated per-export reference, including every type in the subpath, is at Slack Block Kit. For the Teams equivalent of this page, see Generative UI on Microsoft Teams.