# Documentation Page **Page:** kit/agent/chat-apps/slack [Download Raw Markdown](./kit/agent/chat-apps/slack.md) --- # 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 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](https://api.slack.com/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. ```bash hoody agent bots channels setup get -c $COMPUTER_ID --id chief --kind slack --name "Chief" ``` ```ts 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); ``` ```bash 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](/foundation/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 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. 1. 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**. 2. The agent checks the Bot token ("Checking the token…"). 3. The owner code appears on screen. Go to step 3 below. ```bash 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-1 ``` Pass 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. ```ts 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); ``` ```bash 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": "", "app_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 In Slack, open the app (under **Apps** in the sidebar) and go to its **Messages** tab. Send the owner code as the only text: ```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](/kit/agent/chat-apps/#become-the-owner)). ## 4. Add other people (optional) Anyone you pair can read the Bot's answers in their conversation with it. Pair only people you would let read it. - **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**. ## 5. Use it in a channel (optional) On Slack, a group is a channel. Every member of that channel can read what the Bot answers there. 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 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}/credentials` with `{"token": "…"}`, or `{"token": "…", "app_token": "…"}` to replace both. ## 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`, `@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](/kit/agent/chat-apps/approvals/).