> ## Documentation Index
> Fetch the complete documentation index at: https://koreai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up Slack

[Back to messaging or digital channels](https://koreai.mintlify.site/agent-platform/channels.md#messaging-or-digital-channels)

Deploy your agent as a Slack bot so your team reaches it through direct messages and channel mentions. You connect your own Slack app to Artemis, either by entering its credentials manually or through **Add to Slack**.

The setup requires:

1. [Choose a setup method](#choose-a-setup-method).
2. [Prepare your Slack app](#prepare-your-slack-app) with the scopes the agent needs.
3. [Artemis channel configuration](#artemis-channel-configuration): create the connection, then copy its Webhook URL.
4. [Event subscriptions in Slack](#event-subscriptions-in-slack): register the Webhook URL so Slack delivers messages.
5. [Verify the connection](#verify-the-connection) in a direct message and in a channel.

After you complete the configuration, Slack posts each direct message and @mention to Artemis, and the agent replies in the same conversation.

**Important considerations**

* **Manual credentials are the recommended setup**: They connect your own Slack app without depending on platform-managed OAuth. **Add to Slack** works only when your platform administrator enables it.
* **Slack uses two different URLs**: The OAuth Redirect URL serves only **Add to Slack**. The Events Request URL delivers messages. Pasting one in place of the other breaks the setup.
* **Create the connection before you register events**: Slack verifies the Request URL the moment you paste it, so Artemis must already hold the matching Team ID:App ID and Signing Secret.
* **Treat the Bot Token and Signing Secret as production secrets**: Paste them only into Artemis. Keep them out of tickets, chat messages, screenshots, and source control.

## Prerequisites

Confirm these before you start, because Slack app changes need workspace permissions.

* Permission to create or manage Slack apps in the target workspace, or a Workspace Owner or App Manager who approves the app.
* Artemis project access with permission to open **Deployments** > **Channels**, and a deployed agent in the environment you intend to bind.

***

## Choose a setup method

Both methods produce the same connection. They differ in how Artemis gets the Slack credentials.

> [card] [Enter credentials manually](#artemis-channel-configuration)
>
> Recommended. You copy the Team ID, App ID, Bot Token, and Signing Secret from your Slack app.

> [card] [Add to Slack](#artemis-channel-configuration)
>
> Slack authorizes the workspace and fills in the identifiers. Requires administrator enablement.

### Slack URLs at a glance

Slack asks for URLs on several screens. Each URL has one job.

| URL | Purpose | Where it goes in Slack |
| - | - | - |
| **OAuth Redirect URL** | Returns **Add to Slack** authorization to Artemis. Manual setup doesn't use it. | **OAuth & Permissions** > **Redirect URLs** |
| **Webhook URL** (Events Request URL) | Delivers messages and events for this connection | **Event Subscriptions** > **Request URL**, and **Interactivity & Shortcuts** > **Request URL** |
| **Slash Command URL** | Delivers slash commands for this connection | The command's **Request URL** |

***

## Prepare your Slack app

Set up the app in Slack before you open Artemis. Select **Open Slack app settings** in the setup guide to jump straight to your apps.

**1. Create or select your Slack app**

1. Go to [Your Apps](https://api.slack.com/apps) and select **Create New App**.
2. Choose **From scratch**, name the app, and choose a development workspace.

**2. Register the OAuth Redirect URL (Add to Slack only)**

Skip this step for manual setup.

1. Go to **OAuth & Permissions** > **Redirect URLs**.
2. Add the OAuth Redirect URL that the Artemis setup guide shows, and save.

Slack requires an exact match on scheme, host, port, path, and trailing slash.

**3. Add bot token scopes**

Go to **OAuth & Permissions** > **Bot Token Scopes** and add the core scopes. Add optional scopes only for the feature that needs them.

| Scope | Required for |
| - | - |
| `chat:write`, `app_mentions:read`, `im:history`, `im:read`, `im:write` | Core messaging. Always add these. |
| `files:read` | File attachments |
| `commands` | Slash commands |
| `chat:write.public` | Posting to public channels the bot hasn't joined |
| `users:read` | Tools that look up the sender's profile |
| `users:read`, `users:read.email` | **Require verified Slack identity** |

**4. Install the app**

1. Select **Install to Workspace** and approve the permissions.
2. Reinstall the app whenever you change scopes, so the bot token receives the new grants.

***

## Artemis channel configuration

Create the connection before you register event subscriptions. Slack sends its verification challenge immediately, and only a saved connection can answer it.

1. Open Artemis and select the project.

2. Go to **Deployments** > **Channels** > **Slack** > **+ New**. The **New Slack Connection** dialog opens, with the setup guide on the left and the connection fields on the right.

3. Complete the steps for your setup method:

   > [tab] Enter credentials manually
   >
   > 1. Select **Enter credentials manually instead**.
   > 2. Collect the values below from Slack and enter them.
   >
   > | Artemis field | Where to find it in Slack | Notes |
   > | - | - | - |
   > | **Slack Team ID:App ID** | Team ID: open the workspace in a browser and read the segment beginning with `T` in the `app.slack.com/client/` URL. App ID: **Basic Information** > **App Credentials**. | Join the two values with one colon and no spaces. The Team ID doesn't appear in the Slack app settings URL. |
   > | **Bot Token** | **OAuth & Permissions** > **OAuth Tokens** > **Bot User OAuth Token** | Begins with `xoxb-`. Authorizes every reply the agent sends. |
   > | **Signing Secret** | **Basic Information** > **App Credentials** > **Signing Secret** | Verifies that each inbound request comes from Slack. |

   > [tab] Add to Slack
   >
   > 1. Enter a **Display Name** that identifies the workspace and environment.
   > 2. Select **Add to Slack**, choose the intended workspace, review the requested permissions, and select **Allow**.
   > 3. Confirm the connected workspace. Slack fills in the **Slack Team ID:App ID** for you.
   >
   > If Slack reports that the app needs approval, ask a Workspace Owner or App Manager to approve it, then select **Add to Slack** again.

4. Configure the remaining fields:

   | Artemis field | What it controls |
   | - | - |
   | **Display Name** | The label operators see in the connections list. Routing ignores it. |
   | **Environment** | The environment whose active deployment answers messages. If no environment has an active deployment, leave the default to use the working copy, and bind it later from the **Deployment** tab. |
   | **Provider Verification Strength** | How far the runtime trusts Slack's identity assertion when it links a sender to an existing session. Keep **Weak** unless you base continuity and account-linking decisions on Slack identity. |
   | **Initial Status** | **Active** takes traffic immediately. **Inactive** saves the connection disabled until you activate it. |

5. Select **Create**.

6. Open the connection and copy the **Webhook URL** from the summary panel on the right. The URL ends with this connection's encoded Team ID:App ID, so copy it rather than building it.

***

## Event subscriptions in Slack

Event subscriptions turn the app into a conversation. Until Slack has the Request URL, the agent never receives a message.

1. Confirm the Artemis connection exists and is **Active**.
2. In your Slack app, go to **Event Subscriptions** and turn on **Enable Events**.
3. Paste the connection's **Webhook URL** into **Request URL**, and wait for Slack to show **Verified**.
4. Under **Subscribe to bot events**, add `message.im` and `app_mention`.
5. Select **Save Changes**, then reinstall the app if Slack prompts you.

> [!WARNING]
>
> If Slack reports that the challenge value wasn't returned, check that the URL ends with the encoded Team ID:App ID, that the connection exists and is **Active**, and that its Signing Secret matches this Slack app. Don't use the generic `/slack/webhook` URL for verification.

### Validation checklist

Work down this list once per connection.

| Validation item | Expected result |
| :- | :- |
| Prepare the Slack app | Core scopes added and the app installed in the workspace. |
| Create the Artemis connection | Saved as **Active** with the right Team ID:App ID and environment. |
| Register events | **Request URL** shows **Verified**, and `message.im` and `app_mention` appear under bot events. |
| Test both paths | The agent replies once in a direct message and once to an @mention. |

## Verify the connection

Slack has two conversation paths, and each needs its own test.

1. Send the app a direct message and confirm the agent replies.
2. Invite the app to a channel, @mention it, and confirm the agent replies in the thread.
3. If no reply arrives, open **Sessions** and search for your message. A session means Slack reached Artemis and the reply failed. No session means the event never arrived.

***

## Optional Slack features

Turn these on only when your agent uses them. Each one reuses a connection-specific URL.

| Feature | Setup in Slack |
| - | - |
| **Buttons, menus, and shortcuts** | Turn on **Interactivity & Shortcuts** and paste the same Webhook URL into its **Request URL**. |
| **Slash commands** | Add the `commands` scope, reinstall the app, create the command, and paste the connection's Slash Command URL into its **Request URL**. |
| **Verified Slack identity** | Add `users:read` and `users:read.email`, reinstall the app, then turn on **Require verified Slack identity** in the **Configuration** tab. |

***

## Sessions and sender identity

The Slack channel scopes each conversation to a thread and tells the agent who sent each message.

| Behavior | Description |
| - | - |
| One session per thread | Each Slack thread runs as its own session, so separate requests in the same channel never share context. |
| Sender user ID | The runtime adds the sender's Slack user ID to `session._metadata` as `slackUserId`. A tool can pass it to Slack's [users.info](https://api.slack.com/methods/users.info) method, which needs the `users:read` scope. |

***

## Manage the channel connection

Open a Slack connection from **Deployments** > **Channels** > **Slack** to manage it. The page has a header, three tabs, and a summary panel on the right.

**Header.** Shows the connection name, its environment badge, its status, and when it last changed. The **...** overflow menu holds the connection-level actions.

**Summary panel.** Stays visible on every tab and carries the values Slack needs.

| Field | Description |
| - | - |
| **Channel** and **Connection Type** | Read **Slack** and **Channel Connection**. |
| **Identifier** | The Slack Team ID:App ID this connection routes on. |
| **Credentials** | Reads **Configured** once credentials save. |
| **Webhook URL** | The Request URL for **Event Subscriptions** and **Interactivity & Shortcuts**, with a copy control. |
| **Created** and **Updated** | Date and time of creation and of the last change. |

> [tab] Credentials
>
> Artemis encrypts credentials after you save them. Leave a field blank to keep its current value, or enter a new value to replace it.
>
> | Field | Description |
> | - | - |
> | **Use Auth Profile** | Authenticates through a saved auth profile in place of the fields below. |
> | **Bot Token** | Authorizes outbound replies. Replace it here after you reinstall or rotate the app. |
> | **Signing Secret** | Verifies inbound requests. A mismatch fails Slack's verification challenge. |
>
> Select **Save Credentials** to apply your changes.

> [tab] Configuration
>
> Update the connection's behavior in Slack.
>
> | Setting | Description |
> | - | - |
> | **Display Name** | The label operators see in the connections list. |
> | **Provider Verification Strength** | How far the runtime trusts Slack's identity assertion. |
> | **Slack Team ID:App ID** | Read-only. A connection pointed at the wrong app needs replacing rather than editing. |
> | **Require verified Slack identity** | Requires a workspace user with a resolvable email before the connection starts or resumes a session. Guests, external Slack Connect users, and users without email stay blocked. The runtime resolves the email through `users.info`, so add `users:read` and `users:read.email` and reinstall the app first. |
> | **Enable Streaming** | Streams responses to Slack as the agent generates them. |
> | **Chunk Size (characters)** | The minimum characters Artemis buffers before each update. Lower values feel faster and make more Slack API calls. |
> | **Message template** | The authorization message the connection sends when a tool needs the user to authorize. Insert variables from the chips, select **See all variables** for the full list, and select **Show preview** to check it. |
>
> Select **Save Changes** to apply your changes.

> [tab] Deployment
>
> Choose which deployed version answers the channel.
>
> | Setting | Description |
> | - | - |
> | **Environment** | Under **Environment Binding**. Selects which deployed version handles incoming messages. |
> | **Active Deployment** | Shows the bound version and when someone deployed it. Check it when the agent behaves like an older build. |
>
> Select **Save Changes** after you switch the environment.

***

## Troubleshoot connection issues

Start with the **Sessions** check from [Verify the connection](#verify-the-connection), then match the symptom here.

| Symptom | Likely cause | Recommended action |
| - | - | - |
| Slack's challenge verification fails | The connection doesn't exist yet, the URL is wrong, or the Signing Secret doesn't match | Create the connection first, copy the Webhook URL from the connection's summary panel, and confirm the Signing Secret comes from the same Slack app. |
| **Add to Slack** fails before the Slack window opens | Artemis can't start the OAuth flow | Ask your platform administrator to confirm Artemis allows the request origin and the Slack app holds the exact OAuth Redirect URL. |
| Slack reports that the app needs approval | Your workspace restricts app installs | Ask a Workspace Owner or App Manager to approve the app, then run **Add to Slack** again. |
| You can't find the Team ID | You looked in the Slack app settings URL | Read the `T` segment from the workspace's `app.slack.com/client/` browser URL. The `api.slack.com/apps/` URL shows only the App ID. |
| The bot receives events but doesn't reply | Missing scope, inactive connection, or the bot isn't in the channel | Confirm the installed app has `chat:write`, the connection is **Active**, and someone invited the app to the channel. |
| Behavior doesn't change after you edit scopes or events | Slack hasn't applied the change | Save the Slack configuration and reinstall the app before you test again. |
| Users get blocked from starting a session | **Require verified Slack identity** is on | Confirm the user is a workspace member with an email, and that the app holds `users:read` and `users:read.email`. |

***

## Slack reference

Use these pages when you need detail beyond what this article covers.

| Resource | Use it for |
| - | - |
| [Your Apps](https://api.slack.com/apps) | Creating an app or returning to its settings. |
| [Using HTTP Request URLs](https://docs.slack.dev/apis/events-api/using-http-request-urls/) | How Slack delivers events to a Request URL. |
| [URL verification](https://docs.slack.dev/reference/events/url_verification) | The challenge Slack sends when you register a Request URL. |
| [Verifying requests from Slack](https://api.slack.com/authentication/verifying-requests-from-slack) | How the Signing Secret proves a request came from Slack. |
| [Scopes](https://api.slack.com/scopes) | What each bot token scope grants. |

***

**Related articles:**

* [Channels](https://koreai.mintlify.site/agent-platform/channels.md)
* [Set up Microsoft Teams](https://koreai.mintlify.site/agent-platform/channels/ms-teams-copilot)
* [Set up WhatsApp](https://koreai.mintlify.site/agent-platform/channels/whatsapp)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.