Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Python agent-orchestrationaiai-agentschatopsdiscordlangchainmcpmicrosoft-teamsmulti-agentopen-sourceopenaiself-hostedslack
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.mdindex 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 Teamsworkspace is connected **per bridge through the gateway** — all credentials livein 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.+## ArchitectureTeams has no persistent bot socket (unlike Slack Socket Mode / Mattermostdiff --git a/docs/bridges/DISCORD_SETUP.md b/docs/bridges/DISCORD_SETUP.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.