Skip to main content

Slack

Last updated 10/07/2026

1. Configure the Slack App​

  1. Go to Slack API

  2. Create a new app (or use an existing one)

    • Choose to start from a blank app ("Blank app")
    • Enter the App Name and select a Workspace

  3. Get the app credentials:

    • Client ID (in Basic Information → App Credentials)
    • Client Secret (in Basic Information → App Credentials)

2. Configure App-Level Tokens​

  1. In Basic Information → App-Level Tokens, click Generate Token and Scopes
  2. Enter a Token name (such as connection_token)
  3. Add the connections:write, authorizations:read, and app_configurations:write scopes
  4. Click Generate
  5. Copy the generated Token in the xapp-... format

3. Configure OAuth & Permissions​

Slack requires HTTPS. If you don't have HTTPS, you can skip this configuration and bind with Method 1

On the Slack App management page → OAuth & Permissions:

3.1 Add Redirect URLs​

https://your-domain:port/agent/api/slack-oauth/callback

Example:

Note:

  • The protocol must match (HTTPS)
  • If you don't use a default port (80/443), include the port number
  • You can configure multiple callback URLs (development/test/production)

3.2 Configure User Token Scopes​

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

  • identity.basic - Get basic user information (required)
  • identity.email - Get the user's email (optional)

Note: After you add or modify Scopes, you need to reinstall the app to the Workspace.

3.3 Configure Bot Token Scopes​

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

  • chat:write - Send messages
  • app_mentions:read - Read @ mentions
  • channels:history - Read channel message history
  • channels:read - Read channel information
  • groups:history - Read private channel message history
  • im:history - Read direct message history
  • im:read - Read direct message information
  • files:write - Upload, edit, and delete files
  • files:read - View shared files

4. Configure App Home and the bot​

  1. In App Home → Show Tabs, enable:

- Home Tab - Users can interact with the Bot in Home

- Message Tab - The Bot's direct message interface

Select: Allow users to send Slash commands and messages from the messages tab

  1. In Interactivity & Shortcuts, enable Interactivity
  2. In Socket Mode, enable Socket Mode (if you use a WebSocket connection)

5. Add Event Subscriptions​

  1. In Event Subscriptions, turn on Enable Events.
  2. In Subscribe to bot events, add app_mention to receive new tasks started by @mentioning the App in public or private channels.
  3. Add message.channels and message.groups to receive answers to pending questions and replies that continue execution in threads of public/private channels.
  4. Keep message.im to receive direct messages. If you also need group direct messages, you can add message.mpim and grant the corresponding message history permission.
warning

Socket Mode, event, and interactivity checks:

  • Grant the App-Level Token at least connections:write, and turn on Enable Socket Mode.
  • Bot Token Scopes must include at least chat:write, app_mentions:read, channels:history, groups:history, im:history, files:read, and files:write.
  • Interactivity must be turned on. In Socket Mode, no public Request URL is needed, but message forms, Modal submissions, and continuing execution still depend on Interactivity.
  • After you modify OAuth Scopes or Bot Events, you must reinstall the App to the Workspace. After you regenerate the App-Level Token, you also need to update the App Token in the channel configuration.

6. Install the app to the Workspace​

On the OAuth & Permissions page, click Install to Workspace to authorize the app to access the Workspace.

How to use​

Method 1: Binding code (recommended)​

Slack supports binding accounts in group chats with a binding code, which makes it easy to roll out within a team.

Bind a user account​

  1. Log in to the system
  2. Click your avatar in the lower-left corner to open the menu
  3. Find the Slack row and click Get Binding Code
  4. The system generates a 6-character binding code (such as FRT12H) that is valid for 10 minutes
  5. Send a direct message to the bot in Slack: +bind FRT12H
  6. After binding succeeds, Slack shows a Binding successful message

Unbind an account​

  1. Click your avatar in the lower-left corner to open the menu
  2. Find the Slack row and click Unbind
  3. Confirm the unbinding
  4. After unbinding succeeds, the menu shows the Unbound status

Method 2: OAuth authorization​

Complete binding through browser authorization.

Bind a user account​

  1. Log in to the system
  2. Click your avatar in the lower-left corner to open the menu
  3. Find the Slack row and click Bind
  4. You're redirected to the Slack authorization page
  5. Confirm the authorization (select a Workspace)
  6. You're automatically redirected back to the system, and Binding successful appears
  7. Close the authorization window. The original page refreshes automatically, and the menu shows the Bound status

Unbind a user account​

  1. Click your avatar in the lower-left corner to open the menu
  2. Find the Slack row and click Unbind
  3. Confirm the unbinding
  4. After unbinding succeeds, the menu shows the Unbound status

Custom commands​

The Slack bot supports the following commands (all commands start with +):

CommandDescriptionExample
+bind <CODE>Binds an account with a binding code (6 uppercase letters + digits)+bind FRT12H
+newStarts a new session and clears the current session historySend +new
+agent <名称> <消息>Sends a message to the Agent with the specified name+agent rhea 你好
+agent <消息>Sends a message to the system default Agent+agent 你好

