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

# Groups

# Groups

crocbot treats group chats consistently for Telegram.

## Beginner intro (2 minutes)

crocbot "lives" on your own messaging accounts via the Telegram Bot API.
If your bot is in a group, crocbot can see that group and respond there.

Default behavior:

* Groups are restricted (`groupPolicy: "allowlist"`).
* Replies require a mention unless you explicitly disable mention gating.

Translation: allowlisted senders can trigger crocbot by mentioning it.

> TL;DR
>
> * **DM access** is controlled by `*.allowFrom`.
> * **Group access** is controlled by `*.groupPolicy` + allowlists (`*.groups`, `*.groupAllowFrom`).
> * **Reply triggering** is controlled by mention gating (`requireMention`, `/activation`).

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
otherwise -> reply
```

<img src="https://mintcdn.com/aiwithapex/HKEPRC_4qDeejY5S/images/groups-flow.svg?fit=max&auto=format&n=HKEPRC_4qDeejY5S&q=85&s=a67590caecfe7e358c771dda94904d1d" alt="Group message flow" width="960" height="260" data-path="images/groups-flow.svg" />

If you want...

| Goal                                         | What to set                                                 |
| -------------------------------------------- | ----------------------------------------------------------- |
| Allow all groups but only reply on @mentions | `groups: { "*": { requireMention: true } }`                 |
| Disable all group replies                    | `groupPolicy: "disabled"`                                   |
| Only specific groups                         | `groups: { "<group-id>": { ... } }` (no `"*"` key)          |
| Only you can trigger in groups               | `groupPolicy: "allowlist"`, `groupAllowFrom: ["123456789"]` |

## Session keys

* Group sessions use `agent:<agentId>:telegram:group:<id>` session keys.
* 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 if configured).
* Heartbeats are skipped for group sessions.

## 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 always use **non-main** session keys (`agent:main:telegram:group:<id>`). If you enable sandboxing with `mode: "non-main"`, those group sessions run in Docker while your main DM session stays on-host.

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

* **DMs**: full tools (host)
* **Groups**: sandbox + restricted tools (Docker)

> If you need truly separate workspaces/personas ("personal" and "public" must never mix), use a second agent + bindings. See [Multi-Agent Routing](/concepts/multi-agent).

Example (DMs on host, groups sandboxed + messaging-only tools):

```json5 theme={null}
{
  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 theme={null}
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "session",
        workspaceAccess: "none",
        docker: {
          binds: [
            // hostPath:containerPath:mode
            "~/FriendsShared:/data:ro"
          ]
        }
      }
    }
  }
}
```

Related:

* Configuration keys and defaults: [Gateway configuration](/gateway/configuration#agentsdefaultssandbox)
* Debugging why a tool is blocked: [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated)
* Bind mounts details: [Sandboxing](/gateway/sandboxing#custom-bind-mounts)

## 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 `#@+._-`).

## Group policy

Control how group/room messages are handled:

```json5 theme={null}
{
  channels: {
    telegram: {
      groupPolicy: "disabled", // "open" | "disabled" | "allowlist"
      groupAllowFrom: ["123456789", "@username"]
    }
  }
}
```

| Policy        | Behavior                                                     |
| ------------- | ------------------------------------------------------------ |
| `"open"`      | Groups bypass allowlists; mention-gating still applies.      |
| `"disabled"`  | Block all group messages entirely.                           |
| `"allowlist"` | Only allow groups/rooms that match the configured allowlist. |

Notes:

* `groupPolicy` is separate from mention-gating (which requires @mentions).
* Telegram: use `groupAllowFrom` to restrict senders.
* Telegram allowlist can match user IDs (`"123456789"`, `"telegram:123456789"`, `"tg:123456789"`) or usernames (`"@alice"` or `"alice"`); prefixes are case-insensitive.
* Default is `groupPolicy: "allowlist"`; if your group allowlist is empty, group messages are blocked.

Quick mental model (evaluation order for group messages):

1. `groupPolicy` (open/disabled/allowlist)
2. group allowlists (`*.groups`, `*.groupAllowFrom`)
3. mention gating (`requireMention`, `/activation`)

## Mention gating (default)

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

Replying to a bot message counts as an implicit mention (when the channel supports reply metadata).

```json5 theme={null}
{
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: true },
        "123456789": { requireMention: false }
      }
    }
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@croc", "crocbot"],
          historyLimit: 50
        }
      }
    ]
  }
}
```

Notes:

* `mentionPatterns` are case-insensitive regexes.
* Surfaces that provide explicit mentions still pass; patterns are a fallback.
* Per-agent override: `agents.list[].groupChat.mentionPatterns` (useful when multiple agents share a group).
* Mention gating is only enforced when mention detection is possible (native mentions or `mentionPatterns` are configured).
* Group history context is wrapped uniformly and is **pending-only** (messages skipped due to mention gating); use `messages.groupChat.historyLimit` for the global default and `channels.telegram.historyLimit` (or `channels.telegram.accounts.*.historyLimit`) for overrides. Set `0` to disable.

## Group/channel tool restrictions (optional)

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

* `tools`: allow/deny tools for the whole group.
* `toolsBySender`: per-sender overrides within the group (keys are sender IDs/usernames). Use `"*"` as a wildcard.

Resolution order (most specific wins):

1. group/channel `toolsBySender` match
2. group/channel `tools`
3. default (`"*"`) `toolsBySender` match
4. default (`"*"`) `tools`

Example (Telegram):

```json5 theme={null}
{
  channels: {
    telegram: {
      groups: {
        "*": { tools: { deny: ["exec"] } },
        "-1001234567890": {
          tools: { deny: ["exec", "read", "write"] },
          toolsBySender: {
            "123456789": { alsoAllow: ["exec"] }
          }
        }
      }
    }
  }
}
```

Notes:

* Group/channel tool restrictions are applied in addition to global/agent tool policy (deny still wins).

## Group allowlists

When `channels.telegram.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):

1. Disable all group replies

```json5 theme={null}
{
  channels: { telegram: { groupPolicy: "disabled" } }
}
```

2. Allow only specific groups (Telegram)

```json5 theme={null}
{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": { requireMention: true },
        "-1009876543210": { requireMention: false }
      }
    }
  }
}
```

3. Allow all groups but require mention (explicit)

```json5 theme={null}
{
  channels: {
    telegram: {
      groups: { "*": { requireMention: true } }
    }
  }
}
```

4. Only the owner can trigger in groups (Telegram)

```json5 theme={null}
{
  channels: {
    telegram: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["123456789"],
      groups: { "*": { requireMention: true } }
    }
  }
}
```

## Activation (owner-only)

Group owners can toggle per-group activation:

* `/activation mention`
* `/activation always`

Owner is determined by `channels.telegram.allowFrom`. Send the command as a standalone message.

## 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. It reminds the model to respond like a human, avoid Markdown tables, and avoid typing literal `\n` sequences.

## Telegram specifics

See [Group messages](/concepts/group-messages) for Telegram-specific behavior (history injection, mention handling details).