Apus applies the same group rules across group-capable channels, including Discord, iMessage, Matrix, Microsoft Teams, QQBot, Signal, Slack, Telegram, WhatsApp, and Zalo.

For always-on rooms that should provide quiet context unless the agent explicitly sends a visible message, see Ambient room events.

Beginner intro (2 minutes)

Apus "lives" on your own messaging accounts. There is no separate WhatsApp bot user: if you are in a group, Apus can see that group and respond there.

Default behavior:

• Groups are restricted (groupPolicy: "allowlist"); group senders are blocked until allowlisted.
• Replies require a mention unless you disable mention gating for a group.
• Final reply text posts to the room automatically (visibleReplies: "automatic").

Translation: allowlisted senders can trigger Apus by mentioning it.

Quick flow (what happens to a group message):

groupPolicy? disabled -> drop
groupPolicy? allowlist -> group allowed? no -> drop
requireMention? yes -> mentioned? no -> store for context only
mention/reply/command/DM -> user request
always-on group chatter -> user request, or room event when configured

Bot-created threads

Use requireMentionInBotThreads to override mention gating only in a thread or topic created by the receiving bot:

• false accepts unmentioned follow-ups in confirmed bot-created threads.
• true requires a mention there, even when the room normally accepts all messages. Replies, quotes, and past bot participation alone do not satisfy it; native mentions, configured mention patterns, and authorized commands retain their normal behavior.
• Omitted preserves the channel's existing mention and implicit-reply behavior.

For example, keep Discord parent channels mention-gated while opening the bot's own threads, and apply the same policy to Slack. Merge these fields into your existing channel configuration, preserving its credentials and allowlists:

{
  channels: {
    discord: {
      intents: { messageContent: true },
      guilds: {
        "123456789012345678": {
          requireMention: true,
          requireMentionInBotThreads: false,
        },
      },
    },
    slack: {
      requireMention: true,
      requireMentionInBotThreads: false,
    },
  },
}

The setting uses each channel's existing configuration scopes; account-scoped configuration uses the corresponding paths under accounts.<id> where supported. For a narrower change, set the option on an existing allowed channel entry. See the Discord example and Slack example.

Unknown or unavailable ownership keeps ordinary mention rules. Existing bounded caches can lose old ownership evidence; see the channel documentation for its limits. A bot replying in someone else's thread does not make it the creator. Sender, channel, and bot-access restrictions still apply. Explicit session bindings retain their own route activation rules.

These rules govern new message admissions. An already admitted turn keeps its captured policy; changing mention rules or sender allowlists does not suppress its reply.

The transport must deliver unmentioned messages before Apus can apply the policy:

• Discord needs Message Content Intent enabled in both the Developer Portal and the Apus account configuration.
• Microsoft Teams needs the ChannelMessage.Read.Group RSC permission.
• Slack needs channel membership and the matching message.channels or message.groups event subscription.
• Telegram needs privacy mode disabled or group-admin status.

The current Google Chat interaction webhook does not provide ordinary unmentioned space messages or thread-owner metadata, so it does not expose this option. Channels that provide only quotes, direct conversations, or no native threads also keep their existing mention behavior. External plugins need to implement the shared thread mention policy.

Visible replies

For normal group/channel requests, Apus defaults to messages.groupChat.visibleReplies: "automatic": the final assistant text posts to the room as the visible reply.

Use messages.groupChat.visibleReplies: "message_tool" when visible answers must go through message(action=send). This selects the delivery method, not whether a reply is required. It works best with models that reliably follow tool-only delivery. If the model misses the tool and returns substantive final text, Apus keeps that text private and attempts a bounded delivery recovery rather than posting it directly. Claude CLI runs call the registered tool as mcp__apus__message; the backend explains this mapping and how to discover deferred tools in the system prompt.

Use "automatic" for models or runtimes that do not reliably follow tool-only delivery: normal text finals post directly to the room, and the agent may still call message(action=send) for files, images, or other attachments that cannot ride along with the final text.

If the message tool is unavailable under the active tool policy, Apus falls back to automatic visible replies instead of silently suppressing the response. apus doctor warns about this mismatch.

For direct chats and any other source event, messages.visibleReplies: "message_tool" applies the same tool-only behavior globally; messages.groupChat.visibleReplies remains the more specific override for group/channel rooms. Internal WebChat direct turns default to automatic final-reply delivery so Pi and Codex receive the same visible-reply contract.

