palyra-connectors framework, managed by the ChannelPlatform supervisor in the daemon. It supports message normalization, real-time gateway interaction, automated onboarding, and fine-grained mutation governance (edits/deletions/reactions).
Architecture Overview
The Discord implementation is divided into three primary adapter layers that satisfy theConnectorAdapter trait requirements. These layers isolate the complexities of the Discord API (REST and Gateway) from the internal Palyra routing logic.
| Layer | Responsibility | Key Entities |
|---|---|---|
| Gateway | Inbound message ingestion and real-time event processing. | DiscordGatewayAdapter |
| Transport | Outbound message delivery via Discord REST API. | DiscordTransportAdapter |
| Admin | Management operations: health checks, message search, and deletions. | DiscordAdminAdapter |
Data Flow: Inbound Message Normalization
When a message is received via the Discord Gateway, it is normalized into aConnectorMessageRecord before being routed to the palyrad control plane.
Sources: crates/palyra-daemon/src/channels.rs#154-161, crates/palyra-connectors/src/providers/discord/adapter/gateway.rs#1-50
Bot Token & Identity Management
Discord connectors are identified by a uniqueconnector_id derived from the Discord Account ID. Tokens are never stored in plaintext configuration; they are referenced via the Palyra Vault.
- Connector ID Generation: Generated using
discord_connector_id(account_id)crates/palyra-daemon/src/channels/discord.rs#12-15. - Principal Mapping: Discord users are mapped to internal principals using
discord_principal(user_id)crates/palyra-daemon/src/channels/discord.rs#11-15. - Vault Integration: The
discord_token_vault_ref(account_id)function creates a pointer to the secure storage location of the bot token crates/palyra-daemon/src/channels/discord.rs#11-15.
Message Mutation & Governance
Palyra implements a “Governance” layer for Discord actions like editing or deleting messages. This ensures that the agent’s destructive actions are gated by risk levels and windows of time.Mutation Classification Logic
The functionclassify_discord_message_mutation_governance determines if an action requires human-in-the-loop approval based on the age of the message and the type of operation.
| Operation | Window | Default Risk |
|---|---|---|
Edit | 15 Minutes | Low |
ReactAdd | 6 Hours | Low |
Delete | Immediate | High |
Any | > 24 Hours | High (Approval Required) |
Onboarding Flow
The Onboarding Wizard simplifies the process of connecting a new Discord bot to Palyra. It consists of aprobe (preflight) phase and an apply phase.
- Probe: Validates the bot token, checks Discord API connectivity, and retrieves bot metadata (Username, Discriminator, Guilds).
- Apply: Persists the configuration to the daemon, initializes the Vault entry for the token, and enables the connector.
Onboarding Components
Sources: apps/web/src/features/channels/connectors/discord/components/DiscordOnboardingPanel.tsx#128-135, crates/palyra-daemon/src/transport/http/handlers/admin/channels/connectors/discord.rs#25-41, apps/web/src/consoleApi/channels/discord.ts#73-98Management Interface
Web Console
TheChannelsSection provides a dedicated tab for Discord management, including:
- Direct Verification: Sending test messages to specific targets apps/web/src/features/channels/connectors/discord/components/DiscordConnectorActionsPanel.tsx#23-55.
- Health Refresh: Triggering a manual status check and gateway reconnection apps/web/src/consoleApi/channels/discord.ts#31-44.
- Queue Control: Pausing or draining the outbound message queue for a specific Discord connector apps/web/src/consoleApi/channels/core.ts#222-253.
CLI / Console Handlers
The daemon exposes HTTP handlers for both Admin and Console surfaces to manage Discord-specific lifecycle events:admin_discord_account_logout_handler: Log out a bot and optionally clear credentials crates/palyra-daemon/src/transport/http/handlers/admin/channels/connectors/discord.rs#43-60.admin_discord_account_remove_handler: Completely remove a Discord connector instance crates/palyra-daemon/src/transport/http/handlers/admin/channels/connectors/discord.rs#81-98.
Implementation Details: ChannelPlatform
TheChannelPlatform struct in the daemon acts as the orchestrator for all connectors, including Discord.
- Initialization: Opens the
ConnectorStore(SQLite) and initializes theConnectorSupervisorwith Discord adapters crates/palyra-daemon/src/channels.rs#142-169. - Test Sending: The
submit_discord_test_sendmethod allows developers to bypass the standard routing logic to verify connectivity crates/palyra-daemon/src/channels/discord.rs#62-152. - Attachment Handling: Discord-specific attachments are preprocessed using
preprocess_discord_inbound_attachmentsto handle CDN URLs and metadata crates/palyra-daemon/src/channels.rs#42-44.