Skip to main content
The Discord integration in Palyra allows agents to interact with users and guilds via the Discord platform. It is implemented through a specialized connector crate palyra-connector-discord, which is supervised by the daemon’s channel platform to handle message normalization, permission validation, and real-time event monitoring.

​
Architecture Overview

The integration follows a layered approach where the palyra-daemon manages the lifecycle and routing, while palyra-connectors (via the Discord adapter) handles the low-level API communication.

​
Data Flow Diagram

The following diagram illustrates the flow of a message from Discord into the Palyra Gateway and back. “Discord Message Flow” Sources: [crates/palyra-daemon/src/channels.rs#112-140](http://crates/palyra-daemon/src/channels.rs#112-140), [crates/palyra-daemon/src/channels/discord.rs#1-21](http://crates/palyra-daemon/src/channels/discord.rs#1-21), [crates/palyra-connector-core/src/supervisor.rs#127-134](http://crates/palyra-connector-core/src/supervisor.rs#127-134)

​
Connector Implementation

The Discord integration is built on the ConnectorAdapter trait defined in palyra-connector-core.

​
Key Functions and Entities

EntityLocationRole
discord_connector_id[crates/palyra-daemon/src/channels/discord.rs#7-10](http://crates/palyra-daemon/src/channels/discord.rs#7-10)Generates a unique canonical ID for a Discord connector instance.
discord_connector_spec[crates/palyra-daemon/src/channels/discord.rs#18-21](http://crates/palyra-daemon/src/channels/discord.rs#18-21)Defines the ConnectorInstanceSpec (kind, principal, permissions).
normalize_discord_account_id[crates/palyra-daemon/src/channels/discord.rs#13-16](http://crates/palyra-daemon/src/channels/discord.rs#13-16)Validates and formats Discord Snowflake IDs.
ConnectorSupervisor[crates/palyra-connector-core/src/supervisor.rs#194-199](http://crates/palyra-connector-core/src/supervisor.rs#194-199)Manages the runtime state, retries, and polling for the Discord adapter.

​
Permissions and Normalization

Discord interactions require specific bot permissions. The daemon monitors these via build_discord_channel_permission_warnings to provide feedback when an agent lacks the ability to read history or send attachments [crates/palyra-daemon/src/transport/http/handlers/admin/channels/mod.rs#87-104](http://crates/palyra-daemon/src/transport/http/handlers/admin/channels/mod.rs#87-104). Sources: [crates/palyra-daemon/src/channels.rs#160-179](http://crates/palyra-daemon/src/channels.rs#160-179), [crates/palyra-daemon/src/channels/discord.rs#1-28](http://crates/palyra-daemon/src/channels/discord.rs#1-28)

​
Setup and Lifecycle

Discord connectors are managed through both the CLI and the Admin API.

​
CLI Commands

The palyra CLI provides a suite of commands for Discord onboarding:
  • palyra channels add --provider discord: Registers a new bot token.
  • palyra channels login: Re-authenticates or updates an existing Discord connector.
  • palyra channels logout: Disables the connector while optionally retaining credentials [crates/palyra-daemon/src/transport/http/handlers/admin/channels/connectors/discord.rs#113-139](http://crates/palyra-daemon/src/transport/http/handlers/admin/channels/connectors/discord.rs#113-139).

​
Onboarding Flow

The onboarding process involves a “preflight” check to verify the bot token and its access to guilds. “Discord Onboarding Logic” Sources: [crates/palyra-daemon/src/transport/http/handlers/admin/channels/connectors/discord.rs#6-40](http://crates/palyra-daemon/src/transport/http/handlers/admin/channels/connectors/discord.rs#6-40), [crates/palyra-daemon/src/transport/http/handlers/console/channels/connectors/discord.rs#126-162](http://crates/palyra-daemon/src/transport/http/handlers/console/channels/connectors/discord.rs#126-162)

​
Admin and Diagnostics

The Admin surface provides deep visibility into the Discord connector’s health.

​
Health Monitoring

The admin_channels_list_handler and associated status builders aggregate data from the ConnectorSupervisor to identify:
  • Saturation State: Whether the connector is healthy, rate_limited, or experiencing backpressure [crates/palyra-daemon/src/transport/http/handlers/admin/channels/mod.rs#114-147](http://crates/palyra-daemon/src/transport/http/handlers/admin/channels/mod.rs#114-147).
  • Dead Letters: Messages that failed delivery after maximum retries (e.g., due to the bot being kicked from a server) [crates/palyra-daemon/src/transport/http/handlers/admin/channels/mod.rs#38-41](http://crates/palyra-daemon/src/transport/http/handlers/admin/channels/mod.rs#38-41).
  • Inbound Monitor: Real-time status of the WebSocket connection to the Discord Gateway [crates/palyra-daemon/src/transport/http/handlers/console/channels/connectors/discord.rs#160-165](http://crates/palyra-daemon/src/transport/http/handlers/console/channels/connectors/discord.rs#160-165).

​
Diagnostic Indicators

FieldSourceDescription
last_permission_failure[crates/palyra-daemon/src/transport/http/handlers/admin/channels/mod.rs#87](http://crates/palyra-daemon/src/transport/http/handlers/admin/channels/mod.rs#87)Regex-matched errors indicating missing Discord scopes.
global_retry_after_ms[crates/palyra-daemon/src/transport/http/handlers/admin/channels/mod.rs#68](http://crates/palyra-daemon/src/transport/http/handlers/admin/channels/mod.rs#68)Discord API rate limit backoff signal.
inbound_alive[crates/palyra-daemon/src/transport/http/handlers/console/channels/connectors/discord.rs#163](http://crates/palyra-daemon/src/transport/http/handlers/console/channels/connectors/discord.rs#163)Boolean indicating if the Gateway heartbeats are healthy.
Sources: [crates/palyra-daemon/src/transport/http/handlers/admin/channels/mod.rs#11-53](http://crates/palyra-daemon/src/transport/http/handlers/admin/channels/mod.rs#11-53), [crates/palyra-daemon/src/transport/http/handlers/admin/channels/mod.rs#153-165](http://crates/palyra-daemon/src/transport/http/handlers/admin/channels/mod.rs#153-165)