Payloads
Build the interaction payloads Slack sends to your app's request URL.
The provider builds Slack’s interaction payloads for you and passes them to onPayload, onSubmit, onClose and onOptions. The same builders are exported, for tests or for payloads you send yourself.
Each builder returns the JSON Slack would send, with the placeholder identity (T00000000, U00000000, A00000000) unless you pass identity. identity takes camelCase keys (apiAppId, triggerId, responseUrl); the payload has Slack’s snake_case ones (api_app_id, trigger_id, response_url).
The payloads changed in 0.5: an overflow action no longer sends the option’s URL, state.values lists every input, and on_character_entered sends one action once typing pauses. Upgrading says what to change.
buildBlockActionsPayload
A block_actions payload: a user clicked a button, picked an option, or changed an input that dispatches actions.
import { buildBlockActionsPayload } from "@nkootstra/block-kit";
const payload = buildBlockActionsPayload({
action: {
type: "button",
action_id: "approve",
block_id: "deploy",
value: "api@4.2.0",
action_ts: "1700000000.000200",
},
state: {},
container: { type: "message", messageTs: "1700000000.000100", channelId: "C0RELEASES" },
identity: { user: { id: "U0ADA", username: "ada", name: "ada", team_id: "T0ACME" } },
});
A message container gives a payload with channel, message and state; a view container gives one with view, whose state holds the values. The return type narrows to match.
Text objects come back the way Slack echoes them: every plain_text object in the action and in state (the button text, a placeholder, the confirm dialog, an option’s text and description) gets emoji: true, and every mrkdwn one gets verbatim: false, unless you set them. onAction receives the same normalized action as the payload’s actions[0].
Like Slack’s, the payload carries enterprise and is_enterprise_install, and so do view_submission, view_closed and block_suggestion payloads. enterprise is null unless the identity’s team has an enterprise_id, which makes it { id, name } (from enterprise_id and enterprise_name). is_enterprise_install is false unless the identity sets isEnterpriseInstall.
buildViewSubmissionPayload
A view_submission payload: the modal’s submit button was pressed.
import { buildViewSubmissionPayload } from "@nkootstra/block-kit";
// `blocks` is the modal's blocks array, the same one you pass to <Modal>.
const payload = buildViewSubmissionPayload({
view: { id: "V0DEPLOY", type: "modal", callback_id: "deploy", blocks },
state: { version: { value: { type: "plain_text_input", value: "api@4.2.0" } } },
});
view.state.values in the payload is the state you pass, with its text objects normalized like the action’s. The view itself comes back the way Slack echoes a stored view: title, submit, close and every text object in blocks get emoji: true or verbatim: false, and each input block gets optional: false and dispatch_action: false unless set. The same applies to the view in view_closed, block_suggestion and a view’s block_actions. Add responseUrls for modals with a response_url_enabled conversation select: an array of { block_id, action_id, channel_id, response_url }, which becomes the payload’s response_urls ([] without it).
buildViewClosedPayload
A view_closed payload: the modal was closed, for views with notify_on_close. Set isCleared when the whole stack closed.
buildBlockSuggestionPayload
A block_suggestion payload: the user typed into an external_select. Pass actionId, blockId, the typed value, the container and state:
import { buildBlockSuggestionPayload } from "@nkootstra/block-kit";
const payload = buildBlockSuggestionPayload({
actionId: "assignee",
blockId: "owner",
value: "ad",
container: { type: "message", messageTs: "1700000000.000100", channelId: "C0RELEASES" },
state: {},
});
Your options load URL answers it with an OptionsResponse, built from SuggestionOption objects (text, value, and an optional description or url):
type OptionsResponse =
| { options: SuggestionOption[] }
| { option_groups: { label: PlainTextElement; options: SuggestionOption[] }[] };
Types
| Type | Describes |
|---|---|
BlockAction |
One entry of actions: type, action_id, block_id, action_ts, plus the element’s value fields |
BlockActionsPayload |
MessageBlockActionsPayload | ViewBlockActionsPayload |
BlockSuggestionPayload |
The block_suggestion payload |
Container |
MessageContainer | ViewContainer |
ViewLike |
The view fields the builders read and echo back |
ViewResponseAction |
What onSubmit may return: errors, update, push or clear |
PayloadIdentity |
team, user, apiAppId, token, triggerId, responseUrl, isEnterpriseInstall, teamName |