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

# Channel Routing

# Channels & routing

WednesdayAI routes replies **back to the channel where a message came from**. The
model does not choose a channel; routing is deterministic and controlled by the
host configuration.

## Key terms

* **Channel**: `whatsapp`, `telegram`, `discord`, `slack`, `signal`, `imessage`, `webchat`.
* **AccountId**: per‑channel account instance (when supported).
* Optional channel default account: `channels.<channel>.defaultAccount` chooses
  which account is used when an outbound path does not specify `accountId`.
* **AgentId**: an isolated workspace + session store (“brain”).
* **SessionKey**: the bucket key used to store context and control concurrency.

## Session key shapes (examples)

Direct messages collapse to the agent’s **main** session:

* `agent:<agentId>:<mainKey>` (default: `agent:main:main`)

Groups and channels remain isolated per channel:

* Groups: `agent:<agentId>:<channel>:group:<id>`
* Channels/rooms: `agent:<agentId>:<channel>:channel:<id>`

Threads:

* Slack/Discord threads append `:thread:<threadId>` to the base key.
* Telegram forum topics embed `:topic:<topicId>` in the group key.

Examples:

* `agent:main:telegram:group:-1001234567890:topic:42`
* `agent:main:discord:channel:123456:thread:987654`

## Main DM route pinning

When `session.dmScope` is `main`, direct messages may share one main session.
To prevent the session’s `lastRoute` from being overwritten by non-owner DMs,
WednesdayAI infers a pinned owner from `allowFrom` when all of these are true:

* `allowFrom` has exactly one non-wildcard entry.
* The entry can be normalized to a concrete sender ID for that channel.
* The inbound DM sender does not match that pinned owner.

In that mismatch case, WednesdayAI still records inbound session metadata, but it
skips updating the main session `lastRoute`.

## Routing rules (how an agent is chosen)

Routing picks **one agent** for each inbound message:

1. **Exact peer match** (`bindings` with `peer.kind` + `peer.id`).
2. **Parent peer match** (thread inheritance).
3. **Guild + roles match** (Discord) via `guildId` + `roles`.
4. **Guild match** (Discord) via `guildId`.
5. **Team match** (Slack) via `teamId`.
6. **Account match** (`accountId` on the channel).
7. **Channel match** (any account on that channel, `accountId: "*"`).
8. **Default agent** (`agents.list[].default`, else first list entry, fallback to `main`).

When a binding includes multiple match fields (`peer`, `guildId`, `teamId`, `roles`), **all provided fields must match** for that binding to apply.

The matched agent determines which workspace and session store are used.

## Broadcast groups (run multiple agents)

Broadcast groups let you run **multiple agents** for the same peer **when WednesdayAI would normally reply** (for example: in WhatsApp groups, after mention/activation gating).

Config:

```json5 theme={"dark"}
{
  broadcast: {
    strategy: "parallel",
    "120363403215116621@g.us": ["alfred", "baerbel"],
    "+15555550123": ["support", "logger"],
  },
}
```

See: [Broadcast Groups](https://docs.wednesdayai.dev/next/admin/channels/broadcast-groups.md).

## Config overview

* `agents.list`: named agent definitions (workspace, model, etc.).
* `bindings`: map inbound channels/accounts/peers to agents.

Example:

```json5 theme={"dark"}
{
  agents: {
    list: [{ id: "support", name: "Support", workspace: "~/.openclaw/workspace-support" }],
  },
  bindings: [
    { match: { channel: "slack", teamId: "T123" }, agentId: "support" },
    { match: { channel: "telegram", peer: { kind: "group", id: "-100123" } }, agentId: "support" },
  ],
}
```

## Account mode

Each channel account is exclusively one of two things: a chat channel the agent talks
through, or an inbox source that only feeds the inbox store. The mode is resolved per
account:

```
channels.<ch>.accounts.<id>.mode ?? channels.<ch>.mode ?? "channel"
```

The channel root is the default account's config, so a channel-level `mode` applies to the
default account and every account that does not override it.

Supported channels: `whatsapp`, `bluebubbles`, and `discord`. Signal adds inbox mode when it
ships. Every other built-in channel accepts the `mode` key but rejects `"inbox"` at
validation; extension channel schemas reject the key entirely.

Note Slack: `channels.slack.mode` selects the socket/http transport. It is not the account
mode; Slack has no inbox mode.

An account in inbox mode is never a chat route. It has no agent replies, no pairing, no
allowlist or dm/group gating, no automatic read receipts, no typing indicators, and no
`message_received` hook. Inbound on that account is ingested by the inbox plugin only:

* WhatsApp ingests live through the channel message feed.
* BlueBubbles and Discord ingest through the inbox history scanners (60 s REST polling).
* Discord DMs are not ingested; the scanner only walks guild channels. A Discord inbox
  account also registers no slash commands, buttons, or voice.

Changing an account's `mode` restarts the gateway, so the channel monitor and the inbox
plugin switch together.

An `inbox.owners` entry may name a chat-mode account. It is not an error: the binding still
scopes rows ingested before the account switched to chat, and it applies as soon as the account
switches to inbox mode. A chat-mode account starts without an inbox log line.

The three validation errors:

* `channel "<ch>" has no inbox source; mode "inbox" is supported on: whatsapp, bluebubbles, discord`
* `account "<ch>:<id>" is in inbox mode and cannot be bound to an agent`
* `defaultAccount "<id>" is in inbox mode; the default account must be a chat channel`

Migration: `inbox.sources.<id>` for channel-backed ids (`whatsapp-web`, `bluebubbles`,
`discord`, `slack`) is deprecated and ignored. `wednesdayai doctor --fix` converts it: an
account is switched to inbox mode only when it cannot chat (`dmPolicy` and `groupPolicy`
both `"disabled"` and no binding names it, and it is not the channel's `defaultAccount`);
otherwise it stays chat-only with a warning. The gateway applies the same migration at start.
A key that lives in an `$include` file cannot be rewritten: the gateway warns and you remove
it by hand. Gmail and ms365 enablement is unchanged.

## Session storage

Sessions live in SQL session storage under the state directory (default `~/.openclaw`):

* session database: `~/.openclaw/sessions.db` (SQLite default; Postgres via `session.storage`)
* per-agent store identity: `~/.openclaw/agents/<agentId>/sessions/sessions.json` (also where the
  one-time legacy JSON import looks for old session files)

You can override the store identity via `session.store` and `{agentId}` templating.

## WebChat behavior

WebChat attaches to the **selected agent** and defaults to the agent’s main
session. Because of this, WebChat lets you see cross‑channel context for that
agent in one place.

## Reply context

Inbound replies include:

* `ReplyToId`, `ReplyToBody`, and `ReplyToSender` when available.
* Quoted context is appended to `Body` as a `[Replying to ...]` block.

This is consistent across channels.


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