Communication

Slack

Send and receive messages via Socket Mode, react, read threads

Slack Setup Guide

Enables your agent to send and receive messages, react to messages, read threads, and manage channels in your Slack workspace.

Prerequisites

A Slack workspace where you have permission to install apps
Admin approval may be required depending on workspace settings

Step 1: Create a Slack App

Go to api.slack.com/apps
Click Create New App > From scratch
Enter an app name (e.g., "Carapace Agent") and select your workspace
Click Create App

Step 2: Enable Socket Mode

Socket Mode lets your agent receive messages in real time without exposing a public URL.

In the left sidebar, go to Socket Mode
Toggle Enable Socket Mode on
You'll be prompted to create an App-Level Token — name it something like "carapace-socket" and add the connections:write scope
Copy the token (starts with xapp-) — you'll need this later

Step 3: Configure Event Subscriptions

In the left sidebar, go to Event Subscriptions
Toggle Enable Events on
Under Subscribe to bot events, add:

Required events:

Event	Description
`message.channels`	Messages in public channels
`message.groups`	Messages in private channels
`message.im`	Direct messages to your bot
`app_mention`	When someone @mentions your bot

Optional events (for triage/approval workflows):

Event	Description
`reaction_added`	When someone adds an emoji reaction

Click Save Changes

Step 4: Configure Bot Token Scopes

In the left sidebar, go to OAuth & Permissions
Scroll to Scopes > Bot Token Scopes
Add the following scopes:

Required scopes:

Scope	Description
`chat:write`	Send messages
`channels:read`	List public channels
`channels:history`	Read messages in public channels
`groups:history`	Read messages in private channels
`im:history`	Read direct messages
`users:read`	Look up user info

Recommended scopes:

Scope	Description
`reactions:read`	Read emoji reactions (for approval workflows)
`reactions:write`	Add emoji reactions
`app_mentions:read`	Read @mentions of the bot
`im:read`	View DM metadata
`im:write`	Open DM conversations
`files:write`	Upload files

Step 5: Install the App

In the left sidebar, go to Install App
Click Install to Workspace
Review the permissions and click Allow
Copy the Bot User OAuth Token (starts with xoxb-)

Step 6: Invite the Bot to Channels

The bot can only see and post in channels it has been explicitly invited to.

/invite @YourBotName

Or right-click the channel > View channel details > Integrations > Add apps.

Step 7: Connect in Carapace

Go to Dashboard > Connections
Find Slack and click Connect
Paste the Bot Token (xoxb-...)
Paste the App Token (xapp-...) — this enables real-time message receiving via Socket Mode
Click Save Credentials

Credential Fields Reference

Field	Required	Format	Description
`bot_token`	Yes	Starts with `xoxb-`	Bot User OAuth Token — used for API calls
`app_token`	No	Starts with `xapp-`	App-Level Token — enables Socket Mode for real-time events

Without the app token, the agent can send messages but cannot receive them in real time.

Private Channels

Private channels require different scopes than public channels:

Public channels	Private channels
`channels:history`	`groups:history`
`channels:read`	`groups:read`
`message.channels` event	`message.groups` event

Make sure you add both sets of scopes and events if your agent needs to work in private channels. The bot must still be explicitly invited to each private channel.

Triage Agent Setup

Carapace includes a triage agent template that monitors Slack channels for bug reports and feature requests, gathers structured information, consults your dev team, and creates ClickUp tasks.

To set up a triage agent:

Complete the Slack setup above (including Socket Mode and reaction events)
Connect a ClickUp integration with a personal API token
Download the triage agent prompt template and paste it into your agent's system prompt
Fill in the configurable sections: monitored channels, dev notification target, and ClickUp list ID

The triage flow:

Someone posts a bug report or feature request in a monitored channel
The agent reacts with a magnifying glass and starts gathering info in a thread
Once info is complete, the agent posts a summary to the dev channel
A dev approves (checkmark reaction or "lgtm" reply)
The agent creates a structured ClickUp task and closes the loop

Gotchas

Bot must be invited to channels: The bot cannot see or post to any channel until explicitly invited. This is the most common reason the agent "can't find" a channel.

Scopes require reinstall: If you add scopes after installation, you must reinstall the app to your workspace. Go to Install App and click Reinstall to Workspace.

Event subscriptions require reinstall: Same as scopes — after changing event subscriptions, reinstall the app.

xoxb- vs xoxp- vs xapp- tokens:

xoxb- — Bot tokens (used for API calls)
xapp- — App-level tokens (used for Socket Mode)
xoxp- — User tokens (not supported by Carapace)

Agent must be restarted after token changes: If you update your Slack credentials in the dashboard, stop and start the agent to pick up the new tokens.

Troubleshooting

Bot doesn't respond to messages

Verify Socket Mode is enabled in your Slack app settings
Verify the app token (xapp-...) is saved in Carapace alongside the bot token
Verify Event Subscriptions are enabled with the correct bot events
Verify the bot is invited to the channel (/invite @BotName)
Check that private channels have groups:history scope and message.groups event

Bot can't send messages

The bot hasn't been invited to the target channel. Use /invite @BotName.

"missing_scope" error

Add the missing scope in OAuth & Permissions > Bot Token Scopes, then reinstall the app and update the token in Carapace.

"not_in_channel" error

The bot hasn't been added to the channel. Invite it first.

Bot connects but receives no events

This usually means event subscriptions are not configured or the app wasn't reinstalled after changing them. Check Event Subscriptions in your Slack app settings and reinstall.