Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

docs: collaboration bridge setup guides (Slack, Mattermost, Teams, Discord) (CHOO-1589) (#55)

Christian McDermott2cf8eaf8af39
diff --git a/core/switch_core/bridges/collaboration/teams/README.md b/core/switch_core/bridges/collaboration/teams/README.md
index a8ec3fa7a..e1cbba191 100644
--- a/core/switch_core/bridges/collaboration/teams/README.md
+++ b/core/switch_core/bridges/collaboration/teams/README.md
@@ -6,6 +6,11 @@ architecture, the ops prerequisites, and the per-bridge configuration. A Teams
workspace is connected **per bridge through the gateway** — all credentials live
in the bridge's stored `connection_config`, never in global/env config.
+> For the operator-facing **setup walkthrough** (Azure prerequisites, onboarding
+> request, and how Teams fits alongside the other bridges), see
+> [`docs/bridges/TEAMS_SETUP.md`](../../../../../docs/bridges/TEAMS_SETUP.md).
+> This note focuses on the adapter's internal architecture.
+
## Architecture
Teams has no persistent bot socket (unlike Slack Socket Mode / Mattermost
diff --git a/docs/bridges/DISCORD_SETUP.md b/docs/bridges/DISCORD_SETUP.md
new file mode 100644
index 000000000..15f87a745
--- /dev/null
+++ b/docs/bridges/DISCORD_SETUP.md
@@ -0,0 +1,109 @@
+# Discord collaboration bridge setup
+
+Connects a Discord server (**guild**) to Switch. A **single bot application**
+backs every Switch agent; per-agent presentation is done with **per-channel
+webhooks** (Discord webhooks accept a per-message username and avatar). Inbound
+events arrive over an outbound **Gateway WebSocket** scoped to the configured
+guild, so **no public ingress is required**; outbound goes through the REST API.
+
+Rooms are provisioned **lazily**: Discord has no "app invited to channel" signal
+(the bot sees every channel its permissions allow), so a channel's Switch room is
+created on the first bridged message rather than eagerly for the whole guild.
+
+## Prerequisites
+
+- A Discord server (guild) where you can add a bot and manage channels.
+- The Switch gateway reachable by an admin to onboard the bridge.
+
+## 1. Create the Discord application + bot
+
+1. Go to the [Discord Developer Portal](https://discord.com/developers/applications)
+ → **New Application**. Name it (e.g. "Agent Switch").
+2. Open the **Bot** tab. The bot is created with the app; copy its **token** —
+ this is the `bot_token`. (Reset the token if you need a fresh one.)
+
+## 2. Enable privileged gateway intents
+
+The adapter requests these gateway intents: `guilds`, `guild_messages`,
+`dm_messages`, `message_content`, `members`. Two of these are **privileged** and
+must be toggled on under **Bot → Privileged Gateway Intents**:
+
+- **Message Content Intent** — required to read message text.
+- **Server Members Intent** — required for member lookups and per-channel
+ membership grants.
+
+(For a bot in 100+ servers these require Discord verification; a
+single-workspace deployment does not.)
+
+## 3. Invite the bot with the right permissions
+
+Build an OAuth2 invite URL (Developer Portal → **OAuth2 → URL Generator**):
+
+- **Scopes:** `bot`.
+- **Bot permissions** (matching what the adapter does):
+ - **View Channels** — see the guild's channels.
+ - **Send Messages** + **Send Messages in Threads** — post agent replies.
+ - **Manage Webhooks** — mint the per-channel webhook agents post through.
+ - **Manage Channels** / **Manage Roles** — set per-member channel permission
+ overwrites (`channel.set_permissions`) when provisioning access.
+ - **Read Message History** — thread-aware replies.
+ - **Attach Files** — relay agent image attachments.
+
+Open the generated URL and add the bot to your server.
+
+## 4. Get the guild id
+
+Enable **Developer Mode** in Discord (User Settings → Advanced), then right-click
+the server icon → **Copy Server ID**. This is the `guild_id`.
+
+## 5. Onboard the bridge in Switch
+
+As a gateway admin, onboard the bridge from the **operator dashboard**:
+**Messaging Apps → Add bridge → Discord**, give it a display name (e.g. "Acme
+Discord"), and fill in the fields below.
+
+Fields (`DiscordConnectionConfig`):
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `bot_token` | yes | Bot token from the Developer Portal. |
+| `guild_id` | yes | The Discord server (guild) id the bridge is scoped to. |
+
+On success the bridge opens its Gateway WebSocket to that guild. Post in a
+channel the bot can see (or have an agent post) and the Switch room is created on
+the first bridged message.
+
+## Clickable "Open in SwitchDash" links (`GATEWAY_PUBLIC_URL`)
+
+Discord only linkifies `http(s)`, so a raw `switchdash://session?…` deeplink
+renders as plain text. Set **`GATEWAY_PUBLIC_URL`** on switch-core to the Switch
+API's public origin — scheme + host only, **no path** — the same host SwitchDash
+reports as its `server` (distinct from the operator UI):
+
+```dotenv
+# .env / deployment env
+GATEWAY_PUBLIC_URL=https://switch-api.acme.com
+```
+
+When set, Switch rewrites the deeplink to a clickable
+`https://<switch-api-host>/deeplink/session?…` redirect (a `302` back to the
+`switchdash://` scheme) at runtime-state ingestion — so both the bridged
+working/awaiting-input status message **and** the `!status` command surface a
+clickable link, on every platform at once. When unset, the raw `switchdash://`
+link is posted as before (disclosed fallback).
+
+The value is validated at startup: it must be scheme + host only. A URL carrying
+a path is rejected, because the redirect is served at `/deeplink/session` on the
+API root (the agent-bridge app, **not** under the `/gateway` mount) and a path
+prefix would build links that 404. Front `GATEWAY_PUBLIC_URL` with a proxy that
+routes the API root, not only `/gateway/*`.
+
+## Notes
+
+- **Room icon.** SwitchDash shows a Discord icon for Discord-channel rooms
+ (`discord.svg`, keyed to `bridge_type` `"discord"`).
+- **Outbound images.** Agents can relay images into Discord — the adapter
+ uploads the bytes through the channel webhook under the agent's username/avatar
+ (with the caption as the message). HTTP failures fall back to a disclosed text
+ notice so nothing is silently dropped.
+- **DMs.** In a DM channel the file posts as the bot with the agent name inlined.
diff --git a/docs/bridges/MATTERMOST_SETUP.md b/docs/bridges/MATTERMOST_SETUP.md
new file mode 100644
index 000000000..f542d9359
--- /dev/null
+++ b/docs/bridges/MATTERMOST_SETUP.md
@@ -0,0 +1,72 @@
+# Mattermost collaboration bridge setup
+
+Connects a Mattermost server to Switch. Unlike the single-bot platforms,
+Mattermost uses **one bot account per Switch agent**, created and driven through
+an **admin account** you supply. Inbound messages arrive over Mattermost's
+WebSocket (an outbound connection from Switch), so **no public ingress is
+required**.
+
+## Prerequisites
+
+- A Mattermost server reachable from switch-core.
+- An **admin** account on that server (username + password) — the bridge uses it
+ to create per-agent bot accounts, channels, and memberships.
+- A **team** on the server that bridged channels live in.
+- The Switch gateway reachable by an admin to onboard the bridge.
+
+## 1. Prepare the Mattermost server
+
+1. Ensure **bot accounts** are enabled (System Console → Integrations → Bot
+ Accounts → *Enable Bot Account Creation*).
+2. Have (or create) the **admin** user the bridge will authenticate as, and the
+ **team** (its URL name / slug) that channels will be created under.
+3. Make sure the admin can create channels and manage members on that team.
+
+## 2. Onboard the bridge in Switch
+
+As a gateway admin, onboard the bridge from the **operator dashboard**:
+**Messaging Apps → Add bridge → Mattermost**, give it a display name (e.g. "Acme
+Mattermost"), and fill in the fields below.
+
+Fields (`MattermostConnectionConfig`):
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `url` | yes | Base URL switch-core connects to (may be an internal/tailnet address). |
+| `admin_user` | yes | Admin username the bridge authenticates as. |
+| `admin_password` | yes | Admin password. |
+| `team_name` | yes | Team slug that bridged channels are created under. |
+| `public_url` | no | User-facing base URL when it differs from `url`; used for channel deeplinks so they open in the user's client. Falls back to `url`. |
+
+On success the bridge logs in as the admin, resolves the team, and starts its
+WebSocket. Per-agent bot accounts are created as agents are used.
+
+## Local development
+
+The local stack (`just up` / `just standalone-up`) runs a **Mattermost server in
+Docker** and **auto-registers a Mattermost bridge** for you via
+`deploy/shared_resources/setup.py`. It reads these values from `.env`:
+
+```dotenv
+MATTERMOST_HOST_PORT=8065
+MATTERMOST_ADMIN_USER=admin
+MATTERMOST_ADMIN_PASSWORD=admin1234
+MATTERMOST_TEAM_NAME=switch
+MATTERMOST_USER=user
+MATTERMOST_USER_PASSWORD=user1234
+```
+
+The seeder creates the admin user + team, then registers the bridge with
+`connection_config = { url, admin_user, admin_password, team_name }` (adding
+`public_url` only if a public URL is configured). So for local dev you normally
+don't onboard Mattermost by hand — it's already there after setup. Log in at
+`http://localhost:8065` with the `MATTERMOST_USER` credentials to try it.
+
+## Notes
+
+- **Identity.** Each agent gets its own Mattermost bot account, so agent messages
+ appear as distinct users (not a single relayed bot).
+- **DMs.** Switch-initiated DM rooms are user-initiated on Mattermost — a user
+ starts the DM with the agent's bot and Switch picks it up.
+- **Deeplinks.** Set `GATEWAY_PUBLIC_URL` on switch-core for clickable "Open in
+ SwitchDash" links (see the [index](README.md#deployment-knobs)).
diff --git a/docs/bridges/README.md b/docs/bridges/README.md
new file mode 100644
index 000000000..8068eaa0c
--- /dev/null
+++ b/docs/bridges/README.md
@@ -0,0 +1,70 @@
+# Collaboration bridge setup
+
+A **collaboration bridge** is a two-way relay between an external chat platform
+(Slack, Mattermost, Microsoft Teams, Discord) and Switch's internal Matrix
+rooms. Humans talk in their normal chat client; Switch agents see those messages
+as room events and reply back into the same channel. Each external channel maps
+to a Switch room, and each Switch agent is presented in the channel under its own
+name and avatar.
+
+This directory documents how to set up each bridge. Read this page first for the
+shared onboarding model, then the per-platform guide:
+
+| Platform | Guide | Identity model | Inbound transport | Public ingress |
+| --- | --- | --- | --- | --- |
+| Slack | [`SLACK_SETUP.md`](SLACK_SETUP.md) | single bot app | Socket Mode (outbound WS) | not required |
+| Mattermost | [`MATTERMOST_SETUP.md`](MATTERMOST_SETUP.md) | one bot account per agent | WebSocket (outbound) | not required |
+| Microsoft Teams | [`TEAMS_SETUP.md`](TEAMS_SETUP.md) | single Azure bot app | HTTP push (Bot Framework + Graph) | **required** |
+| Discord | [`DISCORD_SETUP.md`](DISCORD_SETUP.md) | single bot app | Gateway WebSocket (outbound) | not required |
+
+## The onboarding model (same for every bridge)
+
+A bridge is an **unowned, workspace-wide integration** that holds platform
+credentials. Registering one is therefore an **admin-only** action. All
+credentials live per-bridge in the bridge's stored `connection_config` (a JSONB
+column) — **never** in global environment/config. Onboarding one platform never
+touches another.
+
+Onboard a bridge from the **operator dashboard**: **Messaging Apps → Add
+bridge**, pick the platform, and fill in the form. The form is rendered from the
+bridge type's config schema, so it always asks for exactly the fields that type
+needs — the per-platform guides below describe those fields in prose so you know
+what to gather beforehand.
+
+On save the bridge is created, its platform client starts, and identities are
+provisioned lazily as channels are used. The dashboard also lists existing
+bridges and lets you edit or remove them.
+
+### Registered bridge types
+
+`slack`, `mattermost`, `teams`, `discord`. The dashboard's Add-bridge form lists
+the live set and the fields each one requires.
+
+## Once a bridge is live
+
+- **Rooms.** Depending on the platform, a Switch room is created for a channel
+ either when the bot is added to it (Slack, Mattermost, Teams) or lazily on the
+ first bridged message (Discord — it has no "app added to channel" signal).
+ Existing Switch rooms can also be bound to a channel at room-creation time.
+- **Addressing agents.** Users `@mention` an agent by name in the channel to
+ address it; unaddressed chatter is bridged as context. Bridge in-room commands
+ (e.g. `!invite-agent`) and slash commands work per platform.
+- **"Open in SwitchDash" links.** Agents surface a `switchdash://…` deeplink with
+ their runtime status. Platforms that only linkify `http(s)` (notably Discord)
+ need `GATEWAY_PUBLIC_URL` set so Switch can rewrite it to a clickable
+ `https://<switch-api-host>/deeplink/session?…` redirect. See the Discord guide.
+
+## Deployment knobs
+
+Most bridge configuration is per-bridge (in `connection_config`). A few things
+are deployment-level environment config on switch-core:
+
+- **`GATEWAY_PUBLIC_URL`** — the Switch API's public origin (scheme + host only,
+ no path): the same host SwitchDash reports as its `server`, and distinct from
+ the operator UI. Used to build the clickable deeplink redirect, which is served
+ at `/deeplink/session` on the API root (the agent-bridge app), **not** under the
+ `/gateway` mount — so front it with a proxy that routes the API root, not only
+ `/gateway/*`. Leave unset to post the raw `switchdash://` deeplink (the
+ disclosed fallback). Applies to every platform but matters most for Discord.
+- **Teams** additionally needs public HTTPS ingress to the bridge's listener —
+ see [`TEAMS_SETUP.md`](TEAMS_SETUP.md).
diff --git a/docs/bridges/SLACK_SETUP.md b/docs/bridges/SLACK_SETUP.md
new file mode 100644
index 000000000..c2a9228e6
--- /dev/null
+++ b/docs/bridges/SLACK_SETUP.md
@@ -0,0 +1,209 @@
+# Slack collaboration bridge setup
+
+Connects a Slack workspace to Switch. A **single Slack app** (one bot) backs
+every Switch agent; per-agent presentation is done with per-message username +
+avatar overrides. Inbound events arrive over **Socket Mode** — an outbound
+WebSocket the bot opens to Slack — so **no public ingress is required**. Outbound
+messages go through the Slack Web API.
+
+## Prerequisites
+
+- A Slack workspace where you can install a custom app (workspace admin approval
+ may be required).
+- The Switch gateway reachable by an admin to onboard the bridge.
+
+## 1. Create the Slack app
+
+You need one Slack app for the whole bridge. There are two ways to create it —
+**the manifest path is strongly recommended**, it is far less error-prone.
+
+### Recommended: from an app manifest
+
+1. Go to <https://api.slack.com/apps> → **Create New App** → **From an app
+ manifest**.
+2. Select the target workspace.
+3. Paste the manifest below and create the app. It pre-configures the bot token
+ scopes, all of Switch's `/…` slash commands, Socket Mode, event subscriptions,
+ interactivity, and the app home in one step — so you can skip the manual scope
+ and event setup entirely.
+
+<details>
+<summary><strong>Agent Switch app manifest</strong> (paste this)</summary>
+
+```json
+{
+ "display_information": {
+ "name": "Agent Switch"
+ },
+ "features": {
+ "app_home": {
+ "home_tab_enabled": true,
+ "messages_tab_enabled": false,
+ "messages_tab_read_only_enabled": false
+ },
+ "bot_user": {
+ "display_name": "Agent Switch",
+ "always_online": false
+ },
+ "slash_commands": [
+ { "command": "/admin", "description": "Toggle admin mode on/off for this room", "should_escape": false },
+ { "command": "/help", "description": "Show the list of available in-room commands", "should_escape": false },
+ { "command": "/reset", "description": "Reset a targeted agent's session (clears context, then reconnects)", "usage_hint": "@agent-name | @role (required)", "should_escape": true },
+ { "command": "/reset-all-agents", "description": "Reset EVERY agent's session in this room", "should_escape": false },
+ { "command": "/compact", "description": "Compact a targeted agent's session context", "usage_hint": "@agent-name | @role (required)", "should_escape": true },
+ { "command": "/compact-all-agents", "description": "Compact EVERY agent's session context in this room", "should_escape": false },
+ { "command": "/interrupt", "description": "Interrupt a targeted agent's current turn", "usage_hint": "@agent-name | @role (required)", "should_escape": true },
+ { "command": "/interrupt-all-agents", "description": "Interrupt EVERY agent's current turn in this room", "should_escape": false },
+ { "command": "/agents-status", "description": "Show each agent's presence and capabilities in this room", "should_escape": false },
+ { "command": "/roles", "description": "List this room's roles and who currently holds each", "should_escape": false },
+ { "command": "/list-agents", "description": "List the agents available in this room", "should_escape": false },
+ { "command": "/list-switch-agents", "description": "List all agents registered on the Switch", "should_escape": false },
+ { "command": "/list-documents", "description": "List the room's internal documents", "should_escape": false },
+ { "command": "/list-references", "description": "List the room's references", "should_escape": false },
+ { "command": "/list-aliases", "description": "List per-room agent aliases (@alias to agent)", "should_escape": false },
+ { "command": "/set-alias", "description": "Give an agent a room alias", "usage_hint": "@agent-name @alias", "should_escape": true },
+ { "command": "/remove-alias", "description": "Remove a room alias", "usage_hint": "@alias (or @agent-name)", "should_escape": true },
+ { "command": "/invite-agent", "description": "Add an existing agent to this room", "usage_hint": "@agent-name", "should_escape": true },
+ { "command": "/run-cmd", "description": "Show the terminal command to start a session for an agent", "usage_hint": "@agent-name [@role]", "should_escape": true },
+ { "command": "/agents-greet", "description": "Have agents in the room introduce themselves", "should_escape": false },
+ { "command": "/room-url", "description": "Show the frontend URL for this room", "should_escape": false }
+ ]
+ },
+ "oauth_config": {
+ "scopes": {
+ "bot": [
+ "files:read",
+ "files:write",
+ "assistant:write",
+ "channels:history",
+ "channels:manage",
+ "channels:read",
+ "chat:write",
+ "chat:write.customize",
+ "commands",
+ "groups:history",
+ "groups:read",
+ "groups:write",
+ "im:history",
+ "im:read",
+ "im:write",
+ "mpim:history",
+ "reactions:read",
+ "reactions:write",
+ "users:read"
+ ]
+ },
+ "pkce_enabled": false
+ },
+ "settings": {
+ "event_subscriptions": {
+ "bot_events": [
+ "message.channels",
+ "message.groups",
+ "message.im",
+ "message.mpim"
+ ]
+ },
+ "interactivity": {
+ "is_enabled": true
+ },
+ "org_deploy_enabled": false,
+ "socket_mode_enabled": true,
+ "token_rotation_enabled": false,
+ "is_mcp_enabled": false
+ }
+}
+```
+
+</details>
+
+Then continue with [Generate tokens and install](#2-generate-tokens-and-install).
+
+### Alternative: from scratch (manual)
+
+1. **Create New App → From scratch**, name it (e.g. "Agent Switch"), and pick the
+ workspace.
+2. Configure the **bot token scopes**, **event subscriptions**, **slash
+ commands**, and enable **Socket Mode** + **interactivity** by hand — see the
+ [App configuration reference](#app-configuration-reference) below for the exact
+ values (they mirror the manifest).
+
+## 2. Generate tokens and install
+
+Regardless of how you created the app:
+
+1. **App-level token (Socket Mode).** Under **Basic Information → App-Level
+ Tokens**, generate a token with the `connections:write` scope — this is the
+ `app_token` (`xapp-…`). (Socket Mode is already enabled by the manifest; on the
+ from-scratch path, enable it under **Settings → Socket Mode** first.)
+2. **Install to workspace.** **Install App** → copy the **Bot User OAuth Token**
+ (`xoxb-…`) — this is the `bot_token`.
+3. **Workspace id.** Note the workspace/team id (`T…`) — this is `workspace_id`
+ (Workspace → Settings, or from any message link).
+4. **Invite the app** to the channels you want bridged (`/invite @Agent Switch`).
+ The bridge provisions a Switch room when the app joins a channel.
+
+## 3. Onboard the bridge in Switch
+
+As a gateway admin, onboard the bridge from the **operator dashboard**:
+**Messaging Apps → Add bridge → Slack**, give it a display name (e.g. "Acme
+Slack"), and fill in the fields below.
+
+Fields (`SlackConnectionConfig`):
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `bot_token` | yes | Bot User OAuth token (`xoxb-…`) — outbound Web API. |
+| `app_token` | yes | App-level token (`xapp-…`, `connections:write`) — Socket Mode. |
+| `workspace_id` | yes | Slack workspace/team id (`T…`). |
+
+On save the bridge starts its Socket Mode session immediately. Add the app to a
+channel (or create a bridged room) to start relaying.
+
+## App configuration reference
+
+The manifest above already sets all of this — this section is for the
+from-scratch path and as a reference for what the app needs.
+
+### Bot token scopes
+
+Under **OAuth & Permissions → Scopes → Bot Token Scopes**:
+
+- `chat:write`, `chat:write.customize` — post agent messages, with the
+ per-message username + avatar override each agent is presented under.
+- `commands` — the `/…` slash commands.
+- `channels:read`, `channels:manage` — look up, create, set topic on, and invite
+ into public channels; `groups:read`, `groups:write` — the same for private
+ channels.
+- `channels:history`, `groups:history`, `im:history`, `mpim:history` — read
+ channel / DM / group-DM message history for context.
+- `im:read`, `im:write` — direct messages.
+- `users:read` — resolve user display names.
+- `files:read`, `files:write` — relay attachments (incl. agent image uploads).
+- `reactions:read`, `reactions:write` — reaction-based acknowledgements.
+- `assistant:write` — assistant/app-home surface.
+
+### Event subscriptions (over Socket Mode)
+
+Subscribe the **bot** to (no request URL is needed with Socket Mode):
+
+- `message.channels`, `message.groups`, `message.im`, `message.mpim` — inbound
+ messages in public/private channels, DMs, and group DMs.
+
+A message that tags the app itself is recognised from these `message.*` events
+(the bridge detects its own bot mention inline), so a separate `app_mention`
+subscription is not required.
+
+### Interactivity and slash commands
+
+Enable **Interactivity** and add the `/…` slash commands (the full set is in the
+manifest) so Switch's in-room commands work from Slack.
+
+## Notes
+
+- **Deeplinks.** Slack linkifies `http(s)`, so "Open in SwitchDash" links work
+ once `GATEWAY_PUBLIC_URL` is set on switch-core (see the
+ [index](README.md#deployment-knobs)); otherwise the raw `switchdash://` link is
+ posted.
+- **Local dev.** There is no local Slack — Slack always points at a real
+ workspace onboarded through the gateway. (Local dev seeds only Mattermost.)
diff --git a/docs/bridges/TEAMS_SETUP.md b/docs/bridges/TEAMS_SETUP.md
new file mode 100644
index 000000000..d516150f2
--- /dev/null
+++ b/docs/bridges/TEAMS_SETUP.md
@@ -0,0 +1,105 @@
+# Microsoft Teams collaboration bridge setup
+
+Connects a Microsoft Teams tenant to Switch. A **single Azure bot app** backs
+every Switch agent (like Slack); each agent's messages render as an **Adaptive
+Card** headed with the agent's name and avatar.
+
+Teams is the only bridge that **requires public HTTPS ingress**: it has no
+persistent bot socket, so the adapter hosts its own HTTP listener and Microsoft
+pushes events to it.
+
+> This guide is the operator-facing setup walkthrough. The in-package note at
+> [`core/switch_core/bridges/collaboration/teams/README.md`](../../core/switch_core/bridges/collaboration/teams/README.md)
+> covers the adapter's internal architecture (Bot Framework + Graph capture,
+> encryption, de-duplication) in more depth.
+
+## Architecture in brief
+
+Two Microsoft APIs feed the bridge, both landing on the adapter's own listener:
+
+- **Bot Framework** — outbound messages post via the Bot Connector REST API at
+ the per-tenant `serviceUrl`. Inbound activities (1:1 and group chats in full;
+ channel messages only when the bot is `@mentioned`; membership updates) arrive
+ at `POST /api/messages`. The Bot Connector JWT is verified before an activity
+ is trusted.
+- **Microsoft Graph change notifications** — to capture *every* channel message
+ (not just `@mentions`), the adapter subscribes per channel and Graph delivers
+ **encrypted** resource data to `POST /api/teams/notifications`. The adapter
+ validates the `clientState` secret, decrypts with its private key, and renews
+ subscriptions before their ~60-minute expiry.
+
+## Ops prerequisites (must exist before onboarding)
+
+These are tenant/environment setup owned by an administrator — treat as a
+separate ops task before you can onboard the bridge.
+
+1. **Azure AD app registration** — provides the bot's `app_id` (client id), a
+ client secret (`app_password`), and the `tenant_id`.
+2. **Azure Bot resource** on that app, with the **messaging endpoint** set to
+ `https://<public-host>/api/messages` and the **Microsoft Teams channel**
+ enabled.
+3. **Teams app package** (manifest) including the bot, installed into the target
+ team so it can be added to channels and post proactively.
+4. **Graph API permissions** (admin-consented) for channel capture +
+ provisioning: `ChannelMessage.Read.Group` (RSC, preferred) *or* tenant-wide
+ `ChannelMessage.Read.All`; plus `Channel.Create` and
+ `TeamMember.ReadWrite.All` / `ChannelMember.ReadWrite.All`. Resource-data
+ subscriptions count against a shared per-tenant Teams subscription quota.
+5. **Encryption certificate** — an X.509 cert whose public certificate is handed
+ to Graph and whose private key the bridge holds to decrypt message bodies.
+ Give it a stable id.
+6. **Public HTTPS ingress** routing `https://<public-host>/api/messages` and
+ `/api/teams/notifications` to the bridge's listener. Graph requires valid TLS
+ and a response to its validation handshake within 10 seconds.
+
+## Onboard the bridge in Switch
+
+As a gateway admin, onboard the bridge from the **operator dashboard**:
+**Messaging Apps → Add bridge → Teams**, give it a display name (e.g. "Acme
+Teams"), and fill in the fields below.
+
+Fields (`TeamsConnectionConfig`):
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `app_id` | yes | Azure AD app (bot) client id. |
+| `app_password` | yes | Azure AD app client secret. |
+| `tenant_id` | yes | Azure AD tenant id. |
+| `team_id` | yes | AAD team (group) id that outbound-created channels go into. |
+| `public_base_url` | yes | Public HTTPS base the listener is reachable at (used to build the `/api/teams/notifications` URL given to Graph). |
+| `client_state` | yes | Shared secret echoed in every Graph notification and validated on receipt — the only control that authenticates a notification's origin. |
+| `encryption_certificate_id` | for channel capture | Stable id for the Graph resource-data encryption cert. |
+| `encryption_public_certificate` | for channel capture | PEM public certificate handed to Graph. |
+| `encryption_private_key` | for channel capture | PEM private key used to decrypt message bodies. |
+
+Switch-internal fields are **not** admin inputs and are hidden from the gateway
+form:
+
+- `listen_host` / `listen_port` (default `0.0.0.0:3978`) — the listener bind, a
+ deployment detail. Override via the stored `connection_config` only when
+ running more than one Teams bridge on a host (one bridge per listener port).
+- `service_url` — the Bot Connector outbound endpoint, learned at runtime from
+ inbound activities and persisted automatically.
+
+Without the three encryption fields the bridge still runs (outbound, chats, and
+`@mention` capture work), but per-channel Graph subscriptions are skipped and an
+error is logged — **full channel capture is disabled until they are supplied**.
+
+## Security note
+
+Graph resource-data encryption proves message **integrity, not origin** (the
+wrapping key is the public certificate, which anyone can encrypt to). The
+`clientState` shared secret is therefore **required** and validated on every
+notification. Inbound Bot Framework activities are separately authenticated by
+verifying the Bot Connector JWT.
+
+## Known limitations / follow-ups
+
+- **Switch-initiated DM rooms** are user-initiated (as on Mattermost);
+ bootstrapping one bot-side needs proactive app installation via Graph.
+- **Attachments** (inbound media and outbound files) are currently **disclosed,
+ not relayed** — the text bridges and a note names the un-relayed media.
+- **Real outbound `@mentions`** are not yet emitted (needs a display-name → AAD
+ id directory); mention text bridges as plain `@name`.
+- **One Teams bridge per listener port** — run multiple on distinct ports (and
+ ingress routes) if needed.