Skip to main content

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:
See: Broadcast Groups.

Config overview

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

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