Accepted group/channel requests require a reply by default. To permit selective silence for unaddressed requests, explicitly set agents.defaults.silentReply.group: "allow" or the appropriate surfaces.<id>.silentReply.group override; see Silent replies. In "automatic" mode, that opt-in enables NO_REPLY guidance. In tool-only mode, optional turns stay quiet by not calling the message tool; merely selecting tool-only delivery does not waive a required answer.

Plugin-owned conversation bindings are the exception. Once a plugin binds a thread and claims the inbound turn, the plugin's returned reply is the visible binding response; it does not need message(action=send). That reply is plugin runtime output, not private model final text.

Typing indicators are still sent for direct group requests. Ambient always-on room events, when enabled, stay strict and quiet unless the agent calls the message tool.

Sessions suppress verbose tool/progress summaries by default. Use /verbose on (or /verbose full) to show them for the current session while debugging, and /verbose off to return to final-reply-only behavior. Verbose state is per session and works the same in direct chats, groups, channels, and forum topics.

To submit unmentioned always-on group chatter as quiet room context instead of user requests, use Ambient room events:

{
  messages: {
    groupChat: {
      unmentionedInbound: "room_event",
    },
  },
}

The default is unmentionedInbound: "user_request". Mentioned messages, commands, abort requests, and DMs stay user requests.

To require visible output to go through the message tool for group/channel requests:

{
  messages: {
    groupChat: {
      visibleReplies: "message_tool",
    },
  },
}

To require it for every source chat:

{
  messages: {
    visibleReplies: "message_tool",
  },
}

The gateway picks up messages config changes without a restart after the file is saved. Restart only when config reload is disabled (gateway.reload.mode: "off").

Command turns bypass visibleReplies: "message_tool" and always reply visibly: native slash commands (Discord, Telegram, and other surfaces with native command support) and authorized text /... commands both post their response to the source chat. Unauthorized text /... turns in groups stay message-tool-only; ordinary chat turns follow the configured default.

Context visibility and allowlists

Two different controls are involved in group safety:

• Trigger authorization: who can trigger the agent (groupPolicy, groups, groupAllowFrom, channel-specific allowlists).
• Context visibility: what supplemental context is injected into the model (reply/quote text, thread history, forwarded metadata).

By default Apus keeps context as received: allowlists decide who can trigger actions, not what quoted or historical snippets the model sees. To also filter supplemental context, set contextVisibility:

Set it per channel (channels.<channel>.contextVisibility), per account (channels.<channel>.accounts.<accountId>.contextVisibility), or globally (channels.defaults.contextVisibility). Channels that fetch supplemental context (Discord, Feishu, iMessage, Matrix, Mattermost, Microsoft Teams, QQBot, Signal, Slack, Telegram, WhatsApp) apply the policy when building inbound context; unknown policy combinations fail closed and omit the context.

These modes filter channel-supplied supplemental context only. Tool policy and the owner-only tool inventory are still selected from the current turn's originating requester, not every sender represented in the prompt. See Requester-scoped controls and prompt context.

If you want...

For reusable sender allowlists, see Access groups.

Session keys

• By default, group sessions use agent:<agentId>:<channel>:group:<id> session keys (rooms/channels use agent:<agentId>:<channel>:channel:<id>).
• Telegram forum topics add :topic:<threadId> to the group id so each topic has its own session.
• Direct chats use the main session (or per-sender sessions if session.dmScope is configured).
• Heartbeats run in the configured heartbeat session (default: the agent main session); group sessions do not run their own heartbeats.

Set a binding's session.groupScope to "main" when a trusted room should share the agent's main conversation:

{
  bindings: [
    {
      agentId: "main",
      match: { channel: "slack", peer: { kind: "channel", id: "C0123TEAM" } },
      session: { groupScope: "main" },
    },
  ],
}

The global session.groupScope supports "per-group" (default) or "main". This does not change group admission, mention gating, or reply routing.

Pattern: personal DMs + public groups (single agent)

Yes — this works well if your "personal" traffic is DMs and your "public" traffic is groups.

Why: in single-agent mode, DMs typically land in the main session key (agent:main:main), while groups use non-main session keys (agent:main:<channel>:group:<id>) under the default groupScope: "per-group". If you enable sandboxing with mode: "non-main", those group sessions run in the configured sandbox backend while your main DM session stays on-host. Docker is the default backend if you do not choose one.

