Auto-Reply Pipeline
The auto-reply pipeline is the layer that turns every inbound channel message into a structured agent run and reply. It owns message normalization, deduplication, media transcription, command detection, model routing, reply chunking, and send policy. All channels — Telegram, WhatsApp, Discord, Slack, Signal, iMessage, and plugin-registered channels — feed through this shared pipeline; only the final delivery step is channel-specific.Pipeline stages
Debounce. Multiple messages arriving in quick succession from the same sender can be coalesced into a single agent turn. The debounce window is set viamessages.inbound.debounceMs (global) or messages.inbound.byChannel.<channelId> (per channel). When debounce is zero or disabled, each message triggers its own dispatch immediately.
Deduplication. Before any work begins, each inbound context is checked against a short-lived in-memory deduplication key derived from the session key and message id. Duplicate deliveries from the same provider are silently dropped.
Send policy check. If the session’s send policy is deny, the message is logged and discarded without invoking the agent. Policy is set per-session via the /send command or via config. See Send policy.
Command detection. The normalized message body is matched against the built-in command registry and any plugin-registered commands. A control command (e.g. /reset, /model) bypasses the agent entirely; the command handler runs and returns a reply directly.
Transcription and media understanding. Audio and image attachments are processed before the message body reaches the agent. Audio files produce a transcript that is injected into BodyForAgent; images produce a description. Both are applied in parallel where possible.
Link understanding. URLs embedded in the message body are optionally fetched and summarized before the body is sent to the agent.
Hook events. After transcription and media understanding complete, message:transcribed fires (audio only) and message:preprocessed always fires. See Hook events.
Envelope wrap. The normalized body is wrapped with a metadata header: [Channel From Timestamp] body. The format is controlled by agents.defaults.envelopeTimezone, agents.defaults.envelopeTimestamp, and agents.defaults.envelopeElapsed. The envelope is applied for the current turn only; the stored transcript keeps the raw message text, and past turns render as a timestamp stamp plus that raw text (see Date & Time).
Agent run. The finalized message context is passed to getReplyFromConfig, which resolves session state, system prompt, model, and runs the agent loop. Directives embedded inline (e.g. /model gpt-4o or /think high) are extracted from the message before the loop starts.
Reply chunking. Agent output is split into platform-sized chunks before delivery. The default chunk limit is 4 000 characters. Override it per channel with channels.<id>.textChunkLimit. chunkMode is length (default: split only at the limit), newline (prefer paragraph boundaries and pack complete paragraphs up to the limit), or paragraph (one outbound message per paragraph). Oversized blocks fall back to length splitting. Fenced code blocks and tables stay intact. chunkNewlinePacking is deprecated; with chunkMode: "newline", false ≡ chunkMode: "paragraph". Prefer chunkMode: "paragraph".
TTS / voice-note-loop. If TTS is configured and tts.auto triggers, a voice note is synthesized and attached to the reply. When tts.voiceNoteLoop is "enabled", a voice-note inbound triggers a voice-note reply with the text suppressed. See Voice note loop.
Send. Final payloads are dispatched through the ReplyDispatcher, which serializes concurrent replies and shows typing indicators while the agent runs.
Hook events
Plugins and hook files can subscribe to thesemessage:* events. All are fired fire-and-forget; they do not block the pipeline.
senderId in these payloads is the raw sender of the turn. On gateway turns (web client, Control
UI) it is device:<deviceId> when the connection has a verified device, otherwise the app id (for
example openclaw-user-client); see Workspace Lanes for how devices
link to people. For a linked device, senderName is the person (ADR 0104). System agent-turns
(cron systemEvent/wake, nudge, work, announce) report trigger of cron/heartbeat — never
user — and carry the run’s configured identity.
Hooks are registered via api.registerHook(event, handler, opts) in a plugin, or as hook files using event keys message:received, message:transcribed, and message:preprocessed. See Hooks for the full hook authoring guide.
Hook names in plugin registrations are validated: a name the typed hook runner dispatches (api.on names), or one no internal emitter produces, produces a PLUGIN_HOOK_NOT_DISPATCHED warning — visible in wednesdayai plugins doctor, wednesdayai plugins status, and the gateway startup report, with the plugin shown as degraded in wednesdayai plugins list — while the plugin keeps loading. See the hook parity map.
Example — log every transcribed voice message:
Command registry
The command registry maps text aliases (e.g./reset, /model, /think) and native slash commands (Discord, Telegram) to handler functions. Built-in commands are defined in src/auto-reply/commands-registry.data.ts. The complete list includes:
Commands are matched in two modes: text (the message body equals
/commandname) and native (a Telegram, Discord, or Slack native slash command). Some commands are text-only (e.g. /bash, /allowlist); others are native-only; most support both.
Plugin commands. Plugins can register commands via api.registerCommand({ name, description, handler }). Plugin commands execute before built-in commands and before the agent. See Register auto-reply commands.
Enabling/disabling commands. /config and /debug can be restricted via commands.config and commands.debug config flags. The /bash command is gated by commands.bash.
Text command normalization. The registry normalizes colon syntax (/model:gpt-4o → /model gpt-4o) and Telegram bot-username suffixes (/reset@mybot → /reset) before matching.
Send policy
The send policy controls whether a reply is delivered to the channel. There are two runtime values:allow (default) and deny.
You can toggle the policy mid-conversation:
resolveSendPolicy in src/sessions/send-policy.ts at dispatch time. When deny is active, the agent still runs (unless you also /stop the run), but no output is delivered. This is useful for observation mode: you can watch what the agent would say without it replying to your contacts.
Config can set a default policy per-session via the session store; there is no global sendPolicy config key — the policy is always a per-session runtime state controlled through /send.
Voice note loop
voiceNoteLoop closes the voice ↔ voice loop: when the user sends a voice message, WednesdayAI replies with a voice message instead of text.
Configure it under tts:
"disabled"(default): The pipeline ignores whether the inbound message was audio; TTS auto-mode behaves normally."enabled": When an inbound audio message triggers TTS, the text is suppressed and only the synthesized voice note is delivered."both": When an inbound audio message triggers TTS, both the text reply and the voice note are delivered.
voiceNoteLoop is only active on channels that support audio outbound delivery. Telegram and WhatsApp both support voice-note delivery. Discord supports TTS via the /tts command path but not native voice note send. Other channels fall back to text delivery.
The relevant implementation is in src/auto-reply/reply/dispatch-from-config.ts (applyVoiceNoteLoopPolicy).
Heartbeat
Heartbeat runs are periodic background agent turns that fire independently of inbound messages. They are configured underagents.defaults.heartbeat (or per-agent under agents.list[*].heartbeat). Once any agents.list[*] entry has a heartbeat block, only those agents run heartbeats (isHeartbeatEnabledForAgent in src/infra/heartbeat-runner.config.ts) — an explicit block on one agent turns heartbeats off for every other agent.
target field controls where heartbeat output is sent:
Suppressing empty heartbeats. If the agent replies with
HEARTBEAT_OK (or a short acknowledgement under ackMaxChars characters, default 300), the pipeline strips the token and suppresses delivery. This prevents noise when there is nothing to report.
Heartbeat prompt. The default prompt is: "Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK." Override it with heartbeat.prompt. With lightContext: true, the default prompt is the shorter light wording instead (“Follow the HEARTBEAT.md instructions in your context strictly. Do not infer or repeat old tasks. If nothing needs attention, reply HEARTBEAT_OK.”); a configured heartbeat.prompt always wins over both.
Bootstrap context and cache stability
Which bootstrap files are assembled into the system prompt is normally derived from the session key: a dedicated:heartbeat session gets the heartbeat run kind, everything else gets default. The run kind only narrows the file set when lightweight context is requested (lightContext: true): heartbeat then keeps HEARTBEAT.md alone, while default keeps nothing. With lightContext: false both run kinds load the full bootstrap set, and heartbeat additionally keeps run-kind-gated files such as HEARTBEAT.md. Callers that run a scheduled turn inside a shared session can pin the bootstrap with the bootstrapContextRunKind reply option ("default" | "heartbeat" | "cron" on GetReplyOptions, threaded through to the embedded runner). The heartbeat runner uses this to keep shared-session heartbeats on the session’s normal default bootstrap — the heartbeat checklist is inlined into the trigger message instead, unless that bootstrap already injects it — so the system prompt stays byte-identical to user turns and the provider prefix cache survives every heartbeat (see Prompt caching). ACP cron execution pins "cron" the same way. You only need to care about this option when writing a custom trigger that enqueues agent turns into shared sessions; channel messages and the built-in heartbeat/cron paths already do the right thing.
For a comparison between heartbeats and cron jobs, see Heartbeat vs Cron.
Troubleshooting
Message received but no reply.- Check
wednesdayai channels status --probe— confirm the channel is connected and the session key resolves. - Check the gateway log for
send_policy_deny— the session’s send policy may bedeny(run/send onfrom that conversation). - Check whether a debounce is swallowing rapid messages: lower or zero
messages.inbound.debounceMs. - Confirm the session’s allowlist includes the sender (
/allowlist list). - Check for a
duplicateskip in the log — the same message id may have been delivered twice by the provider. - For a message queued behind an active run, check the log for
Followup reply failed after the agent runordropped a follow-up. A followup turn is never re-run after its agent has run; see Command Queue.
heartbeat.activeHours to restrict the window, or set heartbeat.target: "none" and trigger heartbeats only from cron jobs that check session state. See Heartbeat vs Cron.
Media attachment not understood.
Verify that a media-understanding provider extension is enabled (plugins.entries.<vendor>.enabled: true — vendor extensions are disabled by default) and configured (e.g. tools.media.audio for audio, or a vision-capable model for images). Audio transcription requires a local CLI (Whisper) or an enabled provider extension; a config-provided OpenAI-compatible proxy (models.providers.<id> with api: "openai-completions" or "openai-responses") needs no plugin extension, but voice notes are never auto-detected on it — name a speech-to-text model in tools.media.audio.models (see Config-provided proxy bindings). Check the gateway log for media-understanding errors, including the auto-selection-exhausted warning naming the remedy. If the attachment arrives as a URL rather than a local file, confirm that tools.media.downloadMedia is enabled so the pipeline can fetch it before processing.
Command not detected.
Run /commands in the conversation to list active commands. Check whether text commands are disabled for this surface (commands.text: false combined with a native-command surface like Discord). Verify that the command body starts with / after trimming — the normalizer strips colon syntax and bot-username suffixes but will not match a command buried in prose. If you added a plugin command, confirm the plugin loaded (wednesdayai plugins list and check for errors).