diff --git a/apps/docs/content/docs/channels.mdx b/apps/docs/content/docs/channels.mdx index 7bc07a856..44906bbee 100644 --- a/apps/docs/content/docs/channels.mdx +++ b/apps/docs/content/docs/channels.mdx @@ -72,7 +72,7 @@ So adding a bot to a public channel is safe: only workspace members who have bou -**Slack — bring your own app.** A workspace admin creates a Slack app, installs it to their Slack workspace, and pastes its bot token + app-level token into Multica. Each agent gets its own Slack app, so several agents can each have a distinct bot in one Slack workspace. See [Slack Bot integration](/slack-bot-integration) and [Create a Slack app](/create-slack-app). +**Slack — bring your own app.** A workspace admin creates a Slack app, installs it to their Slack workspace, and pastes its bot token + app-level token into Multica. Each agent gets its own Slack app, so several agents can each have a distinct bot in one Slack workspace. See [Slack Bot integration](/slack-bot-integration) for the manifest and step-by-step setup. ## Self-host @@ -89,6 +89,5 @@ On Multica Cloud both are already configured. See [Environment variables](/envir ## Next - [Lark Bot integration](/lark-bot-integration) — scan-to-install, DM / @-mention / `/issue` -- [Slack Bot integration](/slack-bot-integration) — bring-your-own-app, per-agent bots -- [Create a Slack app](/create-slack-app) — the step-by-step app + token setup +- [Slack Bot integration](/slack-bot-integration) — bring-your-own-app setup (manifest + tokens), per-agent bots - [Agents](/agents) · [Chat](/chat) · [Tasks](/tasks) diff --git a/apps/docs/content/docs/create-slack-app.mdx b/apps/docs/content/docs/create-slack-app.mdx deleted file mode 100644 index c9b31fec7..000000000 --- a/apps/docs/content/docs/create-slack-app.mdx +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: Create a Slack app -description: Step-by-step — create a Slack app from a manifest, install it to your workspace, and grab the bot token and app-level token to connect it to a Multica agent. ---- - -import { Callout } from "fumadocs-ui/components/callout"; - -Multica's [Slack integration](/slack-bot-integration) is **bring-your-own-app**: you create a Slack app, install it to your Slack workspace, and paste two tokens into Multica. This page walks through that one-time setup. It takes about five minutes and needs no public URL. - -At the end you'll have two values to paste into the agent's **Connect Slack** dialog: - -- a **Bot token** — starts with `xoxb-` -- an **App-level token** — starts with `xapp-` - -## 1. Create the app from a manifest - -1. Go to [https://api.slack.com/apps](https://api.slack.com/apps) and click **Create New App**. -2. Choose **From a manifest**. -3. Pick the Slack workspace to install the app into. -4. Paste the manifest below (the **YAML** tab), review, and create the app. - -```yaml -display_information: - name: Multica -features: - app_home: - messages_tab_enabled: true - messages_tab_read_only_enabled: false - bot_user: - display_name: Multica - always_online: true -oauth_config: - scopes: - bot: - - app_mentions:read - - channels:history - - chat:write - - groups:history - - im:history - - mpim:history - - users:read -settings: - event_subscriptions: - bot_events: - - app_mention - - message.im - - message.channels - - message.groups - - message.mpim - interactivity: - is_enabled: false - socket_mode_enabled: true - org_deploy_enabled: false - token_rotation_enabled: false -``` - -The manifest already configures everything Multica needs — bot scopes, event subscriptions, Socket Mode, and the Messages tab — so you don't have to set them by hand. There is **no OAuth redirect URL** because BYO doesn't use OAuth. - - -Want the bot to show up under a specific name in Slack? Change `display_information.name` and `features.bot_user.display_name` (e.g. to your agent's name) before creating, or edit it later under **App Home**. Slack shows the bot by its **bot display name**, which can differ from the app name. - - - -Keep `users:read` in the scopes. Multica calls `bots.info` to verify the bot token and app-level token belong to the same app, and that call needs `users:read`. Without it, **Connect** fails. - - -## 2. Install the app and copy the Bot token - -1. In the app's left nav, open **Install App** (or **OAuth & Permissions**). -2. Click **Install to Workspace** and approve. -3. Copy the **Bot User OAuth Token** — it starts with `xoxb-`. This is your **Bot token**. - -## 3. Create the App-level token - -The app-level token authorizes the Socket Mode connection and can only be created in the console (it isn't available over OAuth). - -1. Open **Basic Information → App-Level Tokens**, click **Generate Token and Scopes**. -2. Give it any name. -3. Click **Add Scope** and select **`connections:write`** (it's a picker — select it from the list, don't type it). -4. Click **Generate**, then copy the token — it starts with `xapp-`. This is your **App-level token**. - -## 4. Connect it in Multica - -1. In Multica, open the agent → **Integrations** tab → **Connect Slack**. -2. Paste the **Bot token** (`xoxb-`) and the **App-level token** (`xapp-`). -3. Click **Connect**. - -That's it. Now use the bot: `/invite @your-bot` into a channel and `@`-mention it, or DM it from the Slack sidebar's **Apps** section. See [Slack Bot integration](/slack-bot-integration) for usage and `/issue`. - - -Doing this for **multiple agents**? Repeat the whole flow once per agent — each agent gets its own Slack app and its own pair of tokens, and they appear as separate bots in your workspace. - - -## Next - -- [Slack Bot integration](/slack-bot-integration) — connect, use, and manage the bot -- [Chat integrations](/channels) — how the channel engine works diff --git a/apps/docs/content/docs/meta.json b/apps/docs/content/docs/meta.json index 880800835..d571c70f9 100644 --- a/apps/docs/content/docs/meta.json +++ b/apps/docs/content/docs/meta.json @@ -34,7 +34,6 @@ "github-integration", "lark-bot-integration", "slack-bot-integration", - "create-slack-app", "---Self-hosting & ops---", "environment-variables", "auth-setup", diff --git a/apps/docs/content/docs/slack-bot-integration.mdx b/apps/docs/content/docs/slack-bot-integration.mdx index b42339ca1..309736dcc 100644 --- a/apps/docs/content/docs/slack-bot-integration.mdx +++ b/apps/docs/content/docs/slack-bot-integration.mdx @@ -1,6 +1,6 @@ --- title: Slack Bot integration -description: Connect a Multica agent to your own Slack app, then talk to it from a DM or channel — @-mention it, chat naturally, or type /issue to file a Multica issue without leaving Slack. +description: Connect a Multica agent to your own Slack app — create the app from a manifest, install it, paste the bot + app-level tokens, then @-mention it, DM it, or type /issue from inside Slack. --- import { Callout } from "fumadocs-ui/components/callout"; @@ -9,56 +9,135 @@ Connect any [agent](/agents) to a Slack bot and your team can work with it from Slack uses a **bring-your-own-app (BYO)** model: a workspace admin creates a Slack app, installs it to their Slack workspace, and pastes its tokens into Multica. Each agent gets **its own** Slack app — so several agents can each have a distinct, separately @-mentionable bot in the same Slack workspace. (This differs from [Lark](/lark-bot-integration), where binding is a scan-to-install flow.) +The whole setup is below and takes about five minutes. You'll end up with two tokens to paste into Multica: + +- a **Bot token** — starts with `xoxb-` +- an **App-level token** — starts with `xapp-` + +## Set up your Slack app + +### 1. Create the app from a manifest + +1. Go to [https://api.slack.com/apps](https://api.slack.com/apps) and click **Create New App**. +2. Choose **From a manifest**. +3. Pick the Slack workspace to install the app into. +4. Switch to the **YAML** tab, paste the manifest below, review, and create the app. + +```yaml +display_information: + name: Multica +features: + app_home: + home_tab_enabled: false + messages_tab_enabled: true + messages_tab_read_only_enabled: false + bot_user: + display_name: Multica + always_online: true +oauth_config: + scopes: + bot: + - app_mentions:read + - channels:history + - groups:history + - im:history + - mpim:history + - chat:write + - users:read +settings: + event_subscriptions: + bot_events: + - app_mention + - message.im + - message.channels + - message.groups + - message.mpim + interactivity: + is_enabled: false + org_deploy_enabled: false + socket_mode_enabled: true + token_rotation_enabled: false +``` + +This manifest configures everything Multica needs, so you don't set anything by hand: + +| Section | Why it's there | +|---|---| +| `app_home.messages_tab_enabled: true` | Lets members open the bot and **DM** it. Without it, the bot can't be messaged directly. | +| `bot_user` | Creates the bot identity that gets @-mentioned and posts replies. | +| `chat:write` | Post the agent's replies back into Slack. | +| `app_mentions:read` + `app_mention` event | Receive @-mentions in channels. | +| `im:history` + `message.im` | Receive **DMs** to the bot (every DM message is read). | +| `channels:history` / `groups:history` / `mpim:history` + the matching `message.*` events | Receive messages in public channels, private channels, and group DMs. In these, the bot only acts on messages that **@-mention** it. | +| `users:read` | Required so Multica can verify (via `bots.info`) that your two tokens belong to the same app. | +| `socket_mode_enabled: true` | The bot connects out over Socket Mode — **no public URL / request URL needed**. | +| `interactivity.is_enabled: false` | Multica's prompts are plain links, not buttons, so interactivity isn't needed. | + +There is **no OAuth redirect URL**, because BYO doesn't use OAuth. + + +Keep `users:read` in the scopes. At connect time Multica calls `bots.info` to confirm the bot token and app-level token come from the **same** app — that call needs `users:read`. Without it, **Connect** fails. + + -First time setting one up? Follow [Create a Slack app](/create-slack-app) to get the two tokens, then come back here to paste them. +Want a specific name in Slack? Change `display_information.name` and `features.bot_user.display_name` (e.g. to your agent's name) before creating, or edit it later under **App Home**. Slack shows the bot by its **bot display name**, which can differ from the app name. + + +### 2. Install the app and copy the Bot token + +1. In the app's left nav, open **Install App** (or **OAuth & Permissions**). +2. Click **Install to Workspace** and approve. +3. Copy the **Bot User OAuth Token** — it starts with `xoxb-`. This is your **Bot token**. + +### 3. Create the App-level token + +The app-level token authorizes the Socket Mode connection. It can only be created in the console (it isn't part of OAuth). + +1. Open **Basic Information → App-Level Tokens** and click **Generate Token and Scopes**. +2. Give it any name. +3. Click **Add Scope** and pick **`connections:write`** from the list (it's a picker — select it, don't type it). +4. Click **Generate**, then copy the token — it starts with `xapp-`. This is your **App-level token**. + +### 4. Connect it in Multica + +1. Open the agent in **Agents → _your agent_** → the **Integrations** tab (or the **Integrations** section in the left sidebar). +2. Click **Connect Slack**. +3. Paste the **Bot token** (`xoxb-`) and the **App-level token** (`xapp-`), then click **Connect**. +4. The agent shows **Connected to Slack**. The bot is now listening over its own Socket Mode connection. + + +The two tokens must be from the **same** Slack app, and that app maps to exactly **one** agent. Connecting an app that's already connected to a different agent or workspace is refused. To move an app to another agent, disconnect it first; re-connecting an agent with a **new** app updates that agent's bot in place. + + + +Setting this up for **multiple agents**? Repeat the whole flow once per agent — each agent gets its own Slack app and its own pair of tokens, and they show up as separate bots in your Slack workspace. ## What the integration does | Surface | Behavior | |---|---| -| **Agent → Integrations** | The agent detail page has an **Integrations** tab (and a matching section in the left sidebar). Owners and admins see **Connect Slack** there; once connected it flips to a **Connected to Slack** badge with a **Disconnect** control. | -| **DM the bot** | A workspace member messages the bot directly in Slack. The conversation becomes a Multica [chat](/chat) session with the agent. | -| **@-mention in a channel** | Invite the bot to a channel (`/invite @your-bot`) and @-mention it. Only the mentioning message is read — the bot does not listen to the whole channel. Each @bot thread is its own session. | -| **`/issue` command** | Starting a message with `/issue ` (optionally with a body) creates a new Multica issue in the workspace, attributed to you. | +| **Agent → Integrations** | Owners and admins see **Connect Slack**; once connected it flips to a **Connected to Slack** badge with a **Disconnect** control. | +| **DM the bot** | A workspace member messages the bot directly. The conversation becomes a Multica [chat](/chat) session with the agent; every DM message is read. | +| **@-mention in a channel** | Invite the bot (`/invite @your-bot`) and @-mention it. Only the mentioning message is read — the bot does not listen to the whole channel. Each @bot **thread** is its own session. | +| **`/issue` command** | Starting a message with `/issue <title>` (optionally with a body on the next lines) creates a new Multica issue in the workspace, attributed to you. | | **Reply** | The agent's answer is posted back into the same DM or thread. | -## Connect an agent (owner / admin) - -You need a Slack app's **bot token** (`xoxb-`) and **app-level token** (`xapp-`) — create them with [Create a Slack app](/create-slack-app). - -1. Open the agent in **Agents → _your agent_**. -2. Go to the **Integrations** tab (or the **Integrations** section in the left sidebar) and click **Connect Slack**. -3. In the dialog, paste the **Bot token** (`xoxb-`) and the **App-level token** (`xapp-`), then click **Connect**. -4. The agent shows **Connected to Slack**. The bot is now listening over its own Socket Mode connection. - -<Callout type="warning"> -The two tokens must come from the **same** Slack app — Multica verifies this at connect time (using the `users:read` scope via `bots.info`). If your app is missing `users:read`, or the tokens are from different apps, the connect is rejected. The required scopes are listed in [Create a Slack app](/create-slack-app). -</Callout> - -### One bot per agent - -Each Slack app maps to exactly one agent. Connecting an app that's already connected to a different agent or workspace is refused. To move an app to a different agent, disconnect it first. Re-connecting an agent with a **new** app (for example after disconnecting) updates that agent's bot in place. - ## Use the bot (members) -### First message: bind your Slack identity +### First message: link your account -The first time you @-mention or DM the bot, it replies asking you to **link your account** — tap the link, sign in to Multica, and your Slack identity is bound to your Multica membership. This is what lets the agent act as you (for example, `/issue` files the issue under your name). +The first time you @-mention or DM the bot, it replies with a **link your account** prompt. Tap the link, sign in to Multica, and your Slack identity is bound to your Multica membership — this is what lets the agent act as you (e.g. `/issue` files under your name). The link is single-use and expires in about 15 minutes; just message the bot again for a fresh one. <Callout type="warning"> -Only people who are **members of the workspace** can use the bot. If you aren't a member, or you skip the identity bind, the bot won't run — your message is dropped (recorded for audit, without its contents). +Only **members of the workspace** can use the bot. If you aren't a member, or you skip the identity link, the bot won't run — your message is dropped (recorded for audit, without its contents). </Callout> ### Chat and `/issue` -- **In a channel** — the bot is not auto-joined. Run `/invite @your-bot` once, then `@your-bot <your message>`. -- **In a DM** — open the bot from the Slack sidebar's **Apps** section and message it directly. -- **File an issue** — send `/issue Fix the login redirect` and Multica creates that issue in the workspace. Add more lines after the title for a description. - -<Callout type="info"> -The bot shows under its **bot display name** (set in the Slack app's App Home), which may differ from the app name. Look for that name when inviting or DMing it. -</Callout> +- **In a channel** — the bot isn't auto-joined. Run `/invite @your-bot` once, then `@your-bot <your message>`. Re-mention it for each follow-up (the bot only reads messages that mention it). +- **In a DM** — open the bot from the Slack sidebar's **Apps** section and message it directly; no mention needed. +- **File an issue** — send `/issue Fix the login redirect`; add more lines after the title for a description. ## Manage and disconnect @@ -70,14 +149,14 @@ Workspace-wide management lives in **Settings → Integrations**: ## Permissions - **Connect / disconnect** require workspace **owner** or **admin**. -- **Talking to the bot** requires being a workspace member with a bound Slack identity. Everyone else is dropped. +- **Talking to the bot** requires being a workspace member with a linked Slack identity. Everyone else is dropped. - Message bodies for dropped messages are never stored — only a drop reason, for audit. ## Self-host setup On Multica Cloud the integration is already available — skip this section. -For self-host, Slack is **off until you set an at-rest encryption key**. The key encrypts each app's bot + app-level tokens before they touch the database. Unlike a hosted-OAuth integration, BYO needs **no** OAuth client id/secret and **no** deployment-level app token — each installation uses the tokens the admin pastes. +For self-host, Slack is **off until you set an at-rest encryption key**. The key encrypts each app's bot + app-level tokens before they touch the database. BYO needs **no** OAuth client id/secret and **no** deployment-level app token — each installation uses the tokens the admin pastes. 1. Generate a 32-byte key and set it on the API server: @@ -90,12 +169,11 @@ For self-host, Slack is **off until you set an at-rest encryption key**. The key 2. Restart the API. Until the key is set, **Settings → Integrations** shows a "Slack integration not enabled" notice and the **Connect Slack** entry points stay hidden. <Callout type="info"> -The key must decode to exactly 32 bytes — generate it with `openssl rand -base64 32`. Treat it as a long-lived secret: rotating or losing it makes already-stored tokens undecryptable, forcing every bot to reconnect. +The key must decode to exactly 32 bytes — `openssl rand -base64 32` does this. Treat it as a long-lived secret: rotating or losing it makes already-stored tokens undecryptable, forcing every bot to reconnect. The bind link also needs `MULTICA_PUBLIC_URL` set (it's the base of the "link your account" URL). </Callout> ## Next -- [Create a Slack app](/create-slack-app) — get the bot + app-level tokens - [Chat integrations](/channels) — how the channel engine, sessions, and authorization work - [Agents](/agents) · [Chat](/chat) · [Issues](/issues) - [Environment variables](/environment-variables) — full self-host configuration reference