Discord

The Discord interface connects Aleph to Discord using the serenity framework. It supports guild (server) channels, direct messages, file attachments, embeds, reactions, Markdown formatting, and slash commands.

Capabilities

Prerequisites

cargo build --release --features discord
# or for all interfaces:
cargo build --release --features all-interfaces

Configuration

Minimal Configuration

[[channels]]
id = "discord"
channel_type = "discord"
enabled = true

[channels.config]
bot_token = "MTIzNDU2Nzg5MDEyMzQ1Njc4OQ.ABcDeF.1234567890abcdefghijklmnop"

Full Configuration Reference

[[channels]]
id = "discord"
channel_type = "discord"
enabled = true

[channels.config]
# Bot token from Discord Developer Portal (required)
# Supports ${ENV_VAR} expansion
bot_token = "${DISCORD_BOT_TOKEN}"

# Application ID for slash commands registration (optional)
application_id = 123456789012345678

# Guild (server) allowlist -- empty means allow all guilds
allowed_guilds = [123456789012345678]

# Channel allowlist within guilds -- empty means allow all channels
allowed_channels = [987654321098765432]

# Allow direct messages (default: true)
dm_allowed = true

# Prefix for text commands (default: "!")
command_prefix = "!"

# Respond only when mentioned in guilds (default: true)
respond_to_mentions = true

# Register and use slash commands (default: true)
slash_commands_enabled = true

# Send typing indicator while processing (default: true)
send_typing = true

# Gateway intents configuration
[channels.config.intents]
guild_messages = true      # Receive guild messages (default: true)
direct_messages = true     # Receive DMs (default: true)
message_content = true     # Read message content (default: true, privileged)
guild_members = false      # Track guild member events (default: false, privileged)

Environment Variable Mode

export DISCORD_BOT_TOKEN="MTIzNDU2..."
export DISCORD_APPLICATION_ID="123456789012345678"  # Optional

Permission Audit

Aleph includes a built-in permission audit system that checks the bot's permissions in each guild. Permissions are categorized into three levels:

Required Permissions

These are essential for basic operation:

Recommended Permissions

These enable richer interaction:

Optional Permissions

The audit produces a traffic-light assessment:

• Green (Healthy) -- All required and recommended permissions granted
• Yellow (Degraded) -- Required permissions present, some recommended missing
• Red (Critical) -- Missing required permissions; bot cannot function

You can check permission status via the interface.status RPC method.

Message Routing

Guild Channel Messages

In guild channels, the bot processes messages when:

1. The message is not from a bot (prevents self-loops)
2. The guild is in allowed_guilds (or the list is empty)
3. The channel is in allowed_channels (or the list is empty)
4. The bot is mentioned, or the message starts with command_prefix, or respond_to_mentions is false

When respond_to_mentions is true (default), the bot only responds to messages that @mention it or use the command prefix. This prevents the bot from responding to every message in a busy channel.

The mention text is automatically stripped from the message before routing to the agent.

Direct Messages

DMs are processed whenever dm_allowed is true. No prefix or mention is required -- all DM text is forwarded directly to the agent.

Conversation IDs

Session Routing

Each Discord conversation maps to a session key:

Attachments

Receiving Attachments

Discord attachments are extracted with full metadata:

Attachment {
    id: "attachment_id",
    mime_type: "image/png",      // From content_type or default
    filename: Some("image.png"), // Original filename
    size: Some(12345),           // Size in bytes
    url: Some("https://cdn.discordapp.com/..."), // CDN URL
}

Sending Attachments

Outbound attachments are sent as Discord file attachments. Currently, in-memory byte data is supported:

let msg = OutboundMessage::text("channel_id", "Here is the file")
    .with_attachment(Attachment {
        data: Some(file_bytes),
        filename: Some("output.txt".to_string()),
        ..Default::default()
    });

Reply Threading

When the agent responds to a specific message, Discord's reply reference is used:

• Inbound messages include reply_to if the user replied to a previous message
• Outbound messages can set reply_to to create a reply chain

This creates the visual reply indicator in Discord's UI.

Slash Commands

When slash_commands_enabled is true and application_id is set, Aleph can register slash commands with Discord. These appear in the command picker when users type /:

• /ask -- Send a message to Aleph
• /status -- Check Aleph's status
• /help -- Show available commands

Error Handling

Gateway Intents

Discord requires bots to declare which events they want to receive. Aleph's intent configuration maps directly to Discord Gateway Intents:

[channels.config.intents]
guild_messages = true      # GUILD_MESSAGES intent
direct_messages = true     # DIRECT_MESSAGES intent
message_content = true     # MESSAGE_CONTENT intent (privileged)
guild_members = false      # GUILD_MEMBERS intent (privileged)

Troubleshooting