Notes:

  • Messages that don't start with + are sent directly to the system default Agent
  • The +bind command is used for the binding code method. Unbound users must bind their account before they can use other features
  • The +new command clears the current session and starts over
  • The Agent name must be an Agent that the user has permission to access
  • Command parameters are case-sensitive
  • The binding code character set excludes easily confused characters (I/O/0/1)

Group chat message routing​

Group chat message routing lets the same Slack App hand different questions to different Agents or Teams based on rules. A Group Chat Space corresponds to the current Workspace, and the configuration applies to channels in that Workspace where this App is installed. Only members who have bound an Agentic Engine account and explicitly @mention the App in the channel can start tasks.

Admin setup​

  1. Make sure that Socket Mode, Event Subscriptions, and Interactivity are enabled, and that Bot Events include at least app_mention, message.channels, message.groups, and message.im. After you modify scopes, reinstall the App to the Workspace.
  2. Invite the App to the public or private channels where you want to use it. In a private channel, if the App isn't a member, it can't receive messages even if the configuration is correct.
  3. Go to System Admin → Channels, open Message Routing on the corresponding Slack channel, select the Workspace, and configure the default Agent/Team.
  4. Add up to 19 rules as needed. For each rule, select an Agent/Team, fill in the required Command, and optionally add up to 10 keywords. Then turn on the enable switch and save.
  5. Send @App +help in the channel to verify the setup, and make sure that the capability list and thread replies both work properly.
Config itemsRule
Default Agent/TeamRequired before enabling. Used when no command is specified and no keyword is matched.
CommandRequired, 1–32 characters. You can use letters, digits, -, and _, but not system-reserved commands. Differences in letter case or between full-width and half-width characters don't make commands distinct.
KeywordsOptional. Up to 10 per rule, each 2–32 characters. When multiple keywords match, the longer keyword takes priority. If no unique match can be determined among keywords of the same length, the default Agent/Team is used.
Available optionsYou can select enabled and runnable system/company Agents, as well as Teams in the current company. Personal Agents don't appear as group chat routing candidates.

Usage in channels​

PurposeExampleDescription
View available capabilities@App +help
@App 能力清单		Lists the default, commands, and keywords. Capabilities that you don't have permission for or that can't currently run aren't shown.
Specify an Agent/Team@App +analysis 分析本周数据analysis is a command configured by the admin. You can also send @App @analysis 分析本周数据.
Route by keyword@App 帮我检查埋点方案When the message text matches a keyword, it's handed to the corresponding Agent/Team. Otherwise, the default is used.
Cancel a task@App +cancelMust be sent exactly as the entire message. Text already output is kept, and a separate cancellation confirmation is sent.
Legacy syntax@App +agent analysis 分析本周数据Still supported, but using +analysis directly is recommended.

Thread replies: You must @mention the App to start a regular new task. When a task is already waiting for an answer in a thread, you can reply directly in that thread as prompted without @mentioning the App again. Regular channel messages with no waiting task are ignored.

Command scope: Group chat routing doesn't support +new. Direct messages still support +new, +agent, and +cancel.

Public context and personal data: For reference, the system uses only recent public channel turns that explicitly @mentioned the App and were actually processed. Regular messages that don't @mention the App, other channels, direct messages, and personal memories are never mixed in. History serves only as untrusted reference, and only the current message is the instruction for this turn.

FAQ​

1. The Slack binding option doesn't appear in the user menu​

Reason:

  • Slack channel is not configured or not enabled
  • There is no record with type='slack' in the Channel table
  • The config field is missing clientId or clientSecret

Solution:

  • Check whether a Slack channel exists in Channels
  • Make sure that the channel is enabled
  • Make sure that the config field contains clientId and clientSecret

2. Redirect fails after you click Bind​

Error message: Failed to get authorization URL

Solution:

  • Check that the Client ID and Client Secret of the Slack App are correct
  • Make sure that the Slack App is installed to the Workspace
  • Check the backend logs for the specific error message

3. Callback fails after authorization​

Error message: Callback URL verification failed, or state verification failed

Solution:

  • Make sure that the Redirect URLs configured for the Slack App include the callback URL that you're currently accessing
  • Check that the protocol (HTTP/HTTPS) and port match
  • Make sure that there are no cross-origin issues

4. Binding failure​

Error message: This Slack account is bound to another user

Solution:

  • A Slack account can be bound to only one system user
  • To change the binding, first unbind it from the original account

5. Production allowlist verification fails​

Error message: ALLOWED_ORIGINS must be configured in the production environment, or Invalid origin

Solution:

  • Configure the ALLOWED_ORIGINS environment variable
  • Make sure that the origin is in the allowlist
  • Separate multiple domains with commas

Related pages and next steps

Was this page helpful?
On this page