Skip to content
Instant

Developers

Messages, buttons and commands

Everything a bot says lands as a real message, under its name and face. Add buttons and menus, answer slash commands, and talk to one person at a time.

Post a Message

await app.client.chat.postMessage({
  channel: 'ch_…',            // or a person's usr_ id, to DM them (needs im:write)
  text: 'Deploy *finished* in 2m 14s. <https://ci.example.com/9|See the run>',
  thread_ts: 'msg_…',         // optional: reply in a thread
});
  • Formatting is Slack’s mrkdwn: *bold*, _italic_, ~strike~, `code`, > quotes, code blocks, <@usr_…> mentions, <!here> and :emoji: names. A <url|label> link shows as “label (url)”.
  • Blocks are read for their words: header, section (text and fields) and context become the message’s text, and buttons and menus become real controls (below). Other blocks are skipped, so send text too, as Slack asks.
  • Name and face are always the bot’s own; username and icon_url are ignored.
  • chat.update and chat.delete change the bot’s own messages; chat.scheduleMessage posts up to 120 days ahead; chat.getPermalink gives a link anyone in the channel can open.

Only for One Person

chat.postEphemeral with channel and user shows a message only to that person, marked “Only visible to you” with a Dismiss button. It’s never stored, so it’s gone after a reload, as on Slack.

Buttons

Put button elements in an actions block, or one as a section’s accessory. They show under the bot’s message for everyone.

await app.client.chat.postMessage({
  channel: 'ch_…',
  text: 'Deploy web to production?',
  blocks: [
    { type: 'section', text: { type: 'mrkdwn', text: '*Deploy web to production?* 14 commits since Tuesday.' } },
    { type: 'actions', block_id: 'deploy', elements: [
      { type: 'button', action_id: 'ship', text: { type: 'plain_text', text: 'Deploy' }, style: 'primary', value: 'web@4f2c' },
      { type: 'button', action_id: 'cancel', text: { type: 'plain_text', text: 'Cancel' }, style: 'danger' },
      { type: 'button', action_id: 'logs', text: { type: 'plain_text', text: 'Logs' }, url: 'https://ci.example.com/9' },
    ] },
  ],
});

Up to 25 a message, with style primary or danger, a value, and an optional url that opens as well. Only bots can add them.

When Someone Clicks

Set the Interactivity URL on the bot’s page (with Bolt, the same /slack/events address), or use Socket Mode. A click sends Slack’s block_actions payload, signed, as payload=<json>, with user, channel, the message, actions[0], a trigger_id and a response_url. The button shows a spinner until the bot answers.

app.action('ship', async ({ ack, body, action, respond }) => {
  await ack();
  await respond({ replace_original: true, text: `Deploying ${action.value} for <@${body.user.id}>…` });
});

Through the response_url, for 30 minutes: replace_original: true replaces the message for everyone (send new blocks for new buttons, or none), delete_original: true deletes it, and anything else is a reply, only to the clicker unless response_type is in_channel. Or call chat.update yourself.

Menus

A static_select (with options or option_groups, and initial_option), users_select or conversations_select in an actions block or as an accessory shows as a menu under the message. Instant checks the pick is one you offered, a person in the workspace or a channel the picker can see, then sends block_actions with selected_option, selected_user or selected_conversation.

{ type: 'actions', block_id: 'triage', elements: [
  { type: 'static_select', action_id: 'priority', placeholder: { type: 'plain_text', text: 'Priority' },
    options: ['P1', 'P2', 'P3'].map((p) => ({ text: { type: 'plain_text', text: p }, value: p.toLowerCase() })) },
  { type: 'users_select', action_id: 'owner', placeholder: { type: 'plain_text', text: 'Assign' } },
] }

Slash Commands

Turn on commands and choose Add Command on the bot’s page: a name, a short description, a usage hint like [city] and the URL to call. It shows in everyone’s / menu with the bot’s face. Names are unique in a workspace and can’t take a built-in one (/remind, /status, /poll and the like).

Running it sends Slack’s form payload: command, text, user_id, user_name, channel_id, channel_name, team_id, response_url, trigger_id, and thread_ts when run in a thread.

app.command('/weather', async ({ command, ack, respond }) => {
  await ack();                                   // within 3 seconds
  const forecast = await lookUp(command.text || 'Oslo');
  await respond({ response_type: 'in_channel', text: forecast });
});

Answer within 3 seconds with {"text": "…"} (only the person sees it) or add "response_type": "in_channel" to post as the bot. An empty 200 just acknowledges. The response_url takes more answers, in the same shape, for 30 minutes.

Files

With files:write, Bolt’s client.files.uploadV2 works unchanged, and so does the older files.upload. Files are up to 25 MB for images, 90 MB for video and 50 MB for anything else.

await app.client.files.uploadV2({ channel_id: 'ch_…', file: './report.pdf', filename: 'report.pdf', initial_comment: 'Weekly report' });

Build Your First Bot

Make a bot in Settings › Bots & Apps and post your first message in a minute.

Join NowSee Pricing