> 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/maiagent-user-guide-en/conversations/slack.md).

# Integrate with Platform: Slack

## 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

## Step 1: Create a Slack App

### 1. Go to Slack API to Create an App

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

### 2. Select From scratch

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

### 3. Enter App Name and Workspace

Enter the App name (e.g., `MaiAgentBot`) and select the Slack Workspace to install it in, then click <mark style="color:blue;">Create App</mark>.

### 4. Obtain the Signing Secret

After creation, go to the <mark style="color:blue;">Basic Information</mark> page and find the <mark style="color:blue;">Signing Secret</mark> in the **App Credentials** section. Click <mark style="color:blue;">Show</mark> and copy it for later use.

***

## Step 2: Configure Bot Permissions

### 1. Go to OAuth & Permissions

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

### 2. Add Bot Token Scopes

Scroll down to the **Bot Token Scopes** section, 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 public channel message history  |
| `chat:write`        | Send messages                        |
| `files:read`        | Read files (images/documents)        |
| `groups:history`    | Read private channel message history |
| `im:history`        | Read direct message history          |
| `mpim:history`      | Read group direct message history    |

### 3. Install App to Workspace

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

Slack will redirect to the authorization page. After confirming the permissions, click <mark style="color:blue;">Allow</mark>.

### 4. Copy the Bot User OAuth Token

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

***

## Step 3: Configure App Home (Enable Direct Messages)

Go to the <mark style="color:blue;">App Home</mark> page in the left menu and in the **Show Tabs** section:

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

{% hint style="warning" %}
This step must be completed; otherwise, users cannot interact with the Bot via direct messages.
{% endhint %}

***

## Step 4: Create a Slack Chat Platform in MaiAgent

### 1. Go to Connect Chat Platform

Click <mark style="color:blue;">Chat Platforms</mark> in the MaiAgent left menu, then click <mark style="color:blue;">Connect Chat Platform</mark> in the upper right corner and select <mark style="color:blue;">Slack</mark>.

### 2. Enter Basic Settings

| Field                    | Description                                            |
| ------------------------ | ------------------------------------------------------ |
| **Name**                 | Give this connection a name (required)                 |
| **AI Assistant**         | Select the AI Assistant 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 <mark style="color:blue;">Verify Credentials</mark> button to confirm the Token and Secret are correct.

### 4. Chat Room Settings

| Setting                                     | Description                                                            |
| ------------------------------------------- | ---------------------------------------------------------------------- |
| **Respond only when @ mentioned in groups** | When enabled, the Bot only responds in group channels when @ mentioned |
| **Enable reset command**                    | When enabled, users can restart the conversation using a command       |

### 5. Save and Obtain the Webhook URL

Click <mark style="color:blue;">Connect Chat Platform</mark> to complete the setup. The system will generate a **Webhook URL** — copy it for later use.

***

## Step 5: Return to Slack App to Configure Event Subscriptions

### 1. Enable Events

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

### 2. Paste the Request URL

Paste the **Webhook URL** generated by MaiAgent into the <mark style="color:blue;">Request URL</mark> field. Slack will automatically verify it — <mark style="color:green;">Verified ✓</mark> indicates the setup is successful.

### 3. Subscribe to Bot Events

Expand the **Subscribe to bot events** section, 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`      | @ mentioned in a channel              |

### 4. Save Changes

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

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

***

## Getting Started

After the connection is complete, you can interact with the AI Assistant in the following ways:

### Direct Message Conversation

Send a direct message to the Bot in Slack, and the AI Assistant will reply automatically. Supports sending text, images, and files.

### File Upload and Analysis

Users can upload Excel, PDF, and other files during conversations. The AI Assistant can read file content and answer related questions.

### Channel @ Mention

In a channel, type `@BotName your question`, and the AI Assistant will reply in the channel.

{% hint style="info" %}
To add the Bot to a specific channel, type `/invite @BotName` in that channel, or add it through Channel Settings → Integrations → Add an App.
{% 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.maiagent.ai/maiagent-user-guide/maiagent-user-guide-en/conversations/slack.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.