Connect your Bot to Slack
Section titled “Connect your Bot to Slack”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. Create the Slack app
Section titled “1. Create the Slack app”- In the agent’s TUI, start [ + Add chat app ] → Slack and choose ⧉ Copy manifest. The manifest sets up everything below.
- Open your Slack apps, choose Create New App → From a manifest, pick your workspace and paste the manifest.
- Install the app to your workspace. Copy the Bot User OAuth Token (it starts with
xoxb-). - Under Basic Information → App-Level Tokens, create a token with the scope
connections:write. Copy it (it starts withxapp-).
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.
hoody agent bots channels setup get -c $COMPUTER_ID --id chief --kind slack --name "Chief"import { HoodyClient } from 'hoody-sdk';
const hoody = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });const box = await hoody.withComputer(process.env.COMPUTER_ID!);
const { data } = await box.agent.bots.channels.getSetup('chief', { kind: 'slack', name: 'Chief' });console.log(data.manifest);curl "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/chief/channels/setup?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.
2. Connect it
Section titled “2. Connect it”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.
- In the Hub, open Bots, pick the Bot and open its Chat apps tab. Choose Add a chat app, pick Slack and choose Next.
- 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. - Under Become its owner, choose Owner code to show the code. Go to step 3 below.
- On the same screen (+ Add Slack), paste the Bot token (
xoxb-…) into Bot token and the App-level token (xapp-…) into App token. A Name is optional. Choose ✓ Add. - The agent checks the Bot token (“Checking the token…”).
- The owner code appears on screen. Go to step 3 below.
hoody agent bots channels create -c $COMPUTER_ID --id chief --kind slack --label "Team Slack" --bot-token "$SLACK_BOT_TOKEN" --app-token "$SLACK_APP_TOKEN" --idempotency-key slack-chief-1Pass the Bot token with --bot-token and the App-level token with --app-token. The credentials set command requires --bot-token; leave out --app-token to keep the stored App-level token.
import { HoodyClient } from 'hoody-sdk';
const hoody = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });const box = await hoody.withComputer(process.env.COMPUTER_ID!);
const { data } = await box.agent.bots.channels.create('chief', { kind: 'slack', label: 'Team Slack', token: process.env.SLACK_BOT_TOKEN!, app_token: process.env.SLACK_APP_TOKEN!,}, { idempotencyKey: 'slack-chief-1' });console.log(data.id, data.enrolment?.code);curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/chief/channels" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: slack-chief-1" \ -d '{ "kind": "slack", "label": "Team Slack", "token": "<xoxb- bot token>", "app_token": "<xapp- app-level token>" }'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:
reason | What to do |
|---|---|
unauthorized | A token is wrong or revoked. Copy it again, whole. |
mismatched_app | The two tokens come from different Slack apps. Take both from the same app. |
missing_scope | The Bot token (xoxb-) lacks one of the 8 scopes above. Add it, reinstall the app, and copy the new Bot token. |
app_unverified | Slack 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. |
unreachable | Slack 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.
3. Become the owner
Section titled “3. Become the owner”In Slack, open the app (under Apps in the sidebar) and go to its Messages tab. Send the owner code as the only text:
7KQ4M9TXpair 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).
4. Add other people (optional)
Section titled “4. Add other people (optional)”- With a code: set
dm_policytopairing, 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_policytoallowlistorpairing, 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.
5. Use it in a channel (optional)
Section titled “5. Use it in a channel (optional)”- Invite the app to the channel (
/invite @YourApp). - A paired person with the
controlright sends!bindin the channel, mentioning the app. - 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’sid(chat_…) from the chat app’schatslist. Approval confirms that everyone in the channel can read the Bot’s answers.
Replace the tokens
Section titled “Replace the tokens”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}/credentialswith{"token": "…"}, or{"token": "…", "app_token": "…"}to replace both.
Slack details
Section titled “Slack details”- 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,@hereand@everyonein 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.