Messaging Channels
Relevant source files
The following files were used as context for generating this wiki page:
- src/plugin-sdk/index.ts
- src/config/schema.ts
- extensions/mattermost/src/channel.ts
- extensions/discord/src/channel.ts
- extensions/mattermost/src/mattermost/monitor.ts
- extensions/mattermost/src/mattermost/send.ts
- extensions/mattermost/src/mattermost/client.ts
- src/commands/onboard-channels.ts
- src/agents/system-prompt.ts
Messaging Channels represent the integration layer between the Clawdbot core and external communication platforms. These channels facilitate bidirectional communication, allowing the bot to receive inbound messages, process them through its agent logic, and deliver outbound replies. The system is designed as a plugin-based architecture where each platform (e.g., Discord, Slack, Telegram, Mattermost) is implemented as a specialized extension.
The framework handles complexities such as message debouncing, mention gating, media handling, and platform-specific formatting. By abstracting these into a common interface defined in the Plugin SDK, the core agent remains agnostic of the specific transport layer while retaining the ability to use platform-specific features like polls or reactions when supported.
Sources: src/plugin-sdk/index.ts, AGENTS.md:12-20, extensions/mattermost/src/channel.ts
Core Architecture and Plugin System
The messaging system relies on a standardized ChannelPlugin interface. This interface defines how a channel handles onboarding, security, messaging, and status monitoring.
Channel Plugin Structure
Each channel extension must implement specific adapters to integrate with the bot's lifecycle:
- Outbound Adapter: Handles sending text and media to the platform, including logic for chunking messages that exceed platform limits.
- Security Adapter: Manages Direct Message (DM) policies, allowlists, and pairing requests.
- Gateway Adapter: Controls the startup and monitoring of the platform-specific connection (e.g., WebSocket listeners).
- Status Adapter: Reports on the health, connectivity, and last activity of the channel account.
Sources: src/plugin-sdk/index.ts:7-54, extensions/mattermost/src/channel.ts:46-150
Connection Lifecycle
The following diagram illustrates how a messaging channel is initialized and maintained within the Gateway:
The startAccount method within the gateway property of a plugin is responsible for initiating the provider's monitoring logic, often involving a WebSocket connection to the external service.
Sources: extensions/mattermost/src/channel.ts:258-274, extensions/mattermost/src/mattermost/monitor.ts:186-210
Inbound Message Processing
Inbound messages undergo several layers of filtering and normalization before reaching the bot agent. This ensures the bot only responds to authorized users and relevant contexts.
Message Flow and Normalization
When a message is received via a platform's API (e.g., a Mattermost WebSocket event), the following steps occur:
- Deduplication: Check if the message ID has been processed recently.
- Authorization: Validate the sender against configured
dmPolicy(for DMs) orgroupPolicy(for group chats). - Mention Gating: In group contexts, determine if the bot was mentioned or if an "onchar" trigger (like
!) was used. - Normalization: Strip platform-specific mentions and convert media attachments into bot-readable placeholders.
- Context Construction: Package the message into a
ReplyPayloadcontaining the body, sender details, and session keys.
Sources: extensions/mattermost/src/mattermost/monitor.ts:262-430, extensions/mattermost/src/mattermost/monitor.ts:470-520
Security and Access Control
| Policy Type | Description | File Reference |
|---|---|---|
| Pairing | Default policy where unknown users receive a pairing code to be approved by an admin. | extensions/mattermost/src/channel.ts:107 |
| Allowlist | Restricts access to specific user IDs or usernames defined in the configuration. | extensions/mattermost/src/mattermost/monitor.ts:133-145 |
| Open | Allows any user on the platform to interact with the bot (not recommended for all channels). | extensions/mattermost/src/channel.ts:121 |
| Disabled | Completely ignores inbound messages for that specific channel/account. | extensions/mattermost/src/mattermost/monitor.ts:342 |
Sequence: Inbound Event Handling
Outbound Delivery and Formatting
The outbound adapter manages the transmission of messages from the bot to the user. This includes handling platform-specific constraints like message length and markdown variations.
Outbound Logic
- Chunking: If a message exceeds a platform's character limit (e.g., 4000 for Mattermost, 2000 for Discord), the
chunkerbreaks the text into multiple valid chunks. - Markdown Conversion: Different platforms use different markdown flavors. For example, Slack uses
mrkdwnwhich converts bold from**text**to*text*. TheconvertMarkdownTablesfunction handles table rendering based on the platform's capabilities. - Media Upload: Local or remote media URLs are fetched and uploaded as native attachments to the communication platform.
Sources: extensions/mattermost/src/channel.ts:162-192, extensions/mattermost/src/mattermost/send.ts:136-160, src/slack/format.test.ts:5-80
Send Message Configuration
| Parameter | Type | Description |
|---|---|---|
to | string | Recipient identifier (e.g., user:ID, channel:ID, or @username). |
text | string | The message content to be sent. |
mediaUrl | string | Optional URL for file attachments (supports file:// and http(s)://). |
replyToId | string | Optional ID to create a threaded reply or reference a specific message. |
Sources: extensions/mattermost/src/mattermost/send.ts:12-22, skills/discord/SKILL.md:145-165
Supported Channel Types and Platforms
The project supports a wide variety of channels, both built-in and via extensions.
- Chat Platforms: Discord, Slack, Telegram, Mattermost, Microsoft Teams.
- Direct Messaging: iMessage (via BlueBubbles or local CLI), Signal, WhatsApp.
- Advanced Features:
- Polls: Supported on Discord and Telegram.
- Reactions: Bot can react to messages using emojis.
- Threads: Capability to maintain conversations in threaded replies.
Sources: src/config/schema.ts:344-385, extensions/discord/src/channel.ts:43-52
Status and Monitoring
Channels provide detailed status snapshots to the Gateway, allowing users to monitor connectivity and troubleshoot issues.
The probeAccount method is used for ad-hoc connectivity checks (e.g., during clawdbot status --deep), verifying if the configured tokens and URLs are valid without starting the full monitor.
Sources: extensions/mattermost/src/channel.ts:213-245, src/commands/status.command.ts:350-410
Summary
Messaging Channels provide the essential connectivity layer for Clawdbot. Through a robust plugin system, the bot standardizes complex communication tasks—such as OAuth/Token authentication, WebSocket management, and message normalization—across diverse platforms. The architecture prioritizes security through configurable DM policies and mention gating, while ensuring a high-quality user experience with platform-aware markdown formatting and media handling. Channels act as the primary interface for user interaction, feedback loops, and agent-driven notifications.