# Configure Slack

MOI connects to a Slack app through Socket Mode. Prepare the app's **App ID**, **App-Level Token**, and **Bot Token**. No public domain, callback URL, or tool instance is required.

Console menu locations can change. Use the current Slack interface to find the settings and credentials described below.

## 1. Create a Slack app

1. Open [Slack API Apps](https://api.slack.com/apps), create a blank app, and select the target workspace.
2. Record its **App ID**.

## 2. Enable Socket Mode and configure permissions

1. Enable **Socket Mode**. Create an **App-Level Token** with `connections:write`. This token starts with `xapp-`.
2. Enable **Event Subscriptions** and subscribe to the required **Bot Events**, such as `app_mention` and `message.im`.
3. Under **OAuth & Permissions → Bot Token Scopes**, add the scopes for your use cases below.
4. Install the app to the target workspace and obtain its **Bot Token**, which starts with `xoxb-`.

| Use case | Bot Token scope | Event subscription |
| --- | --- | --- |
| Receive direct messages | `im:history` | `message.im` |
| Receive messages mentioning the bot in a channel | `app_mentions:read` | `app_mention` |
| Send replies | `chat:write` | No additional event |
| Read files sent by users | `files:read` | The message event for the conversation |
| Send files generated by the agent | `files:write` | No additional event |

The App-Level Token's `connections:write` scope establishes the Socket Mode connection. The Bot Token still needs the corresponding scopes to receive messages and transfer files. See Slack's scope documentation[^slack-dm][^slack-mentions][^slack-files-read][^slack-files-write][^slack-chat].

After changing Bot Token scopes, follow Slack's prompts to reinstall and authorize the app. Update the tokens in MOI if they have changed.

## 3. Configure the connection in MOI

1. Open the target agent card's **⋯** menu and select **Two-way messaging**.
2. Select **Slack App / Bot**. If a receiving-method selector is shown, choose **Long-lived connection**.
3. Enter **App ID**, **App-Level Token**, and **Bot Token**. Both tokens are required for a new connection. When editing an existing connection, leave a token blank to keep its current value, or enter a new value and save to replace it.
4. Select a **Runtime model**.
5. Click **Save and continue** to start connecting.

## 4. Test the connection

1. In MOI, check for **Configuration saved** and **MOI receiving enabled**, then wait for **Connection established**.
2. Send the bot a direct message in Slack, or invite it to a test channel and mention it in a message.
3. Confirm **Real message received** in MOI, then confirm that the agent replies in the original Slack conversation or reply thread.

**Real message received** confirms incoming-message reception only. If no reply arrives, check the runtime model and the execution result in the corresponding MOI conversation. See [Connection status and troubleshooting](troubleshoot.md).

## Next steps

- [Use a connected agent](usage.md)
- [Connection status and troubleshooting](troubleshoot.md)

### References

[^slack-dm]: Slack. [message.im event](https://docs.slack.dev/reference/events/message.im/).
[^slack-mentions]: Slack. [app_mentions:read scope](https://docs.slack.dev/reference/scopes/app_mentions.read/).
[^slack-files-read]: Slack. [files:read scope](https://docs.slack.dev/reference/scopes/files.read/).
[^slack-files-write]: Slack. [files:write scope](https://docs.slack.dev/reference/scopes/files.write/).
[^slack-chat]: Slack. [chat:write scope](https://docs.slack.dev/reference/scopes/chat.write/).