This gives you one agent "brain" (shared workspace + memory), but two execution postures:

• DMs: full tools (host)
• Groups: sandbox + restricted tools

```json5
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // groups/channels are non-main -> sandboxed
        scope: "session", // strongest isolation (one container per group/channel)
        workspaceAccess: "none",
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        // If allow is non-empty, everything else is blocked (deny still wins).
        allow: ["group:messaging", "group:sessions"],
        deny: ["group:runtime", "group:fs", "group:ui", "nodes", "cron", "gateway"],
      },
    },
  },
}
```

Want "groups can only see folder X" instead of "no host access"? Keep `workspaceAccess: "none"` and mount only allowlisted paths into the sandbox:

```json5
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "session",
        workspaceAccess: "none",
        docker: {
          binds: [
            // hostPath:containerPath:mode
            "/home/user/FriendsShared:/data:ro",
          ],
        },
      },
    },
  },
}
```

Related:

• Configuration keys and defaults: Gateway configuration
• Debugging why a tool is blocked: Sandbox vs Tool Policy vs Elevated
• Bind mounts details: Sandboxing

Display labels

• UI labels use displayName when available, formatted as <channel>:<token>.
• #room is reserved for rooms/channels; group chats use g-<slug> (lowercase, spaces -> -, keep #@+._-). Very long opaque ids are shortened into a stable token instead of leaking full route ids into the UI.

Group policy

Control how group/room messages are handled per channel:

{
  channels: {
    whatsapp: {
      groupPolicy: "disabled", // "open" | "disabled" | "allowlist"
      groupAllowFrom: ["+15551234567"],
    },
    telegram: {
      groupPolicy: "disabled",
      groupAllowFrom: ["123456789"], // numeric Telegram user id (setup resolves @username)
    },
    signal: {
      groupPolicy: "disabled",
      groupAllowFrom: ["+15551234567"],
    },
    imessage: {
      groupPolicy: "disabled",
      groupAllowFrom: ["chat_id:123"],
    },
    msteams: {
      groupPolicy: "disabled",
      groupAllowFrom: ["user@org.com"],
    },
    discord: {
      groupPolicy: "allowlist",
      guilds: {
        GUILD_ID: { channels: { help: { enabled: true } } },
      },
    },
    slack: {
      groupPolicy: "allowlist",
      channels: { "#general": { enabled: true } },
    },
    matrix: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["@owner:example.org"],
      groups: {
        "!roomId:example.org": { enabled: true },
        "#alias:example.org": { enabled: true },
      },
    },
  },
}

- `groupPolicy` is separate from mention-gating (which requires @mentions).
- WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo: use `groupAllowFrom` (fallback: explicit `allowFrom`).
- Signal: `groupAllowFrom` can match either the inbound Signal group id or the sender phone/UUID.
- DM pairing approvals (`*-allowFrom` store entries) apply to DM access only; group sender authorization stays explicit to group allowlists.
- Discord: allowlist uses `channels.discord.guilds.<id>.channels`.
- Slack: allowlist uses `channels.slack.channels`.
- Matrix: allowlist uses `channels.matrix.groups`. Use room IDs (`!room:server`, or the suffixless `!room` form on room version 12+) or aliases (`#alias:server`); room-name keys match only with `channels.matrix.dangerouslyAllowNameMatching: true`, and unresolved entries are ignored at runtime. Use `channels.matrix.groupAllowFrom` to restrict senders; per-room `users` allowlists are also supported.
- Group DMs are controlled separately (`channels.discord.dm.*`, `channels.slack.dm.*`: `groupEnabled`, `groupChannels`).
- Telegram: sender allowlists accept numeric user IDs only (`"123456789"`; `telegram:`/`tg:` prefixes are stripped case-insensitively). `@username` entries do not match at runtime and log a warning; setup resolves `@username` to IDs. Negative chat IDs belong under `channels.telegram.groups`, not sender allowlists.
- Default is `groupPolicy: "allowlist"`; if your group allowlist is empty, group messages are blocked.
- Runtime safety: when a provider block is completely missing (`channels.<provider>` absent), group policy fails closed to `allowlist` instead of inheriting `channels.defaults.groupPolicy`, and the gateway logs the fallback once per account.

Quick mental model (evaluation order for group messages):

