> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Auto-Reply Pipeline

# 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

```mermaid theme={"dark"}
flowchart LR
  A[Inbound message] --> B[Debounce]
  B --> C[Deduplication]
  C --> D[Send policy check]
  D --> E[Command detection]
  E --> F{Command?}
  F -->|Yes| G[Command handler]
  F -->|No| H[Transcription\n& media understanding]
  H --> I[Link understanding]
  I --> J[Hook: message:received]
  J --> K[Envelope wrap]
  K --> L[Agent run]
  L --> M[Hook: message:transcribed\nmessage:preprocessed]
  M --> N[Reply chunking]
  N --> O[TTS / voice-note-loop]
  O --> P[Send]
```

**Debounce.** Multiple messages arriving in quick succession from the same sender can be coalesced into a single agent turn. The debounce window is set via `messages.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](#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](#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](https://docs.wednesdayai.dev/next/users/date-time.md)).

**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](#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 these `message:*` events. All are fired fire-and-forget; they do not block the pipeline.

| Event | Stage | Context fields | Notes |
| - | - | - | - |
| `message:received` | After deduplication, before command check | `from`, `content`, `timestamp`, `channelId`, `accountId`, `conversationId`, `messageId`, `metadata` | Fires for every non-duplicate inbound message, including commands |
| `message:transcribed` | After audio transcription | `from`, `to`, `body`, `bodyForAgent`, `transcript`, `timestamp`, `channelId`, `conversationId`, `messageId`, `senderId`, `senderName`, `senderUsername`, `provider`, `surface`, `mediaPath`, `mediaType` | Only fires when `ctx.Transcript` is set (audio message) |
| `message:preprocessed` | After all media + link understanding completes | `from`, `to`, `body`, `bodyForAgent`, `transcript?`, `timestamp`, `channelId`, `conversationId`, `messageId`, `senderId`, `senderName`, `senderUsername`, `provider`, `surface`, `mediaPath`, `mediaType`, `isGroup`, `groupId` | Always fires (even for text-only messages with no transcript) |

`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](https://docs.wednesdayai.dev/next/developers/concepts/workspace-lanes.md) 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](https://docs.wednesdayai.dev/next/users/automation/hooks.md) 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](https://docs.wednesdayai.dev/next/developers/plugins/hook-parity.md).

Example — log every transcribed voice message:

```ts theme={"dark"}
export default function (api) {
  api.registerHook(
    "message:transcribed",
    async (event) => {
      const ctx = event.context as { transcript: string; channelId: string };
      api.logger.info(`[${ctx.channelId}] transcribed: ${ctx.transcript}`);
    },
    { name: "my-plugin.log-transcriptions" },
  );
}
```

## 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:

| Category | Commands |
| - | - |
| Status | `/help`, `/commands`, `/status`, `/context`, `/whoami` (`/id`) |
| Session | `/reset`, `/new`, `/stop`, `/compact`, `/session` |
| Options | `/model`, `/models`, `/think` (`/thinking`, `/t`), `/verbose` (`/v`), `/reasoning` (`/reason`), `/elevated` (`/elev`), `/exec`, `/usage`, `/queue` |
| Management | `/config`, `/debug`, `/allowlist`, `/approve`, `/send`, `/activation`, `/subagents`, `/kill`, `/steer` (`/tell`), `/acp`, `/focus`, `/unfocus`, `/agents` |
| Media | `/tts` |
| Tools | `/skill`, `/bash`, `/restart` |

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](https://docs.wednesdayai.dev/next/users/tools/plugin.md#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:

```text theme={"dark"}
/send off     → deny  (block replies)
/send on      → allow
/send inherit → reset to config default
```

The policy is persisted in the session store and read by `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`:

```json5 theme={"dark"}
{
  tts: {
    auto: "inbound", // trigger TTS when the inbound message is audio
    voiceNoteLoop: "enabled", // "disabled" | "enabled" | "both"
  },
}
```

Modes:

* `"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 under `agents.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.

```json5 theme={"dark"}
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // interval (default: 30m)
        target: "last", // delivery target
        prompt: "", // custom prompt body (empty string = default prompt)
        lightContext: true, // bootstrap from HEARTBEAT.md only
        // toolsAllow: ["session_status"], // optional: bound the isolated heartbeat tool surface (requires isolatedSession: true)
      },
    },
  },
}
```

**Delivery targets.** The `target` field controls where heartbeat output is sent:

| Value | Behavior |
| - | - |
| `"none"` (default) | Run silently; no output is delivered |
| `"last"` | Deliver to the most recent conversation for this session |
| `"webchat"` | Append to the session chat (web client/Control UI) and push to connected clients |
| `"whatsapp"` | Deliver to WhatsApp (requires `to` field) |
| `"telegram"` | Deliver to Telegram (requires `to` field) |
| `"discord"` | Deliver to Discord (requires `to` field) |
| Any channel id | Deliver to that channel plugin (requires `to` field) |

**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](https://docs.wednesdayai.dev/next/developers/reference/prompt-caching.md#byte-stability-across-trigger-kinds)). 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](https://docs.wednesdayai.dev/next/users/automation/cron-vs-heartbeat.md).

## Troubleshooting

**Message received but no reply.**

1. Check `wednesdayai channels status --probe` — confirm the channel is connected and the session key resolves.
2. Check the gateway log for `send_policy_deny` — the session's send policy may be `deny` (run `/send on` from that conversation).
3. Check whether a debounce is swallowing rapid messages: lower or zero `messages.inbound.debounceMs`.
4. Confirm the session's allowlist includes the sender (`/allowlist list`).
5. Check for a `duplicate` skip in the log — the same message id may have been delivered twice by the provider.
6. For a message queued behind an active run, check the log for `Followup reply failed after the agent run` or `dropped a follow-up`. A followup turn is never re-run after its agent has run; see [Command Queue](https://docs.wednesdayai.dev/next/developers/concepts/queue.md#when-a-followup-turn-fails).

**Reply sent, but immediately followed by an unexpected heartbeat.**

Heartbeats fire on a timer regardless of recent activity. If you want heartbeats to pause when a conversation is active, use `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](https://docs.wednesdayai.dev/next/users/automation/cron-vs-heartbeat.md).

**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](https://docs.wednesdayai.dev/next/users/nodes/media-understanding.md#config-provided-proxy-bindings-openai-compatible)). 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).

## Related

* [Hooks](https://docs.wednesdayai.dev/next/users/automation/hooks.md)
* [Cron jobs](https://docs.wednesdayai.dev/next/users/automation/cron-jobs.md)
* [Heartbeat vs Cron](https://docs.wednesdayai.dev/next/users/automation/cron-vs-heartbeat.md)
* [Agent loop](https://docs.wednesdayai.dev/next/developers/concepts/agent-loop.md)
* [Sessions](https://docs.wednesdayai.dev/next/developers/concepts/session.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.