openclaw/docs/plugins/sdk-channel-inbound.md

summary, title, read_when

summary	title	read_when
Inbound event helpers for channel plugins: context building, shared runner orchestration, session record, and prepared reply dispatch	Channel inbound API	You are building or refactoring a messaging channel plugin receive path You need shared inbound context construction, session recording, or prepared reply dispatch You are migrating old channel turn helpers to inbound/message APIs

Channel plugins should model receive paths with inbound and message nouns:

platform event -> inbound facts/context -> agent reply -> message delivery

Use openclaw/plugin-sdk/channel-inbound for inbound event normalization, formatting, roots, and orchestration. Use openclaw/plugin-sdk/channel-outbound for native send, receipt, durable delivery, and live preview behavior.

Core Helpers

import {
  buildChannelInboundEventContext,
  runChannelInboundEvent,
  dispatchChannelInboundReply,
} from "openclaw/plugin-sdk/channel-inbound";

• buildChannelInboundEventContext(...): project normalized channel facts into the prompt/session context.
• runChannelInboundEvent(...): run ingest, classify, preflight, resolve, record, dispatch, and finalize for one inbound platform event.
• dispatchChannelInboundReply(...): record and dispatch an already assembled inbound reply with a delivery adapter.

The injected plugin runtime exposes the same high-level helpers under runtime.channel.inbound.* for bundled/native channels that already receive the runtime object.

await runtime.channel.inbound.run({
  channel: "demo",
  accountId,
  raw: platformEvent,
  adapter: {
    ingest: normalizePlatformEvent,
    resolveTurn: resolveInboundReply,
  },
});

Compatibility dispatchers should assemble dispatchChannelInboundReply(...) inputs and keep platform delivery in the delivery adapter. New send paths should prefer message adapters and durable message helpers.

Migration

• runtime.channel.turn.run(...) -> runtime.channel.inbound.run(...)
• runtime.channel.turn.runPrepared(...) -> runtime.channel.inbound.runPreparedReply(...)
• runtime.channel.turn.runAssembled(...) -> runtime.channel.inbound.dispatchReply(...)
• runtime.channel.turn.buildContext(...) -> runtime.channel.inbound.buildContext(...)

New plugin code should not introduce turn-named channel APIs. Keep model or agent turn vocabulary inside agent/provider code; channel plugins use inbound, message, delivery, and reply terms.

The runtime.channel.turn.* aliases remain only as deprecated compatibility for already published plugins. They can be removed in the next major SDK cleanup after external plugins have had a migration window.