Discord (Bot API)

Updated: 2025-12-07

Status: ready for DM and guild text channels via the official Discord bot gateway.

Goals

Talk to Clawdis via Discord DMs or guild channels.
Share the same main session used by WhatsApp/Telegram/WebChat; guild channels stay isolated as group:<channelId>.
Keep routing deterministic: replies always go back to the surface they arrived on.

How it works

Create a Discord application → Bot, enable the intents you need (DMs + guild messages + message content), and grab the bot token.
Invite the bot to your server with the permissions required to read/send messages where you want to use it.
Configure Clawdis with DISCORD_BOT_TOKEN (or discord.token in ~/.clawdis/clawdis.json).
Run the gateway; it auto-starts the Discord provider when the token is set (unless discord.enabled = false).
Direct chats: use user:<id> (or a <@id> mention) when delivering; all turns land in the shared main session.
Guild channels: use channel:<channelId> for delivery. Mentions are required by default; disable with discord.requireMention = false.
Optional DM allowlist: reuse discord.allowFrom with user ids (1234567890 or discord:1234567890). Use "*" to allow all DMs.
Optional guild allowlist: set discord.guildAllowFrom with guilds and/or users to gate who can invoke the bot in servers.

Note: Discord does not provide a simple username → id lookup without extra guild context, so prefer ids or <@id> mentions for DM delivery targets.

Capabilities & limits

DMs and guild text channels (threads are treated as separate channels; voice not supported).
Typing indicators sent best-effort; message chunking honors Discord’s 2k character limit.
File uploads supported up to the configured discord.mediaMaxMb (default 8 MB).
Mention-gated guild replies by default to avoid noisy bots.

Config

{
  discord: {
    enabled: true,
    token: "abc.123",
    allowFrom: ["123456789012345678"],
    guildAllowFrom: {
      guilds: ["123456789012345678"],
      users: ["987654321098765432"]
    },
    requireMention: true,
    mediaMaxMb: 8
  }
}

allowFrom: DM allowlist (user ids). Omit or set to ["*"] to allow any DM sender.
guildAllowFrom: Optional allowlist for guild messages. Set guilds and/or users (ids). When both are set, both must match.
requireMention: when true, messages in guild channels must mention the bot.
mediaMaxMb: clamp inbound media saved to disk.

Safety & ops

Treat the bot token like a password; prefer the DISCORD_BOT_TOKEN env var on supervised hosts or lock down the config file permissions.
Only grant the bot permissions it needs (typically Read/Send Messages).
If the bot is stuck or rate limited, restart the gateway (clawdis gateway --force) after confirming no other processes own the Discord session.

3.0 KiB Raw Blame History Unescape Escape