Auto-Reply & Routing
Relevant source files
The following files were used as context for generating this wiki page:
Auto-Reply & Routing constitutes the core messaging intelligence of Clawdbot, managing how the agent intercepts, processes, and dispatches responses across various messaging platforms. The system ensures that messages are correctly routed between built-in channels (like Telegram, Discord, and Slack) and extension-based channels while maintaining consistent session state and user identity verification.
The routing logic integrates deeply with the project's agent architecture, utilizing session keys to track conversations and ensuring that proactive messages or automated replies reach the intended destination without duplication. This system also handles "Silent Replies" and "Heartbeats" to maintain a clean interaction flow on external messaging surfaces.
Messaging Architecture & Routing Logic
Clawdbot handles routing internally through a unified messaging interface that abstracts the complexities of individual platform APIs. The message tool is the primary mechanism for proactive sends and channel actions, such as polls or reactions.
Core Routing Components
The routing system distinguishes between current session replies and cross-session messaging. Responses generated in the current session are automatically routed back to the source channel, while sessions_send is used for cross-session communication.
The diagram shows the high-level flow of message routing from ingestion to output.
Sources: src/agents/system-prompt.ts:79-84, CLAUDE.md
Supported Messaging Channels
Clawdbot supports a wide array of built-in and extension-based messaging channels. Routing logic must account for the specific capabilities of each channel, such as support for inline buttons or media attachments.
| Channel Category | Supported Platforms |
|---|---|
| Core Channels | Telegram, Discord, Slack, Signal, iMessage, Web (WhatsApp Web) |
| Extension Channels | MS Teams, Matrix, Zalo, ZaloUser, Voice-Call |
Auto-Reply Mechanisms
The auto-reply system is governed by several specialized protocols designed to optimize the user experience and reduce noise on external platforms.
Silent Replies and Heartbeats
To prevent redundant or empty messages, Clawdbot implements a SILENT_REPLY_TOKEN. If an agent uses the message tool for a visible reply, it must respond with this token to signal that no further output is required. Additionally, a heartbeat system allows the agent to acknowledge "heartbeat polls" with a specific HEARTBEAT_OK response if no attention is needed.
The sequence diagram illustrates the logic for heartbeats and the protocol for preventing duplicate messages via silent tokens.
Sources: src/agents/system-prompt.ts:89-92, src/agents/system-prompt.ts:401-415, src/agents/system-prompt.ts:420-428
Message Queueing and Formatting
Replies are queued to manage delivery across different platform constraints. Formatting logic ensures that Markdown-heavy responses from the LLM are correctly converted to platform-specific formats (e.g., converting Markdown to Slack's mrkdwn or using bullets for Signal/WhatsApp).
Sources: src/slack/format.test.ts:5-80, appcast.xml
Implementation Details
Session and Identity Resolution
Routing relies on the derivation and resolution of session keys. The system uses deriveSessionKey and resolveSessionKey to ensure that messages are mapped to the correct conversation history and user profile.
// src/index.ts
export {
deriveSessionKey,
resolveSessionKey,
resolveStorePath,
saveSessionStore,
// ... other exports
};
Sources: src/index.ts:18-24, src/index.ts:55-58
Status Monitoring
The status command provides a real-time overview of channel health and routing state. It tracks the state of each channel (OK, WARN, OFF, or SETUP) and identifies any gateway-level issues affecting message delivery.
| Status Field | Description |
|---|---|
| Channel State | Indicates if a channel is ON, OFF, or experiencing issues (WARN). |
| Gateway Reachability | Probes the gateway connection to ensure routing is possible. |
| Recent Sessions | Displays active routing keys, age, and token usage. |
Sources: src/commands/status.command.ts:450-485, src/commands/status.command.ts:494-515
Conclusion
The Auto-Reply & Routing system provides a robust framework for multi-channel communication. By centralizing routing logic within the Clawdbot Gateway and utilizing intelligent tokens for silence and heartbeats, the system maintains high reliability and a seamless user experience across diverse messaging environments. This architecture allows developers to add new channels via extensions without modifying the core routing intelligence.