`groupPolicy` (open/disabled/allowlist).

Group allowlists (`*.groups`, `*.groupAllowFrom`, channel-specific allowlist).

Mention gating (`requireMention`, `/activation`).

Mention gating (default)

Group messages require a mention unless overridden per group. Defaults live per subsystem under *.groups."*".

Supported implicit mention facts are channel-specific:

Each fact defaults to enabled when the channel produces it. Among bundled channels, LINE, Mattermost, Slack, and Tlon read the corresponding implicitMentions flag; set it to false to stop that fact from bypassing mention gating. LINE reads it from the shared channels.defaults.implicitMentions block only; it does not accept a channel- or account-scoped implicitMentions block of its own. Native explicit mentions remain unaffected. The other bundled producers listed above do not currently read implicitMentions, so their facts always count as mentions and the flag cannot turn them off. A flag also has no effect on channels that do not produce that fact.

{
  channels: {
    whatsapp: {
      groups: {
        "*": { requireMention: true },
        "123@g.us": { requireMention: false },
      },
    },
    telegram: {
      groups: {
        "*": { requireMention: true },
        "123456789": { requireMention: false },
      },
    },
    imessage: {
      groups: {
        "*": { requireMention: true },
        "123": { requireMention: false },
      },
    },
  },
  agents: {
    entries: {
      main: {
        groupChat: {
          mentionPatterns: ["@apus", "apus", "\\+15555550123"],
          historyLimit: 50,
        },
      },
    },
  },
}

Scope configured mention patterns

Configured mentionPatterns are regex fallback triggers. Use them when the platform does not expose a native bot mention, or when you want plain text such as apus: to count as a mention. Native platform mentions are separate: when Discord, Slack, Telegram, Matrix, Signal, or another channel can prove the message explicitly mentioned the bot, that native mention still triggers even if configured regex patterns are denied.

By default, configured mention patterns apply everywhere the channel passes provider and conversation facts into mention detection. To keep broad patterns from waking the agent in every group, scope them per channel with channels.<channel>.mentionPatterns.

Use mode: "deny" when regex mention patterns should be off by default for a channel, then opt in specific rooms with allowIn:

{
  messages: {
    groupChat: {
      mentionPatterns: ["\\bapus\\b", "\\bops bot\\b"],
    },
  },
  channels: {
    slack: {
      mentionPatterns: {
        mode: "deny",
        allowIn: ["C0123OPS"],
      },
    },
  },
}

Use the default mode: "allow" (or omit mode) when regex mention patterns should apply broadly, then turn them off in noisy rooms with denyIn:

{
  messages: {
    groupChat: {
      mentionPatterns: ["\\bapus\\b"],
    },
  },
  channels: {
    telegram: {
      mentionPatterns: {
        denyIn: ["-1001234567890", "-1001234567890:topic:42"],
      },
    },
  },
}

Policy resolution:

Supported scoped regex policy today:

Account-level channel configs can set the same policy under channels.<channel>.accounts.<accountId>.mentionPatterns when that channel supports multiple accounts. Account policy takes precedence over the top-level channel policy for that account.

- `mentionPatterns` are case-insensitive safe regex patterns; invalid patterns and unsafe nested-repetition forms are ignored (with a warning).
- Pattern precedence: `agents.entries.*.groupChat.mentionPatterns` (useful when multiple agents share a group) overrides `messages.groupChat.mentionPatterns`; when neither is set, patterns are derived from the routed agent's `identity.name` and `identity.emoji`. An explicit `mentionPatterns: []` at the selected level suppresses this derivation; native mentions remain separate.
- Mention gating can apply without explicitly configured patterns: identity-derived patterns also enable detection. On channels that require detectable mentions before gating, only the absence of both usable patterns and native mention support prevents enforcement.
- Allowlisting a group or sender does not disable mention gating; set that group's `requireMention` to `false` when all messages should trigger.
- Automatic group chat prompt context includes `NO_REPLY` guidance only when the resolved silence policy explicitly allows it; workspace files should not duplicate these mechanics.
- Groups explicitly configured to allow automatic silent replies treat clean empty or reasoning-only model turns as silent, equivalent to `NO_REPLY`. Direct chats never receive `NO_REPLY` guidance, and optional message-tool-only group turns stay quiet by not calling `message(action=send)`.
- Always-on group messages use user-request semantics and require replies by default. Set `messages.groupChat.unmentionedInbound: "room_event"` to submit them as quiet context instead. See [Ambient room events](/channels/ambient-room-events) for supported channels and setup examples.
- Room events are not stored as fake user requests, and private assistant text from no-message-tool room events is not replayed as chat history.
- Discord defaults live in `channels.discord.guilds."*"` (overridable per guild/channel).
- Group history context is wrapped uniformly across channels. Mention-gated groups keep pending skipped messages; always-on groups may also retain recent processed room messages when the channel supports it. Use `messages.groupChat.historyLimit` for the global default and `channels.<channel>.historyLimit` (or `channels.<channel>.accounts.*.historyLimit`) for overrides. Set `0` to disable.

