Principle:Openclaw Openclaw Message Ingestion
| Knowledge Sources | |
|---|---|
| Domains | Agent_Runtime, Messaging |
| Last Updated | 2026-02-06 12:00 GMT |
Overview
Message ingestion is the process of normalizing inbound messages from heterogeneous communication channels into a single, unified envelope type that all downstream processing stages can consume without knowledge of the originating channel.
Description
OpenClaw supports a wide variety of messaging channels: Telegram, Discord, Slack, Signal, iMessage, WhatsApp (web), and extension-based channels such as Microsoft Teams, Matrix, Zalo, and voice calls. Each channel has its own native message format, metadata conventions, and capabilities. A Telegram message carries topic IDs, sticker metadata, and forum flags; a Discord message carries guild IDs and thread identifiers; a Slack message carries team IDs and channel timestamps.
Message ingestion normalizes these disparate formats into a single canonical shape before any routing, command parsing, or LLM interaction occurs. The normalized envelope carries the message body in multiple forms (raw, agent-ready, command-ready), sender identity fields, media attachments and transcriptions, reply-to and forwarding metadata, group/thread context, originating channel information for reply routing, and provider-specific annotations. This envelope is the sole data contract between channel adapters and the rest of the agent runtime.
The design follows a denormalized, optional-field pattern: all fields are optional so that each channel adapter populates only the fields it can supply. Downstream consumers test for presence rather than dispatching on channel type, which keeps the core pipeline channel-agnostic and allows new channels to be added as extensions without modifying core logic.
Usage
Apply this principle whenever:
- Adding a new messaging channel or extension that receives inbound messages.
- Modifying how channel-specific metadata (stickers, threads, forums, reactions) is represented internally.
- Writing code that reads inbound message data -- consume the normalized envelope rather than reaching for provider-specific APIs.
- Extending the envelope with new metadata (e.g., a new media type or sender attribute) -- add an optional field to the canonical type and populate it in the relevant channel adapter.
Theoretical Basis
The pattern is a variant of the Canonical Data Model integration pattern. Rather than building point-to-point transformations between N channels and M consumers (O(N*M) adapters), a single canonical model reduces the integration surface to O(N+M): each channel writes one adapter that populates the canonical envelope, and each consumer reads from that envelope.
The optional-field strategy avoids the need for a discriminated union or channel-specific sub-types. This trades compile-time exhaustiveness for runtime flexibility, which suits a plugin-based architecture where channels may be added at runtime via extensions. The trade-off is mitigated by the finalization step (see finalizeInboundContext), which sets default-deny on security-sensitive fields (e.g., CommandAuthorized) and produces a FinalizedMsgContext that downstream code can trust.
Key design decisions:
- Multiple body representations:
Body,BodyForAgent,RawBody,CommandBody,BodyForCommandseach serve a distinct downstream consumer (prompt assembly, command parsing, display). This avoids re-parsing a single body field for different purposes. - Originating channel tagging:
OriginatingChannelandOriginatingToensure replies route back to the exact channel and chat/thread that originated the message, even when the agent session spans multiple channels. - Media normalization: Single-media fields (
MediaPath,MediaUrl) coexist with batch fields (MediaPaths,MediaUrls), supporting both simple single-attachment messages and multi-media messages without breaking existing consumers.