Skip to main content

​
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
Group message flow If you want…
GoalWhat to set
Allow all groups but only reply on @mentionsgroups: { "*": { requireMention: true } }
Disable all group repliesgroupPolicy: "disabled"
Only specific groupsgroups: { "<group-id>": { ... } } (no "*" key)
Only you can trigger in groupsgroupPolicy: "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.
Example (DMs on host, groups sandboxed + messaging-only tools): 
{
  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: 
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "session",
        workspaceAccess: "none",
        docker: {
          binds: [
            // hostPath:containerPath:mode
            "~/FriendsShared:/data:ro"
          ]
        }
      }
    }
  }
}
Related:

​
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: 
{
  channels: {
    telegram: {
      groupPolicy: "disabled", // "open" | "disabled" | "allowlist"
      groupAllowFrom: ["123456789", "@username"]
    }
  }
}
PolicyBehavior
"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). 
{
  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): 
{
  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
{
  channels: { telegram: { groupPolicy: "disabled" } }
}
  1. Allow only specific groups (Telegram)
{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": { requireMention: true },
        "-1009876543210": { requireMention: false }
      }
    }
  }
}
  1. Allow all groups but require mention (explicit)
{
  channels: {
    telegram: {
      groups: { "*": { requireMention: true } }
    }
  }
}
  1. Only the owner can trigger in groups (Telegram)
{
  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 for Telegram-specific behavior (history injection, mention handling details).