Discord and Platform Integrations

The Palyra platform integrates with external messaging services through a modular connector framework. This system allows the daemon to bridge Natural Language Space (Discord, Slack, etc.) with the internal Tool and Agent Execution Space. The Discord connector is the primary reference implementation, utilizing a WebSocket gateway for real-time interaction and a structured onboarding flow.

Connector Architecture

All platform integrations are built upon the ConnectorAdapter trait. This trait abstracts the specificities of each platform’s API, providing a unified interface for the ConnectorSupervisor to manage lifecycle, message routing, and delivery guarantees.

Key Code Entities

Entity	Role	Source
`ConnectorAdapter`	Trait defining `send_outbound` and platform metadata.	crates/palyra-connector-core/src/supervisor.rs
`ConnectorSupervisor`	Orchestrates the lifecycle of active connector instances.	crates/palyra-connector-core/src/supervisor.rs
`ConnectorStore`	SQLite-backed persistence for outbox and dead-letter queues.	crates/palyra-connector-core/src/storage.rs
`OutboundMessageRequest`	Internal representation of a message to be sent to a platform.	crates/palyra-connector-core/src/protocol.rs
`DeliveryOutcome`	Result of a send attempt (Delivered, Retry, or PermanentFailure).	crates/palyra-connector-core/src/protocol.rs

Data Flow: Outbound Message Routing

The following diagram illustrates how an internal agent request is routed to an external platform like Discord. Outbound Message Flow Sources: crates/palyra-connectors/src/lib.rs#1-13, crates/palyra-connector-core/src/protocol.rs

Discord Connector Implementation

The Discord integration is implemented in the palyra-connector-discord crate. It handles the complexities of the Discord WebSocket Gateway and REST API, including DM pairing and guild (server) message routing.

Implementation Details

Identity Mapping: Discord users are mapped to internal principals using the discord_principal function crates/palyra-daemon/src/channels/discord.rs#8-8.
Normalization: The system enforces canonical formats for account IDs and target channels via normalize_discord_account_id crates/palyra-daemon/src/channels/discord.rs#13-16.
Egress Control: Default egress allowlists are managed to prevent data exfiltration to unauthorized Discord servers crates/palyra-daemon/src/channels/discord.rs#7-10.

Connection Setup and Onboarding

Discord setup is an interactive process managed via the CLI. It involves a “probe” phase to validate tokens and permissions followed by an “apply” phase to persist the configuration.

CLI Function	Purpose
`run_setup`	Interactive TTY flow for onboarding a new Discord bot.
`run_verify`	Sends a test message to verify connector health.
`probe_payload`	Generates the pre-flight check request for the admin API.

Sources: crates/palyra-cli/src/commands/channels/connectors/discord/setup.rs#10-97, crates/palyra-cli/src/commands/channels/connectors/discord/verify.rs#8-54

Channel Admin CLI Commands

The palyra CLI provides a comprehensive suite of commands for managing channel routing and pairings under the channels router subcommand.

Command Reference

Rules: Displays the current routing rules for mapping inbound messages to agents crates/palyra-cli/src/commands/channels/router.rs#11-26.
Preview: Allows operators to simulate a message and see how the ConnectorRouter would handle it crates/palyra-cli/src/commands/channels/router.rs#43-91.
Pairings: Lists established pairings between platform identities (e.g., a Discord User ID) and Palyra accounts crates/palyra-cli/src/commands/channels/router.rs#92-120.
MintPairingCode: Generates a temporary code that a user can type into a chat (e.g., /pair 123456) to link their platform identity to the daemon crates/palyra-cli/src/commands/channels/router.rs#121-153.

Connection Management

CLI commands resolve their target daemon using RootCommandContext crates/palyra-cli/src/app/mod.rs#29-39. It supports:

gRPC Transport: Used for real-time interaction and status updates via resolve_grpc_connection crates/palyra-cli/src/app/mod.rs#173-186.
HTTP Admin API: Used for configuration and onboarding via resolve_http_connection crates/palyra-cli/src/app/mod.rs#188-201.

Sources: crates/palyra-cli/src/commands/channels/router.rs#1-160, crates/palyra-cli/src/app/mod.rs#173-201

Dead-Letter Management and Idempotency

To ensure reliability, the connector framework implements strict idempotency and dead-letter handling.

Idempotency Logic

The EchoConnectorAdapter (used for testing) demonstrates the platform’s approach to idempotency. Every outbound request includes an envelope_id. Adapters must track these IDs to ensure that retries (e.g., after a network failure) do not result in duplicate messages on the platform crates/palyra-connectors/src/connectors/echo.rs#68-75.

Retry Classification

When a delivery fails, the adapter returns a RetryClass to the supervisor:

ConnectorRestarting: Temporary failure; the supervisor should restart the connector and retry crates/palyra-connectors/src/connectors/echo.rs#55-59.
RateLimited: The platform has throttled the bot.
PermanentFailure: The message is moved to the DeadLetterRecord table in ConnectorStore.

Dead-Letter and Retry Flow Sources: crates/palyra-connectors/src/connectors/echo.rs#43-76, crates/palyra-connector-core/src/protocol.rs

Platform Stubs

While Discord is fully implemented, the codebase includes stubs and patterns for Slack and Telegram. These follow the same ConnectorAdapter pattern, utilizing reqwest for API communication and tokio-tungstenite for WebSocket-based “Socket Mode” or “Long Polling” implementations where applicable. Sources: crates/palyra-connectors/Cargo.toml#17-24

​Connector Architecture

​Key Code Entities

​Data Flow: Outbound Message Routing

​Discord Connector Implementation

​Implementation Details

​Connection Setup and Onboarding

​Channel Admin CLI Commands

​Command Reference

​Connection Management

​Dead-Letter Management and Idempotency

​Idempotency Logic

​Retry Classification

​Platform Stubs