Skip to content

Beta: these docs are still being updated. The next full update is on 18 November at 8 PM UTC. Docs in beta. Full update 18 Nov, 8 PM UTC.

Hoody.com

A Slack app, two tokens, one code. Your Bot then answers you in your workspace.

You need a Slack workspace where you may install apps, and a Bot. The examples use the Bot chief.

The chat app connects to Slack over Socket Mode. Slack never needs to reach your computers: the agent opens the connection.

  1. In the agent’s TUI, start [ + Add chat app ] → Slack and choose ⧉ Copy manifest. The manifest sets up everything below.
  2. Open your Slack apps, choose Create New App → From a manifest, pick your workspace and paste the manifest.
  3. Install the app to your workspace. Copy the Bot User OAuth Token (it starts with xoxb-).
  4. Under Basic Information → App-Level Tokens, create a token with the scope connections:write. Copy it (it starts with xapp-).

Building the app by hand instead? Turn on Socket Mode and Interactivity (the approval buttons need it). Add these bot scopes: chat:write, im:history, im:read, im:write, app_mentions:read, users:read, channels:read, groups:read. Subscribe to the bot events app_mention, message.im, member_joined_channel, channel_left and group_left. Turn on Event Subscriptions. In App Home, turn on the Messages Tab and tick Allow users to send Slash commands and messages from the messages tab: without it, people can see the tab but cannot write to the app.

To let the Bot read messages without a mention, also add channels:history, groups:history and the events message.channels and message.groups. Reinstall the app after changing its scopes. After connecting it, send PATCH /api/v1/agent/bots/{id}/channels/{cid} with {"settings":{"mention_only":false}}. A chat’s own mention_only setting takes precedence. The channel and sender must also be admitted by the access settings.

In the Hub, the same manifest shows as Slack app manifest on the Bot’s Chat apps tab, after Add a chat app, Slack and Next.

Without the TUI or the Hub, get the manifest from the setup answer, field manifest. name sets the app’s name in Slack.

Terminal window
hoody agent bots channels setup get -c $COMPUTER_ID --id chief --kind slack --name "Chief"

If your computer’s proxy permissions protect the agent, add the credential its group requires to the cURL examples on this page; see proxy permissions.

This manifest subscribes to mentions only. To read whole channels, complete both the Slack configuration and the mention_only: false change above.

The agent checks the Bot token with Slack before it saves anything. Of the App-level token it checks only the form: Slack checks that token when the chat app connects (see below). The tokens are never shown again.

  1. In the Hub, open Bots, pick the Bot and open its Chat apps tab. Choose Add a chat app, pick Slack and choose Next.
  2. Copy the Slack app manifest shown there into Slack (step 1). Paste the Bot token (xoxb-…) into Bot token and the App-level token (xapp-…) into App token. A Name in this Hub is optional. Choose Connect.
  3. Under Become its owner, choose Owner code to show the code. Go to step 3 below.

The answer carries the chat app’s id, its current state and, once, the owner code in enrolment.code. The state may initially be connecting; it can show awaiting_owner once connected and until you pair. identity.team names the Slack workspace the app is installed in.

If the tokens are refused, the answer is channel_credentials_invalid with a reason:

reasonWhat to do
unauthorizedA token is wrong or revoked. Copy it again, whole.
mismatched_appThe two tokens come from different Slack apps. Take both from the same app.
missing_scopeThe Bot token (xoxb-) lacks one of the 8 scopes above. Add it, reinstall the app, and copy the new Bot token.
app_unverifiedSlack did not say which app the Bot token belongs to (often users:read is missing). Check the scopes, reinstall, and copy the new Bot token.
unreachableSlack could not be reached. Try again.

Create checks the 8 base scopes only, not channels:history and groups:history. Of the App-level token it checks only that it starts with xapp- and, when the token shows its app, that it is the Bot token’s app. A revoked App-level token, one without connections:write, or Socket Mode turned off shows up at the first connection: the state becomes auth_failed, with reason unauthorized or missing_scope.

In Slack, open the app (under Apps in the sidebar) and go to its Messages tab. Send the owner code as the only text:

7KQ4M9TX

pair 7KQ4M9TX works too. The app answers that you are paired. Now write to it. Your Bot answers in a thread under your message (reply_style: thread).

By default the code works for 15 minutes (pairing_ttl_minutes). If it expired, make a new owner code (see Become the owner).

  • With a code: set dm_policy to pairing, make a pairing code, and give it to the person. They send it to the app in a direct message.
  • By user id: set dm_policy to allowlist or pairing, and add them with their Slack member id (POST …/channels/{cid}/principals). Find it in their profile under ⋮ → Copy member ID.
  • In the Hub: on the Bot’s Chat apps tab, choose Manage on the chat app. Under Settings, set Who can talk in direct messages to People I add or Anyone with an invite code from me, then choose Save settings. Under People, use Add a person with their Slack member ID. To invite someone with a code, first save Anyone with an invite code from me, then open People and use Invite someone and Create invite code.
  1. Invite the app to the channel (/invite @YourApp).
  2. A paired person with the control right sends !bind in the channel, mentioning the app.
  3. Approve the channel using Approve on the card sent to the owner’s direct message, in the TUI’s Chat apps screen, in the Hub (open the Bot’s Chat apps tab, choose Manage on the chat app, open Chats, choose Approve, then Approve group), or with PATCH /api/v1/agent/bots/{id}/channels/{cid}/chats/{chat} and {"state":"approved","acknowledge_group_readers":true}. {chat} is the chat’s id (chat_…) from the chat app’s chats list. Approval confirms that everyone in the channel can read the Bot’s answers.

Replace a token when it leaks or was reset. The new Bot token must belong to the same Slack bot: a token of another bot is refused (channel_identity_changed) and nothing changes. The new Bot token is checked with Slack before it is stored. A new App-level token is checked like on create: Slack checks it when the chat app connects again.

Leave the App-level token out to keep the stored one and replace only the Bot token. Give one to replace it too.

A running chat app restarts with the new tokens at once (the API answers "applied": "restart"). When it is not running (turned off, paused or not started yet), or the restart fails, the new tokens are stored and used at its next start ("applied": "next_start"); the chat app’s state says why it is not running.

  • Terminal app: Replace keys in the chat app’s details.
  • Hub: on the Bot’s Chat apps tab, choose Manage on the chat app, open Setup, and choose Replace… under Bot token. Enter the replacement tokens, then choose Replace the token. If authentication has failed, enter the tokens directly in the open Replace the token step.
  • API: PUT …/channels/{cid}/credentials with {"token": "…"}, or {"token": "…", "app_token": "…"} to replace both.
  • By default, commands use ! (command_prefix): !status, !stop, !bind, !unbind, !help. The app registers no Slack slash commands.
  • One answer part holds at most 3900 UTF-16 code units, including formatting markup (part_chars); some characters count as two units. A longer answer is sent in up to 8 parts by default (max_parts, 1 to 20).
  • @channel, @here and @everyone in an answer are sent as plain text. They never notify anyone.
  • By default, the chat app opens at most 30 Slack connections per hour (connection_opens_per_hour), failed ones included.

Next: decide approvals from Slack.