> 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 Slack as a chat channel: create a Slack App with an App Manifest, configure Bot permissions and Event Subscriptions, and let employees chat with an Agent in Slack direct messages or channels.

## Pre-Integration Checklist <a href="#pre-integration-checklist" id="pre-integration-checklist"></a>

* You have created an “AI Assistant” on the [MaiAgent platform](https://admin.maiagent.ai/)
* You have administrator access to a Slack workspace

## Quick Install: Use an App Manifest <a href="#quick-install-app-manifest" id="quick-install-app-manifest"></a>

Go to [Slack API](https://api.slack.com/apps), click <mark style="color:blue;">Create New App</mark>, select <mark style="color:blue;">From a manifest</mark>, and choose the workspace where you want to install the app. Switch to the <mark style="color:blue;">YAML</mark> 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" %}
If you create the app with a manifest, you can skip steps one through three of the detailed instructions below (create the app, configure scopes, and enable App Home). You still need to start at step four to create a channel in MaiAgent, obtain the Webhook URL, and then complete Event Subscriptions in step five. The Request URL is only generated after you create the channel in MaiAgent.
{% endhint %}

## Step One: Create a Slack App <a href="#step-create-slack-app" id="step-create-slack-app"></a>

### 1. Go to Slack API to Create an App <a href="#step-go-to-slack-api" id="step-go-to-slack-api"></a>

Go to <https://api.slack.com/apps> and click <mark style="color:blue;">Create an App</mark>.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-ce0387658ad808d5a696fcaf41634fbc7876aab5%2Fslack-api-your-apps.png?alt=media" alt=""><figcaption><p>Slack API — Your Apps page</p></figcaption></figure>

### 2. Select From scratch <a href="#step-create-from-scratch" id="step-create-from-scratch"></a>

Select <mark style="color:blue;">From scratch</mark> to configure the app manually through the graphical interface.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-ef198579b66f80f26f2a9ff794bb4f55b74c9da2%2Fslack-create-app-scratch.png?alt=media" alt=""><figcaption><p>Select From scratch to create the app</p></figcaption></figure>

### 3. Enter the App Name and Workspace <a href="#step-fill-app-name-and-workspace" id="step-fill-app-name-and-workspace"></a>

Enter an app name (for example, `MaiAgentBot`), select the Slack workspace where you want to install it, and click <mark style="color:blue;">Create App</mark>.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-0608dfa14ee9002008deb49bc7af2d9491057e78%2Fslack-create-app-name.png?alt=media" alt=""><figcaption><p>Enter the app name and select a workspace</p></figcaption></figure>

### 4. Get the Signing Secret <a href="#step-get-signing-secret" id="step-get-signing-secret"></a>

After creating the app, open the <mark style="color:blue;">Basic Information</mark> page. Find <mark style="color:blue;">Signing Secret</mark> under **App Credentials**, click <mark style="color:blue;">Show</mark>, and copy it for later use.

***

## Step Two: Configure Bot Permissions <a href="#step-configure-bot-permissions" id="step-configure-bot-permissions"></a>

### 1. Open OAuth & Permissions <a href="#step-go-to-oauth-permissions" id="step-go-to-oauth-permissions"></a>

Click <mark style="color:blue;">OAuth & Permissions</mark> in the left menu.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-ccce8cfe52662eba88dc58278f7ab3fb48e34e29%2Fslack-oauth-permissions.png?alt=media" alt=""><figcaption><p>OAuth &#x26; Permissions page</p></figcaption></figure>

### 2. Add Bot Token Scopes <a href="#step-add-bot-token-scopes" id="step-add-bot-token-scopes"></a>

Scroll down to **Bot Token Scopes**, click <mark style="color:blue;">Add an OAuth Scope</mark>, and add the following permissions:

| 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 direct message history              |
| `mpim:history`      | Read group direct message history        |

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-ad151db9b82446f54dd72069c0a929050cc67403%2Fslack-bot-scopes.png?alt=media" alt=""><figcaption><p>Bot Token Scopes permission settings</p></figcaption></figure>

### 3. Install the App to the Workspace <a href="#step-install-app-to-workspace" id="step-install-app-to-workspace"></a>

Scroll back to the top of the page and click <mark style="color:blue;">Install to Workspace</mark> (or Reinstall to Workspace).

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-5b4dc93fd2fa5c1286e543b1825cfd92049da9e9%2Fslack-install-app.png?alt=media" alt=""><figcaption><p>Install App page</p></figcaption></figure>

Slack redirects you to the authorization page. Review the permissions and click <mark style="color:blue;">Allow</mark>.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-daf77d582ca9b5f01416b59e0c1c2733cf9b8d4d%2Fslack-authorize.png?alt=media" alt=""><figcaption><p>Authorize the app to access the workspace</p></figcaption></figure>

### 4. Copy the Bot User OAuth Token <a href="#step-copy-bot-user-oauth-token" id="step-copy-bot-user-oauth-token"></a>

After installation, return to <mark style="color:blue;">OAuth & Permissions</mark> and copy the <mark style="color:blue;">Bot User OAuth Token</mark> (in the format `xoxb-...`).

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-0497bc9b32949a666883cab21c8da7cdbc013795%2Fslack-bot-token.png?alt=media" alt=""><figcaption><p>Copy the Bot User OAuth Token</p></figcaption></figure>

***

## Step Three: Configure App Home (Enable Direct Messages) <a href="#step-configure-app-home" id="step-configure-app-home"></a>

Open <mark style="color:blue;">App Home</mark> from the left menu. Under **Show Tabs**:

1. Enable <mark style="color:blue;">Messages Tab</mark>
2. Select <mark style="color:blue;">Allow users to send Slash commands and messages from the messages tab</mark>

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-2d94bf960a8fc3380a7d7558b963b1047874fd5e%2Fslack-app-home-messages.png?alt=media" alt=""><figcaption><p>Enable Messages Tab so users can send direct messages to the bot</p></figcaption></figure>

{% hint style="warning" %}
You must complete this step for users to interact with the bot through direct messages.
{% endhint %}

***

## Step Four: Create a Slack Channel in MaiAgent <a href="#step-create-slack-channel-in-maiagent" id="step-create-slack-channel-in-maiagent"></a>

### 1. Open Channel Integration <a href="#step-go-to-channel-integration" id="step-go-to-channel-integration"></a>

In MaiAgent, click <mark style="color:blue;">Channels</mark> in the left menu, click <mark style="color:blue;">Connect Channel</mark> in the upper right, and select <mark style="color:blue;">Slack</mark>.

### 2. Enter the Basic Settings <a href="#step-fill-basic-settings" id="step-fill-basic-settings"></a>

| Field                    | Description                                              |
| ------------------------ | -------------------------------------------------------- |
| **Name**                 | Enter a name for this integration (required)             |
| **AI Assistant**         | Select the Agent to connect                              |
| **Bot User OAuth Token** | Paste the Bot Token obtained in step two (required)      |
| **Signing Secret**       | Paste the Signing Secret obtained in step one (required) |

### 3. Verify Credentials <a href="#step-verify-credentials" id="step-verify-credentials"></a>

Click <mark style="color:blue;">Verify Credentials</mark> to confirm that the Token and Secret are correct.

### 4. Chat Room Settings <a href="#step-chat-room-settings" id="step-chat-room-settings"></a>

| Setting                                     | Description                                                                                                                                                                                                                                                                                                          |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Only respond when @ mentioned in groups** | When enabled, the bot only replies in group channels when it is @ mentioned                                                                                                                                                                                                                                          |
| **Enable reset commands**                   | When enabled, you can add one or more command phrases (such as “Start over”). When a user sends a Slack message that exactly matches one of these phrases, a new conversation starts for that user. The command itself receives no reply; AI responds in the new conversation when the user sends their next message |

### 5. Save and Get the Webhook URL <a href="#step-save-and-get-webhook-url" id="step-save-and-get-webhook-url"></a>

Click <mark style="color:blue;">Connect Channel</mark> to finish creating the channel. The system generates a **Webhook URL**. Copy it for later use.

***

## Step Five: Return to the Slack App to Configure Event Subscriptions <a href="#step-configure-event-subscriptions" id="step-configure-event-subscriptions"></a>

### 1. Enable Events <a href="#step-enable-events" id="step-enable-events"></a>

Click <mark style="color:blue;">Event Subscriptions</mark> in the Slack App’s left menu and turn on <mark style="color:blue;">Enable Events</mark>.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-589c809a1adab5265cedad08dadedf9699b1cfeb%2Fslack-event-subscriptions.png?alt=media" alt=""><figcaption><p>Event Subscriptions settings page</p></figcaption></figure>

### 2. Paste the Request URL <a href="#step-paste-request-url" id="step-paste-request-url"></a>

Paste the **Webhook URL** generated by MaiAgent into <mark style="color:blue;">Request URL</mark>. Slack verifies it automatically. <mark style="color:green;">Verified ✓</mark> indicates that setup succeeded.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-0166cb7b78b16d9424fb3d506b972ab76f6ed744%2Fslack-event-verified.png?alt=media" alt=""><figcaption><p>Request URL verified successfully</p></figcaption></figure>

### 3. Subscribe to Bot Events <a href="#step-subscribe-bot-events" id="step-subscribe-bot-events"></a>

Expand **Subscribe to bot events**, click <mark style="color:blue;">Add Bot User Event</mark>, 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`      | @ mentions in channels                |

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-a739fd3cc31beba2fbb8aa335c6a9ca7bb6fd79f%2Fslack-event-bot-events.png?alt=media" alt=""><figcaption><p>Subscribe to Bot Events</p></figcaption></figure>

### 4. Save Changes <a href="#step-save-changes" id="step-save-changes"></a>

Click <mark style="color:blue;">Save Changes</mark> to finish setup.

{% hint style="warning" %}
After saving, Slack may ask you to reinstall the app. Click the notice at the top of the page to reinstall it and apply the new permissions.
{% endhint %}

***

## Get Started <a href="#getting-started" id="getting-started"></a>

After connecting the channel, you can interact with the Agent in the following ways:

### Direct Messages <a href="#direct-message-conversation" id="direct-message-conversation"></a>

Send the bot a direct message in Slack, and the Agent replies automatically. You can send text, images, and files.

### File Upload and Analysis <a href="#file-upload-and-analysis" id="file-upload-and-analysis"></a>

Users can upload files such as Excel and PDF documents in a conversation. The Agent can read their contents and answer related questions.

### @ Mentions in Channels <a href="#channel-mention" id="channel-mention"></a>

Enter `@BotName your question` in a channel, and the Agent replies in that channel.

{% hint style="info" %}
To add the bot to a specific channel, enter `/invite @BotName` in that channel, or add it through 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=<question>&goal=<user_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.