Group/channel tool restrictions (optional)

Some channel configs support restricting which tools are available inside a specific group/room/channel.

• tools: allow/deny tools for the whole group (allow, alsoAllow, deny; deny wins).
• toolsBySender: per-sender overrides within the group. Use explicit key prefixes: channel:<channelId>:<senderId>, id:<senderId>, e164:<phone>, username:<handle>, name:<displayName>, and "*" wildcard. Channel ids use canonical Apus channel ids; aliases such as teams normalize to msteams. Run apus doctor --fix to migrate retired unprefixed keys to id: entries before starting the Gateway.

When a sender or group policy restricts the turn's tools, that requester can create only hidden helpers of the same agent. Visible and cross-agent sessions are refused, including through ACP or automatic session creation by sessions_send. Helpers retain the restricted tools and the requester's workspace and session root. The restriction follows delegated and queued turns; an unrestricted sender's later turn does not replace it. Owner-authorized automations retain their separate scheduling policy and workspace.

Resolution order (most specific wins):

Group/channel `toolsBySender` match.

Group/channel `tools`.

Default (`"*"`) `toolsBySender` match.

Default (`"*"`) `tools`.

Example (Telegram):

{
  channels: {
    telegram: {
      groups: {
        "*": { tools: { deny: ["exec"] } },
        "-1001234567890": {
          tools: { deny: ["exec", "read", "write"] },
          toolsBySender: {
            "id:123456789": { alsoAllow: ["exec"] },
          },
        },
      },
    },
  },
}

Group allowlists

When channels.whatsapp.groups, channels.telegram.groups, or channels.imessage.groups is configured, the keys act as a group allowlist. Use "*" to allow all groups while still setting default mention behavior.

Common intents (copy/paste):

```json5
{
  channels: { whatsapp: { groupPolicy: "disabled" } },
}
```

```json5
{
  channels: {
    whatsapp: {
      groups: {
        "123@g.us": { requireMention: true },
        "456@g.us": { requireMention: false },
      },
    },
  },
}
```

```json5
{
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}
```

```json5
{
  channels: {
    whatsapp: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
      groups: { "*": { requireMention: true } },
    },
  },
}
```

Activation (owner-only)

Group owners can toggle per-group activation with a standalone message:

• /activation mention
• /activation always

/activation is a core owner-gated command and only applies in group chats. Owner means the sender matches commands.ownerAllowFrom; channel allowFrom lists only control ordinary channel and command access. The stored mode overrides that group's requireMention on channels that consult it (Google Chat, QQBot, Telegram, WhatsApp), and the group system-prompt intro reflects the active mode everywhere.

Context fields

Group inbound payloads set:

• ChatType=group
• GroupSubject (if known)
• GroupMembers (if known)
• WasMentioned (mention gating result)
• Telegram forum topics also include MessageThreadId and IsForum.

The agent system prompt includes a group intro on the first turn of a new group session (and after /activation changes). It reminds the model to respond like a human, minimize empty lines and follow normal chat spacing, and avoid typing literal \n sequences. Channels whose declared table mode does not preserve native or raw tables also discourage Markdown tables. Channel-sourced group names and participant labels are rendered as fenced untrusted metadata, not inline system instructions.

iMessage specifics

• Prefer chat_id:<id> when routing or allowlisting.
• List chats: imsg chats --limit 20.
• Group replies always go back to the same chat_id.

Related

• Broadcast groups
• Channel routing
• Group messages — WhatsApp-only behavior (history injection, mention handling details)
• Pairing
• WhatsApp — canonical WhatsApp system prompt rules, including group and direct prompt resolution, wildcard behavior, and account override semantics