Generative UI on Slack

The $type tree your assistant renders in the browser is plain JSON, so it does not have to stay in the browser. @assistant-ui/react-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/react-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 });

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.

Warnings

Conversion is total. Every downgrade is reported rather than thrown, so one unsupported node never costs you 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. Logging them in development is the fastest way to see why a composition looks different on Slack than in the browser.

Component mapping

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; and Button's block. Card's asForm and Button's submit are dropped for a different reason: Slack has no client-side form model to submit into, so a submit button and a click button both convert to the same button element carrying the node's $action, and a card marked asForm converts exactly like one that is not.

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.

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, DatePicker, Checkbox, RadioGroup, Input, or Form, plus a ListViewItem or a nested Card footer that carries an 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. The ones 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

Slack posts interactions to your request URL as a block_actions payload. decodeBlockAction takes one entry from its actions array and rebuilds the action your tree dispatched, with the user's runtime selection under $input:

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

const action = decodeBlockAction(payload.actions[0]);
// { type: "approve_order", orderId: "48213", $input: "…" }

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:

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, 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.

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 speaks JSON in and JSON out.

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.