Skip to main content
Channel Connectors provide the integration layer between the Palyra AI gateway and external messaging platforms. The architecture is designed to be provider-agnostic, using a standardized supervisor/adapter pattern to handle message ingestion, delivery, and rate limiting across different protocols.

​
System Architecture

The connector subsystem is managed by the ConnectorSupervisor, which orchestrates the lifecycle of multiple ConnectorAdapter implementations. It acts as the bridge between the internal GatewayRuntimeState and external APIs.

​
Interaction Flow: NL Space to Code Entities

The following diagram illustrates how a natural language message from a user (e.g., on Discord) flows into the system and how the system responds. Sources:

​
Connector Framework

The framework provides the core traits and data structures used by all integrations. It manages the ConnectorStore (SQLite-backed persistence for connector state) and handles complex delivery logic like exponential backoff and dead-lettering.
ComponentResponsibility
ConnectorAdapterTrait for platform-specific logic (send/poll).
ConnectorSupervisorManages adapter lifecycles and message queuing.
OutboundMessageRequestStandardized internal format for outgoing messages.
DeliveryOutcomeEnum representing Delivered, Retry, or PermanentFailure.
DeadLetterRecordStores messages that failed after maximum retries.
For details, see Connector Framework. Sources:

​
Platform Integrations

Palyra supports multiple messaging platforms with varying levels of maturity. The DiscordConnectorAdapter is the primary reference implementation, supporting rich features like attachment pre-processing and secure DM pairing.

​
Code Entity Mapping: Integration Components

This diagram maps system concepts to specific code entities within the palyra-connectors and platform crates. For details, see Discord and Other Platform Integrations. Sources:

​
Webhooks

The Webhook subsystem allows external services to push events into Palyra. It includes a WebhookRegistry for managing endpoint configurations and security features like signature verification and replay protection.
  • Registry Management: Handled via WebhookRegistry which persists to webhooks.toml.
  • Diagnostics: The system provides snapshots via WebhookDiagnosticsSnapshot to track the health of integrations.
  • Testing: A dedicated CLI and API surface allows for simulated payload testing.
For details, see Webhooks. Sources:

​
Management and Monitoring

Connectors can be managed via the CLI or the Admin API. The system tracks saturation states (e.g., rate_limited, backpressure, retrying) to provide operators with visibility into delivery health. 
// Example of how the system builds a health snapshot for a connector
// From crates/palyra-daemon/src/transport/http/handlers/admin/channels/mod.rs:113-147
let saturation_state = if !connector.enabled {
    "paused"
} else if queue.dead_letters > 0 {
    "dead_lettered"
} else if active_route_limits > 0 {
    "rate_limited"
} else {
    "healthy"
};
Sources:

​
Child Pages