> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/en/build/choose-channel/slack.md). # Connect a Conversation Platform: Slack Connect the Slack chat platform. Create a Slack App from an App Manifest, configure Bot permissions and Event Subscriptions, and let employees chat with the Agent through Slack direct messages or chan ## Pre-Connection Checklist * An "AI Assistant" has been created on the [MaiAgent platform](https://admin.maiagent.ai/) * You have administrator permissions for a Slack Workspace ## Quick Install: Use an App Manifest Go to the [Slack API](https://api.slack.com/apps), click Create New App, select From a manifest, and choose the Workspace where you want to install the App. Switch to the YAML tab and paste the complete manifest below: ```yaml display_information: name: MaiAgentBot features: app_home: messages_tab_enabled: true messages_tab_read_only_enabled: false bot_user: display_name: MaiAgentBot always_online: false oauth_config: scopes: bot: - chat:write - users:read - im:history - channels:history - groups:history - files:read - app_mentions:read settings: org_deploy_enabled: false socket_mode_enabled: false token_rotation_enabled: false ``` `MaiAgentBot` is an example name; you can customize `display_information.name` and `features.bot_user.display_name` before creating the App. {% hint style="info" %} After creating the App with a manifest, you can skip Steps 1 to 3 of the step-by-step guide below (create the App, configure scopes, enable App Home). You still need to start from Step 4 to create the chat platform in MaiAgent, obtain the Webhook URL, and then complete the Event Subscriptions in Step 5. The Request URL is only generated after the MaiAgent chat platform has been created. {% endhint %} ## Step 1: Create a Slack App ### 1. Go to the Slack API to create an App Go to and click Create an App.

### 2. Select From scratch Select From scratch to configure the App manually through the graphical interface.

### 3. Enter the App name and Workspace Enter an App name (for example, `MaiAgentBot`), select the Slack Workspace where you want to install it, and click Create App.

Enter the App name and select the Workspace

### 4. Get the Signing Secret After the App is created, go to the Basic Information page, find the Signing Secret in the **App Credentials** section, click Show, and copy it for later use. *** ## Step 2: Configure Bot Permissions ### 1. Go to OAuth & Permissions In the left menu, click OAuth & Permissions.

### 2. Add Bot Token Scopes Scroll down to the **Bot Token Scopes** section, click Add an OAuth Scope, and add the following permissions one by one: | Scope | Description | | ------------------- | ---------------------------------------- | | `app_mentions:read` | Read messages that @mention the bot | | `channels:history` | Read message history in public channels | | `chat:write` | Send messages | | `files:read` | Read files (images/documents) | | `groups:history` | Read message history in private channels | | `im:history` | Read message history in direct messages | | `mpim:history` | Read history in group direct messages |

### 3. Install the App to the Workspace Scroll back to the top of the page and click Install to Workspace (or Reinstall to Workspace).

Slack redirects you to the authorization page. After reviewing the permissions, click Allow.

Authorize the App to access the Workspace

### 4. Copy the Bot User OAuth Token After installation, return to the OAuth & Permissions page and copy the Bot User OAuth Token (in the format `xoxb-...`).

*** ## Step 3: Configure App Home (Enable Direct Messages) Go to the App Home page in the left menu. In the **Show Tabs** section: 1. Turn on Messages Tab 2. Check Allow users to send Slash commands and messages from the messages tab

Enable the Messages Tab so users can send direct messages to the Bot

{% hint style="warning" %} You must complete this step; otherwise, users cannot interact with the Bot through direct messages. {% endhint %} *** ## Step 4: Create a Slack Chat Platform in MaiAgent ### 1. Go to Connect Chat Platform In the MaiAgent left menu, click Chat Platforms, click Connect Chat Platform in the upper right corner, and select Slack. ### 2. Fill in the basic settings | Field | Description | | ------------------------ | ------------------------------------------------------ | | **Name** | Give this integration a name (required) | | **AI Assistant** | Select the Agent to bind | | **Bot User OAuth Token** | Paste the Bot Token obtained in Step 2 (required) | | **Signing Secret** | Paste the Signing Secret obtained in Step 1 (required) | ### 3. Verify credentials Click the Verify Credentials button to confirm that the Token and Secret are correct. ### 4. Chat room settings | Setting | Description | | ------------------------------------------ | --------------------------------------------------------------------------- | | **Respond only when @mentioned in groups** | When enabled, the Bot responds in group channels only when it is @mentioned | | **Enable reset command** | When enabled, users can restart the conversation with a command | ### 5. Save and get the Webhook URL Click Connect Chat Platform to finish creating it. The system generates a **Webhook URL**; copy it for later use. *** ## Step 5: Return to the Slack App to Configure Event Subscriptions ### 1. Enable Events In the Slack App left menu, click Event Subscriptions and turn on Enable Events.

### 2. Paste the Request URL Paste the **Webhook URL** generated by MaiAgent into the Request URL field. Slack verifies it automatically, and Verified ✓ indicates that the setup succeeded.

### 3. Subscribe to Bot Events Expand the **Subscribe to bot events** section, click Add Bot User Event, and add the following events: | Event | Description | | ------------------ | ------------------------------------- | | `message.im` | New messages in direct messages | | `message.channels` | New messages in public channels | | `message.groups` | New messages in private channels | | `message.mpim` | New messages in group direct messages | | `app_mention` | @mentioned in a channel |

### 4. Save changes Click Save Changes to finish the configuration. {% hint style="warning" %} After saving, Slack may ask you to reinstall the App. Click the prompt at the top of the page to reinstall and apply the new permissions. {% endhint %} *** ## Getting Started Once the integration is complete, you can interact with the Agent in the following ways: ### Direct message conversations Send a direct message to the Bot in Slack, and the Agent replies automatically. Text, images, and files are supported. ### File upload and analysis Users can upload files such as Excel and PDF in a conversation. The Agent can read the file contents and answer related questions. ### Channel @mentions In a channel, type `@BotName your question`, and the Agent replies in the channel. {% hint style="info" %} To add the Bot to a specific channel, type `/invite @BotName` in that channel, or add it from the channel settings → Integrations → Add apps. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.maiagent.ai/maiagent-user-guide/en/build/choose-channel/slack.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.