Slack Integration

TeamDay works inside Slack in two complementary ways — and you can turn on either, both, or neither per Space.

Mode	What it does	When to use
Mention bot (inbound)	`@TeamDay` in any channel, or DM the bot — your agent replies in-thread	You want a hands-free way to talk to your agent without leaving Slack
Slack MCP (outbound)	Agents can read channels, post messages, and search history as a tool	Your agents need to act on Slack content — summarise threads, post updates, pull context

Each Space has its own Slack connection. Different Spaces in the same organisation can link to different workspaces or the same workspace with different bots.

Part 1 — Mention Bot Setup

This gives you the @TeamDay experience: mention the bot in a channel and your agent picks up the message, runs its system prompt and tools, and replies in a thread.

1. Create a Slack App

Go to api.slack.com/apps → Create New App → From scratch. Pick the workspace you want to connect.

2. Enable Socket Mode

In the sidebar: Socket Mode → toggle Enable Socket Mode on. Slack will prompt you to create an App-Level Token with the connections:write scope. Give it a name (e.g. teamday-socket) and copy the xapp-... token — you’ll paste it in step 6.

Socket Mode means Slack connects outbound to your App; you don’t need a public URL, webhook forwarding, or HMAC verification.

3. Add Bot Scopes

In OAuth & Permissions → Scopes → Bot Token Scopes, add:

Scope	Why
`app_mentions:read`	Receive `@TeamDay` mentions in channels
`chat:write`	Post replies in threads
`reactions:write`	Add the 👀 acknowledgement emoji
`im:history`	Read direct messages to the bot
`im:read`	List DM channels
`im:write`	Open DMs when needed
`channels:history`	Optional — read context before replying
`groups:history`	Optional — same for private channels

Event Subscriptions → toggle on. Under Subscribe to bot events, add:

app_mention
message.im

Save. No Request URL is needed (Socket Mode delivers events over WebSocket).

5. Install to Workspace

Install App → Install to Workspace → approve. Copy the Bot User OAuth Token (xoxb-...). Also copy the Signing Secret from Basic Information → App Credentials.

You now have three secrets:

Bot token (xoxb-...)
App token (xapp-...)
Signing secret

6. Link the Space

curl -X POST https://cc.teamday.ai/api/messaging/slack/{spaceId}/link \
  -H "Authorization: Bearer $TEAMDAY_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "botToken": "xoxb-...",
    "appToken": "xapp-...",
    "signingSecret": "...",
    "agentId": "agent-xyz"
  }'

TeamDay validates the tokens against Slack’s auth.test API before storing them, so an invalid paste fails fast.

On success the response includes teamName, teamId, botUserId, and a status.status of connected. The bot is live.

7. Say Hi

Invite the bot to a channel (/invite @TeamDay), then mention it:

@TeamDay summarise what's pending from our last standup

The bot adds a 👀 reaction while working, replies in-thread, and removes the reaction when done. Follow-up messages in the same thread resume the same agent session — the agent remembers the earlier turn.

Optional: Allowlists

Restrict which channels or users the bot responds to:

{
  "botToken": "xoxb-...",
  "appToken": "xapp-...",
  "signingSecret": "...",
  "allowChannels": ["C01234ABCDE", "C56789FGHIJ"],
  "allowUsers": ["U01234XYZAB"]
}

Empty arrays (the default) mean “respond anywhere the bot is invited to.”

Unlinking

curl -X POST https://cc.teamday.ai/api/messaging/slack/{spaceId}/unlink \
  -H "Authorization: Bearer $TEAMDAY_PAT"

The Bolt session stops immediately; tokens stay in Firestore (disabled) so you can re-enable without re-linking.

Part 2 — Slack MCP Setup (Outbound)

The MCP lets an agent use Slack as a tool inside a conversation: read a channel, post a message, search history. This is independent from the mention bot — you can have both, or just one.

1. Create a Bot Token

Same Slack App as above works. Add these additional scopes if you haven’t already:

channels:read, channels:history
groups:read, groups:history (private channels)
users:read
search:read (workspace search)

Reinstall the app to pick up new scopes.

2. Find your Team ID

curl -X POST https://slack.com/api/auth.test \
  -H "Authorization: Bearer xoxb-..."

Copy team_id (starts with T).

3. Add the MCP in TeamDay

Open your Space → MCPs tab → Add MCP → select Slack (under Communication). Paste:

Slack Bot Token — xoxb-...
Slack Team ID — T01234ABCDE
Channel IDs (optional) — comma-separated list to sandbox which channels the agent can access

Save. The MCP is now available to every agent in the Space.

Ask your agent something like:

“Check #incidents for any unresolved threads from the last 24 hours and post a summary to #exec.”

How it Works

Per-Space Isolation

Each Space stores its own tokens at spaces/{spaceId}/integrations/slack. Organisation membership is checked on every API call, so one org can never see, use, or override another org’s Slack connection.

Thread-Scoped Memory

Each Slack thread maps to one agent session. First mention in a thread = fresh context. Every reply in that thread = resume the same Claude SDK session. Two parallel threads in the same channel have independent memory — mirroring how a human experiences a Slack thread.

Restart Resilience

If the app or messaging service restarts, TeamDay walks integrations/slack for enabled: true docs and rehydrates every Bolt session automatically. Your bot reconnects without anyone having to re-link.

Error Handling

If your agent fails mid-reply, the bot posts ⚠️ <error message> in-thread instead of going silent. The 👀 reaction is always cleaned up so you never see a stuck “thinking” indicator.

Troubleshooting

Bot doesn’t respond to mentions. Check that:

The bot is actually invited to the channel (/invite @TeamDay)
app_mention is in your Event Subscriptions
GET /api/messaging/slack/{spaceId}/status returns session.status: "connected"

Slack bot token invalid on link. The bot token must start with xoxb- (bot token, not user token). Check OAuth & Permissions → Bot User OAuth Token.

appToken must start with xapp-. The App-Level Token from Basic Information → App-Level Tokens, not the Bot token. Make sure you created one with the connections:write scope.

Session shows connected but mentions don’t arrive. Most common cause: you forgot to subscribe to app_mention in Event Subscriptions. Slack won’t send events for unsubscribed types even if the bot is online.

Duplicate replies. Running both local dev and production against the same Slack App will cause events to fan out to both. Either use separate Slack Apps per environment, or set enabled: false on the Space you’re not actively using.