Flocks Docs

English

Simplified Chinese

English

Simplified Chinese

Appearance

Slack Integration

This document explains how to create an app in Slack, then connect, control permissions for, and verify the Slack integration in Flocks.

Use Cases

  • Trigger Rex or a specified Agent through Slack direct messages.
  • Receive questions in Slack channels and reply with analysis results in the original thread or channel.
  • Push Task Center, Workflow, or conversation results to a specified Slack channel or user.
  • Use Slack Socket Mode to establish outbound connections to Slack when the deployment environment cannot expose a public Webhook.

Prerequisites

  • You have permission to create and install apps in the target Slack Workspace.
  • The server running Flocks can access the Slack API and Socket Mode WebSocket service.
  • Set up a dedicated Slack App for Flocks. Avoid reusing existing bots.
  • For production environments, prepare the Slack user IDs and channel IDs allowed to access Flocks in advance.

We recommend using Socket Mode for Slack integrations. With Socket Mode, Flocks establishes an outbound connection to Slack, so Flocks does not need to be exposed to the public internet and no public callback URL is required.

Procedure

1. Create a Slack App

  1. Open Slack API Apps.
  2. Click Create New App.
  3. Select From scratch.
  4. Enter an App Name, for example Flocks Assistant.
  5. Select the Slack Workspace to connect.
  6. Click Create App.

2. Enable Socket Mode

  1. In the Slack App console, go to Settings -> Socket Mode.
  2. Enable Enable Socket Mode.
  3. Follow the prompts to create an App-Level Token.
  4. Add the connections:write scope to the App-Level Token.
  5. Save the returned App-Level Token. The format is usually similar to:
xapp-...

This Token is used by Flocks to establish the Socket Mode WebSocket connection. Store it as a sensitive credential. Do not commit it to Git or share it in group chats.

3. Configure Bot Token Scopes

Go to Features -> OAuth & Permissions and add the permissions required by Flocks under Bot Token Scopes.

Common permissions:

ScopePurpose
app_mentions:readReceive messages that @ the bot in channels
channels:historyRead public channel message events
channels:readRead basic public channel information
chat:writeSend messages
groups:historyRead private channel message events
groups:readRead basic private channel information
im:historyReceive direct messages
im:readRead basic direct-message information
im:writeOpen or write direct messages
mpim:historyReceive multi-person direct-message events
mpim:readRead basic multi-person direct-message information
users:readRead basic user information for display and allowlist troubleshooting

If you only plan to use the bot in public channels through @ mentions, you can start with a smaller scope set: app_mentions:read, channels:history, channels:read, chat:write, and users:read. If you need direct messages, private channels, or multi-person direct messages, add the corresponding im:*, groups:*, and mpim:* permissions.

4. Install the App and Obtain the Bot Token

  1. On the OAuth & Permissions page, click Install to Workspace.
  2. Follow Slack's prompts to authorize the installation.
  3. After installation, copy the Bot User OAuth Token. The format is usually similar to:
xoxb-...

If Bot Token Scopes are added or removed later, click Reinstall to Workspace again so the permission changes take effect.

5. Configure Event Subscriptions

Go to Features -> Event Subscriptions:

  1. Enable Enable Events.
  2. Under Subscribe to bot events, add the events you need to receive.

Common events:

EventPurpose
app_mentionTriggered when the bot is @ mentioned in a channel
message.imDirect messages
message.channelsRegular messages in public channels
message.groupsRegular messages in private channels
message.mpimMulti-person direct messages

For production environments, use app_mention and message.im first. If you enable message.channels or message.groups, also configure channel allowlists and trigger policies in Flocks to avoid having every normal channel message trigger an Agent.

6. Enable the Messages Tab

If you want users to send direct messages to the bot, go to Features -> App Home:

  1. Under Show Tabs, enable Messages Tab.
  2. Enable Allow users to send Slash commands and messages from the messages tab as needed.

After this is enabled, users can open the App direct-message window in Slack and send messages to Flocks.

7. Configure the Slack Integration in Flocks

Go to "Messaging Integrations -> Slack" in the Flocks WebUI and enter the basic configuration.

Configuration ItemDescription
Bot TokenSlack xoxb-... Bot User OAuth Token.
App TokenSlack xapp-... App-Level Token. It must include connections:write.
Default AgentWhich Agent handles Slack messages by default.
Direct message policyControls whether Slack direct messages are open, restricted to allowlisted users, or disabled.
Allowed usersOnly specified Slack User IDs can trigger Flocks. Recommended for production.
Channel policyControls whether channel messages are open, restricted to allowlisted channels, or disabled.
Allowed ChannelsOnly specified Slack Channel IDs can trigger Flocks.
Channel trigger modeRecommended to trigger only when the bot is @ mentioned or replied to.
Streaming outputControls whether Slack replies are sent progressively in streaming mode.

After filling in the fields, click Enable, then click Save. Wait until the integration status changes to running.

8. Invite the Bot to Channels

After the Slack App is installed to the Workspace, it does not automatically join every channel. Invite the bot in the target channel:

/invite @Flocks Assistant

Or add the bot to the channel through channel member management.

For private channels, the bot must be invited to the channel before Flocks can receive events and send replies.

Get Slack User IDs and Channel IDs

For production environments, use Slack IDs for allowlists instead of relying only on display names. Display names can be duplicated and may be changed by users.

Get a user ID:

  1. Open the target user's profile in Slack.
  2. Click more actions.
  3. Select Copy member ID.
  4. The user ID usually looks like:
U012ABCDEF

Get a channel ID:

  1. Open the target channel.
  2. Click the channel name to open channel details.
  3. In more actions, select Copy channel ID, or identify the ID from the channel link.
  4. Channel IDs usually look like:
C012ABCDEF
G012ABCDEF

An ID starting with C is usually a public channel. An ID starting with G is usually a private channel or multi-person direct message.

Channel and Thread Configuration Notes

Slack channels usually have high message volume. In production, Flocks should not process every normal message in a channel unless that channel is dedicated to bot interaction.

Recommended configuration:

  • Respond to channel messages only when the bot is @ mentioned, when a bot message is replied to, or when a command triggers the bot.
  • Allow only specified channels to trigger Flocks.
  • Allow only specified users or on-call group members to trigger high-privilege Agents.
  • For long reports, generate downloadable files or docs, and post only summaries and key conclusions to Slack.

Slack threads affect context binding. When a user continues asking questions in the same thread, Flocks usually reuses the same external conversation. If the user starts a new message in the channel, a new conversation binding may be created.

Result Delivery and Session ID

To proactively send results to Slack from a Flocks page, Task Center, or Workflow, first establish a conversation binding and obtain the target Session ID.

To obtain the Session ID:

  1. Send What is your session_id? in the Slack channel or direct message thread.
  2. Or send /status to view the currently bound Session, Agent, model, and Slack conversation information.
  3. Use this Session ID in the WebUI, another conversation, Task Center, or Workflow:
Send to session_id: <session_id>: Today's inspection is complete. Two high-risk alerts were found.

Flocks automatically finds the bound Slack conversation based on the Session ID and sends the message. If /new has been executed in the target Slack conversation, a new Session is rebound, and subsequent pushes should use the new Session ID.

Security Recommendations

  • Use a dedicated Slack App and dedicated bot identity. Avoid sharing Tokens with other automation systems.
  • In production, always configure a user allowlist, a channel allowlist, or both.
  • If a Bot Token or App Token leaks, regenerate or revoke it immediately in the Slack App console.
  • Do not grant OAuth scopes that are not currently needed. Add permissions only when adding new features, then reinstall the app.
  • For Agents that can operate devices, change tickets, or execute commands, use them together with Flocks tool permissions, approvals, and audit logging.
  • When an employee leaves, a project ends, or Workspace permissions change, promptly clean up Slack App installations, channel invitations, and Flocks allowlists.

FAQ

The Channel Cannot Connect to Slack

Verify the following:

  • Whether Bot Token starts with xoxb- and App Token starts with xapp-.
  • Whether the App-Level Token includes connections:write.
  • Whether Socket Mode is enabled for the Slack App.
  • Whether the Flocks server can access slack.com, api.slack.com, and the Slack Socket Mode WebSocket service.
  • Whether an enterprise proxy, firewall, or TLS inspection is blocking WebSocket.

Direct Messages Do Not Respond

Verify the following:

  • Whether Messages Tab is enabled in App Home.
  • Whether the message.im event is subscribed.
  • Whether the Bot Token includes im:history, im:read, im:write, and chat:write.
  • Whether the current user is in the Flocks allowed user list.
  • Whether the Slack App was reinstalled to the Workspace after permission changes.

The Bot Does Not Respond When @ Mentioned in a Channel

Verify the following:

  • Whether the bot has been invited to the target channel.
  • Whether the app_mention event is subscribed.
  • Whether the Bot Token includes app_mentions:read, channels:history, channels:read, and chat:write.
  • Whether private channels also include groups:history and groups:read.
  • Whether the current channel is in the Flocks allowed channel list.

Regular Channel Messages Are Configured but No Events Are Received

Verify the following:

  • Whether message.channels or message.groups is subscribed.
  • Whether channels:history is configured for public channels and groups:history is configured for private channels.
  • Whether the Slack App was reinstalled so the new events and permissions take effect.
  • Whether Flocks channel trigger mode is restricted to only @ mentions or bot replies.

How to Distinguish Multiple Workspaces or Slack Apps

Each Slack Workspace should use a separate Slack App, and Flocks should use the corresponding Bot Token and App Token. When you need stable delivery to a specific Slack direct message, channel, or thread, use the Session ID returned by Flocks instead of only writing "send to Slack" in the task description.

References

Related Resources: Messaging and alerting integrations overview | DingTalk integration | Feishu integration | WeCom integration | Telegram integration | WeChat integration | WhatsApp integration | Email integration

Built with VitePress

Copyright © Flocks