Skip to content

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

13.9 KB
Raw Blame

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), the username carrying the agent's display name or its identifier when it has none. 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 → 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 and applications.commands. The second one lets the bridge register Switch's in-room commands as native slash commands (see Slash commands). Without it the bridge still runs, but the slash sync fails at startup — logged, not fatal — and only !-prefixed commands work.
  • 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 two per-channel webhooks the bridge posts through (see Two webhooks per channel).
    • Manage Channels / Manage Roles — set per-member channel permission overwrites (channel.set_permissions) when provisioning access, and mint the per-agent role that makes an agent's name autocomplete (see Agent name autocomplete).
    • Read Message History — thread-aware replies.
    • Attach Files — relay agent image attachments.
    • Add Reactions — mark the message an agent is working on (see Knowing an agent is working).

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 → Register messaging app → 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.
agent_roles no (default on) Give each agent a mentionable role so its name autocompletes. See below.

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.

Agent name autocomplete (agent_roles)

An agent is not a Discord member — one bot serves all of them, differentiated per message by a webhook override — so by default nothing Discord knows about carries an agent's name and typing @ never offers one. With this on, each agent gets a mentionable role named exactly after its identifier — the lowercase name, not the agent's display name — so @flint-tracker completes in the composer and arrives as a real pill. The role is empty and carries no permissions: mentioning it notifies nobody, and Switch resolves the mention back to the agent's name on the way in.

Roles are provisioned for every existing agent when the bridge starts, and for each new agent as it registers. Two limits are worth knowing before you turn it on:

  • Discord caps a server at 250 roles, hard. A server that hits the cap gets one warning naming it, and the bridge stops trying — agents stay addressable by typing their name.
  • A role carries no metadata, so there is nowhere to record that a role belongs to Switch. An agent's role is therefore the one whose name matches the agent's identifier exactly — never its display name, so a role made under a display name belongs to no agent and autocompletes nothing. Two consequences: a role you created by hand for an agent is adopted rather than duplicated (which is how to use this on a server where the bot may not manage roles), and when an agent is deleted its role is only deleted if nobody holds it — one with members is left in place, and the bridge says so.

Renaming an agent renames its role in place, so earlier mentions keep working.

Turn it off (agent_roles: false) on a server that is near the role cap or where role management is restricted.

Knowing an agent is working

When a Switch Console-managed agent starts on a message, two things appear:

  • A reaction on the message it is answering — 👀 while the agent is working on it, ⏳ while a prompt is waiting behind one already running. This is the only signal that says which message is being handled — an agent answering two people at once marks both. A mark comes off a message once the last turn holding it has ended, which is not always the same moment the turn that put it there ends: two prompts queued behind one message share its ⏳, and it stays until neither of them is queued behind anything any more. A queued turn that starts running releases the ⏳ before it finishes, so the hourglass going while an agent is still busy is the mark working, not failing. It needs the Add Reactions permission; without it the bridge logs a warning and posts no reaction rather than a mark that is not there.
  • A status message posted under the agent's own name and avatar, edited in place as the activity changes: "Working… 41s" while the turn runs, "Worked for 2m 14s." when it finishes. It stays in the channel after the turn rather than being deleted, so someone scrolling back can still see that the turn ran.

Stopping an agent. The status message carries a red Stop current work button while there is something to stop, beside the View activity button that opens the turn's tool log. Pressing it asks the agent to end its current turn; the agent decides how quickly it can, and the same message says when it has. The control names the turn it was drawn for, so a press on a message that has not been redrawn since a new turn started is refused rather than stopping the newer one. It disappears when the turn ends. On a queued message the button stops the work in front of it, not the queued message, and the message says so. Whoever presses it must be allowed to stop that agent — the same check a typed !interrupt goes through — and the result, accepted or refused, is shown to them alone.

The button needs a publication webhook this application owns (see below); a status published through somebody else's carries no components, and !interrupt is then the whole of what is on offer. Discord also caps a button's hidden id at 100 characters, so a provider whose turn ids are longer than about 90 gets no button and a warning in the log rather than a control whose press Discord would refuse.

What Discord cannot do here. There is no native progress surface — nothing like Slack's agent card — so the working message is one Switch renders itself. The typing indicator is not usable as a real indicator either: it expires after about 10 seconds, has no "stop" call, and shows the bot rather than the agent, so with two agents working it would read as one anonymous "Switch Bridge is typing". Discord's "thinking…" placeholder is interaction-only (slash commands), which does not cover an ordinary @agent message.

Two webhooks per channel

An admin looking at a channel's integration settings will see two Switch webhooks, not one, and both are expected:

  • Switch Bridge — every ordinary agent message, with the agent's name and avatar carried as a per-message override.
  • Switch Sessions — session status messages and request cards, and nothing else.

They are split so that a request card can be found again when its fate is unknown — the post timed out, or the process died between sending it and recording its id. Two things have to hold before Switch will bind a reservation to a message it finds, and the webhook is only the first: the message must have come through the publication webhook, and it must carry that card's heading line for that handle. The webhook alone rules out an agent's own reply that happens to quote a handle — "I can explain the request R7 syntax" arrives on the webhook agents speak through, so it is never a candidate — and the heading picks the right card out of the other publications beside it.

This does not recover a status message. A turn's status prints no handle, so there is nothing to match on and the lookup declines rather than guessing; the status stays unconfirmed and is not posted a second time. The current bridge emits no discriminator by which it can recover a status: a webhook message carries no metadata this bridge sets, so the handle a card prints is what the lookup has to match on. Alternative recovery approaches remain deferred. On a platform that can carry a marker — Slack does — a status is as findable as a card.

Both are minted on demand the first time the bridge needs them in a channel, and both need Manage Webhooks. Discord's limit is 15 webhooks per channel.

Slash commands

Switch's in-room commands are also registered as native Discord slash commands, so /reset @agent does exactly what typing !reset @agent does — same handler, same result. Nothing to configure beyond the applications.commands scope above: the set is published from the command registry when the bridge starts, and re-published on every start, so renames and removals reconcile themselves.

Two things behave differently from a typed !command, both from Discord:

  • Arguments are declared fields, not free text. Discord shows named inputs (/set-alias agent: … alias: …) and will not submit until the required ones are filled. The @ is optional — worker and @worker are equivalent. An argument that is not a single name is rejected rather than silently truncated at the first space.
  • The result arrives in a thread. A slash invocation is invisible to the channel, so the bridge posts a short ⚙️ Running … message and files the command's result in that message's thread. If a command fails, that message is rewritten into the error — a slash command never silently does nothing.

Commands are registered per guild, not globally: each bridge is scoped to one guild, guild-scoped commands apply immediately (global registration propagates for up to an hour), and because global commands are per-application they would otherwise appear in every guild the bot has joined, including ones with no Switch rooms.

If the slash commands do not appear, check the bridge's startup logs for a sync failure — the usual cause is a bot invited before applications.commands was added to its OAuth2 scopes. Re-inviting with the corrected URL and restarting the bridge fixes it.

Clickable "Open in Switch Console" links (GATEWAY_PUBLIC_URL)

Discord only linkifies http(s), so a raw switchdash://session?… deeplink renders as plain text; the bridge logs a warning at startup when it is running without this set. Set GATEWAY_PUBLIC_URL on switch-core to the Switch API's public origin — scheme + host only, no path — the same host Switch Console reports as its server (distinct from the operator UI):

# .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?… link (a page that hands off to the switchdash:// scheme) at runtime-state ingestion — so both the bridged working/awaiting-input status message and the !agents-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. Switch Console 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.