Skip to main content
The Discord and Platform Integrations subsystem manages the lifecycle, connectivity, and message routing between the Palyra daemon and external communication platforms. It leverages a supervisor-based architecture to manage multiple connector instances, with a specialized focus on the Discord bot integration.

​
Architecture Overview

The integration layer is built upon the palyra-connectors crate, which provides a unified framework for implementing platform-specific adapters. The ChannelPlatform serves as the central manager within the daemon, orchestrating the ConnectorSupervisor and the ConnectorStore.

​
Data Flow: Inbound & Outbound

The following diagram illustrates the flow of messages between a Discord client and the Palyra GatewayRuntimeState. Discord Message Lifecycle Sources: [crates/palyra-daemon/src/channels.rs#106-137](http://crates/palyra-daemon/src/channels.rs#106-137), [crates/palyra-connector-core/src/supervisor.rs#128-134](http://crates/palyra-connector-core/src/supervisor.rs#128-134), [crates/palyra-connector-core/src/supervisor.rs#194-214](http://crates/palyra-connector-core/src/supervisor.rs#194-214)

​
Channel Management

The ChannelPlatform struct in crates/palyra-daemon/src/channels.rs is the primary entry point for managing platform connectors. It initializes the SQLite-backed ConnectorStore and the ConnectorSupervisor.

​
Key Components

ComponentFile PathResponsibility
ChannelPlatform[crates/palyra-daemon/src/channels.rs#106-110](http://crates/palyra-daemon/src/channels.rs#106-110)Top-level daemon integration for all channels.
ConnectorSupervisor[crates/palyra-connector-core/src/supervisor.rs#194-199](http://crates/palyra-connector-core/src/supervisor.rs#194-199)Manages connector lifecycles, retries, and polling.
ConnectorStore[crates/palyra-connector-core/src/storage.rs#1-10](http://crates/palyra-connector-core/src/storage.rs#1-10)Persistence for connector specs, outbox, and dead letters.
DiscordConnectorAdapter[crates/palyra-connector-discord/src/lib.rs#1-20](http://crates/palyra-connector-discord/src/lib.rs#1-20)Implements ConnectorAdapter for the Discord protocol.
Sources: [crates/palyra-daemon/src/channels.rs#113-140](http://crates/palyra-daemon/src/channels.rs#113-140), [crates/palyra-connector-core/src/supervisor.rs#137-174](http://crates/palyra-connector-core/src/supervisor.rs#137-174)

​
Discord Onboarding Flow

Discord integration follows a multi-stage onboarding process to ensure correct permissions and connectivity. This is handled via the admin_discord_onboarding_probe_handler and admin_discord_onboarding_apply_handler.
  1. Preflight Probe: Validates the provided Discord Bot Token, checks if the bot can reach the Discord API, and retrieves bot identity (Username/ID).
  2. Permission Check: Verifies that the bot has required permissions (e.g., View Channels, Send Messages).
  3. Application: Stores the token in the palyra-vault, registers the ConnectorInstanceSpec in the ConnectorStore, and enables the connector.

​
Discord Entity Resolution

Discord IDs are normalized and mapped to Palyra Principals using specific patterns:
  • Connector ID: discord:{account_id} via discord_connector_id() [crates/palyra-daemon/src/channels/discord.rs#7-10](http://crates/palyra-daemon/src/channels/discord.rs#7-10).
  • Principal: channel:discord:{account_id} via discord_principal() [crates/palyra-daemon/src/channels/discord.rs#7-10](http://crates/palyra-daemon/src/channels/discord.rs#7-10).
Sources: [crates/palyra-daemon/src/transport/http/handlers/admin/channels/connectors/discord.rs#6-22](http://crates/palyra-daemon/src/transport/http/handlers/admin/channels/connectors/discord.rs#6-22), [crates/palyra-daemon/src/transport/http/handlers/console/channels/connectors/discord.rs#126-176](http://crates/palyra-daemon/src/transport/http/handlers/console/channels/connectors/discord.rs#126-176)

​
Mention Pattern Matching

For inbound messages, Palyra often requires a “mention” to trigger an agent response, especially in group channels. The palyra-connector-discord crate handles the detection of these patterns.
  • Direct Mentions: Matching <@!ID> or <@ID>.
  • Configurable Patterns: Users can define additional regex or string patterns in the ConnectorInstanceSpec.
  • Inbound Scope: Determines if the bot listens to all messages, only mentions, or specific threads.
Sources: [crates/palyra-cli/src/commands/channels/mod.rs#74-75](http://crates/palyra-cli/src/commands/channels/mod.rs#74-75), [crates/palyra-daemon/src/transport/http/handlers/console/channels/connectors/discord.rs#500-510](http://crates/palyra-daemon/src/transport/http/handlers/console/channels/connectors/discord.rs#500-510)

​
CLI Channel Management

The palyra CLI provides comprehensive commands for managing channels via the ChannelsCommand enum. CLI to Daemon Command Mapping Sources: [crates/palyra-cli/src/commands/channels/mod.rs#61-205](http://crates/palyra-cli/src/commands/channels/mod.rs#61-205), [crates/palyra-daemon/src/transport/http/handlers/admin/channels/connectors/discord.rs#6-110](http://crates/palyra-daemon/src/transport/http/handlers/admin/channels/connectors/discord.rs#6-110)

​
Common Commands

  • palyra channels add discord: Initiates the interactive onboarding for a Discord bot.
  • palyra channels login discord --account-id <ID>: Re-activates a previously configured channel.
  • palyra channels logout discord --account-id <ID>: Disables the connector and optionally removes the token from the vault [crates/palyra-cli/src/commands/channels/mod.rs#162-183](http://crates/palyra-cli/src/commands/channels/mod.rs#162-183).

​
Webhook Integration

In addition to stateful connectors like Discord, Palyra supports stateless Webhooks via the WebhookRegistry.
  • Registry: Webhooks are defined in webhooks.toml, managed by WebhookRegistry [crates/palyra-daemon/src/webhooks.rs#107-111](http://crates/palyra-daemon/src/webhooks.rs#107-111).
  • Validation: Supports signature verification and payload size limits (max_payload_bytes) [crates/palyra-daemon/src/webhooks.rs#33-43](http://crates/palyra-daemon/src/webhooks.rs#33-43).
  • Diagnostics: The daemon tracks the readiness of webhooks, checking if secrets are present in the vault [crates/palyra-daemon/src/webhooks.rs#96-104](http://crates/palyra-daemon/src/webhooks.rs#96-104).
Sources: [crates/palyra-daemon/src/webhooks.rs#178-187](http://crates/palyra-daemon/src/webhooks.rs#178-187), [crates/palyra-cli/src/commands/webhooks.rs#12-133](http://crates/palyra-cli/src/commands/webhooks.rs#12-133)