For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

  • You have created an “AI Assistant” on the MaiAgent platform

  • You have administrator access to a Slack workspace

Quick Install: Use an App Manifest

Go to Slack API, 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:

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.

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.

Step One: Create a Slack App

1. Go to Slack API to Create an App

Go to https://api.slack.com/apps and click Create an App.

Slack API — Your Apps page

2. Select From scratch

Select From scratch to configure the app manually through the graphical interface.

Select From scratch to create the app

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 a workspace

4. Get the Signing Secret

After creating the app, open the Basic Information page. Find Signing Secret under App Credentials, click Show, and copy it for later use.


Step Two: Configure Bot Permissions

1. Open OAuth & Permissions

Click OAuth & Permissions in the left menu.

OAuth & Permissions page

2. Add Bot Token Scopes

Scroll down to Bot Token Scopes, click Add an OAuth Scope, 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

Bot Token Scopes permission settings

3. Install the App to the Workspace

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

Install App page

Slack redirects you to the authorization page. Review the permissions and click Allow.

Authorize the app to access the workspace

4. Copy the Bot User OAuth Token

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

Copy the Bot User OAuth Token

Step Three: Configure App Home (Enable Direct Messages)

Open App Home from the left menu. Under Show Tabs:

  1. Enable Messages Tab

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

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

Step Four: Create a Slack Channel in MaiAgent

1. Open Channel Integration

In MaiAgent, click Channels in the left menu, click Connect Channel in the upper right, and select Slack.

2. Enter the Basic Settings

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

Click Verify Credentials to confirm that the Token and Secret are correct.

4. Chat Room Settings

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

Click Connect Channel 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

1. Enable Events

Click Event Subscriptions in the Slack App’s left menu and turn on Enable Events.

Event Subscriptions settings page

2. Paste the Request URL

Paste the Webhook URL generated by MaiAgent into Request URL. Slack verifies it automatically. Verified ✓ indicates that setup succeeded.

Request URL verified successfully

3. Subscribe to Bot Events

Expand Subscribe to bot events, 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

@ mentions in channels

Subscribe to Bot Events

4. Save Changes

Click Save Changes to finish setup.


Get Started

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

Direct Messages

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

File Upload and Analysis

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

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

To add the bot to a specific channel, enter /invite @BotName in that channel, or add it through Channel Settings → Integrations → Add apps.

Last updated

Was this helpful?