docs: add group behavior and multi-bot sections to Discord setup (#282)

2026-02-11 12:23:32 -08:00
parent 046f15feaa
commit e395dc58a4
1 changed files with 101 additions and 0 deletions
--- a/docs/discord-setup.md
+++ b/docs/discord-setup.md
@@ -138,6 +138,103 @@ dmPolicy: open
 - Anyone can message the bot
 - Not recommended for personal bots

+## Group Behavior
+
+By default, the bot processes and responds to all messages in server channels (`open` mode). You can control this with the `groups` config.
+
+### Group Modes
+
+Three modes are available:
+
+- **`open`** -- Bot responds to all messages in the channel (default)
+- **`listen`** -- Bot processes all messages for context/memory, but only responds when @mentioned
+- **`mention-only`** -- Bot completely ignores messages unless @mentioned (cheapest option -- messages are dropped at the adapter level before reaching the agent)
+
+### Configuring group modes
+
+Add a `groups` section to your Discord channel config. Keys can be channel IDs, guild (server) IDs, or `*` as a wildcard default:
+
+```yaml
+channels:
+  discord:
+    enabled: true
+    token: "your-bot-token"
+    groups:
+      "*": { mode: mention-only }              # default: require @mention everywhere
+      "123456789012345678": { mode: open }      # this channel: respond to everything
+      "987654321098765432": { mode: listen }    # this channel: read all, respond on mention
+```
+
+Mode resolution priority: channel ID > guild ID > `*` wildcard > `open` (built-in default).
+
+### Channel allowlisting
+
+If you define `groups` with specific IDs and **do not** include a `*` wildcard, the bot will only be active in those listed channels. Messages in unlisted channels are silently dropped -- they never reach the agent and consume no tokens.
+
+```yaml
+channels:
+  discord:
+    token: "your-bot-token"
+    groups:
+      "111111111111111111": { mode: open }
+      "222222222222222222": { mode: mention-only }
+      # No "*" -- all other channels are completely ignored
+```
+
+This is the recommended approach when you want to restrict the bot to specific channels.
+
+## Multiple Bots on Discord
+
+If you run multiple agents in a [multi-agent configuration](./configuration.md#multi-agent-configuration), each with their own Discord adapter, there are two scenarios to consider.
+
+### Separate Discord app tokens (recommended)
+
+Each bot connects independently. Give each its own `groups` config:
+
+```yaml
+agents:
+  - name: helper-bot
+    channels:
+      discord:
+        token: "TOKEN_A"
+        groups:
+          "*": { mode: mention-only }
+
+  - name: creative-bot
+    channels:
+      discord:
+        token: "TOKEN_B"
+        groups:
+          "*": { mode: mention-only }
+```
+
+These bots are fully isolated -- Discord delivers messages to each token independently.
+
+### Shared Discord app token
+
+If two agents share the same Discord app token, Discord delivers every message to both adapter instances. Use channel allowlisting (no `*` wildcard) to partition which channels each bot handles:
+
+```yaml
+agents:
+  - name: bot1
+    channels:
+      discord:
+        token: "SHARED_TOKEN"
+        groups:
+          "CHANNEL_FOR_BOT1": { mode: mention-only }
+          # No "*" -- bot1 ignores all other channels
+
+  - name: bot2
+    channels:
+      discord:
+        token: "SHARED_TOKEN"
+        groups:
+          "CHANNEL_FOR_BOT2": { mode: mention-only }
+          # No "*" -- bot2 ignores all other channels
+```
+
+Both adapters technically receive every Discord event, but the non-matching adapter drops messages immediately in the event handler -- no agent interaction, no token cost. For true isolation at the Discord level, use separate app tokens.
+
 ## Adding Reactions

 LettaBot can react to messages using the `lettabot-react` CLI:
@@ -171,6 +268,10 @@ lettabot-react add --emoji ":thumbsup:" --channel discord --chat 123456789 --mes
 3. **Check pairing status** if using pairing mode:
   - New users need to be approved via `lettabot pairing list`

+### All bots respond to every message
+
+If you run multiple agents sharing the same Discord token and all of them respond to every message, you need to configure channel allowlisting. Add a `groups` section to each agent's Discord config with specific channel IDs and **no `*` wildcard**. See [Multiple Bots on Discord](#multiple-bots-on-discord) above.
+
 ### "0 Servers" in Developer Portal

 The bot hasn't been invited to any servers yet. Use the invite URL from Step 4.