Communication access controls where an Agent may participate, who may interact with it, and which messages are eligible for a response. These policies belong to a Communication Connection.
They are not fields on the Agent. Each Platform Plugin defines and validates its own settings schema, so the available controls depend on the Connection's Platform rather than on the Agent or its Runtime.
Overview
- Channel and message access policies belong to a Communication Connection.
- They are not fields on the Agent.
- Each Platform Plugin defines and validates its own settings schema.
- One Agent can have several Connections with different policies.
- Multiple Connections for the same Platform may use different policies.
- Policy changes do not alter the Agent Runtime.
There are no Slack channel IDs, Slack DM user IDs, Discord guild or channel IDs, Platform-wide direct-message settings, routing fields, or universal mention settings stored on the Agent. Every one of those lives on a Connection.
See Communication Connections for the Connection lifecycle, and Configure an Agent for where Connections sit in Agent configuration.
Access model
Four separate boundaries apply. Passing one does not bypass another.
- Agent Access Which Organization Members can view, configure, share, start, stop, or otherwise manage the Agent inside Agent Barn
- Connection management permissions Who can create or edit Connections, and who may create, replace, or retire their encrypted credentials
- Provider permissions What the installed Slack app, Teams bot, Telegram bot, or Discord bot can see and do at the provider
- Connection message policies Which provider-side channels, groups, servers, users, roles, or conversations Agent Barn admits
Agent Access is managed through Share on the Agent, and is documented in Share access to an Agent. It never determines who may talk to the Agent on a provider, and a provider policy never grants authority inside Agent Barn.
Shared-space and direct-message patterns
The shipped plugins share a common schema pattern for shared spaces:
open: accept otherwise eligible messages from any shared space where the provider bot is installed and authorized.allowlist: accept messages only from configured provider identifiers.
open does not override provider-side membership or permissions. It only widens what Agent Barn admits from places the bot can already reach.
The label differs by Platform:
| Platform | Label |
|---|---|
| Slack | Channel access |
| Microsoft Teams | Channel access |
| Telegram | Group access |
| Discord | Channel access, with Allowed servers as the primary shared-space boundary |
Direct messages
Direct-message policy uses three values on every shipped plugin:
off: ignore direct messagesopen: accept direct messages from any provider userallowlist: accept direct messages only from configured provider user IDs
Direct messages are configured independently for each Connection and default to off on the shipped Platform Plugins. Provider-side direct-message availability and Agent Barn admission must both permit the conversation, and mention requirements generally do not apply to direct messages.
Platform policy comparison
| Platform | Shared-space scope | DM allowlist field | Mention behavior | Additional restrictions |
|---|---|---|---|---|
| Slack | Open or allowlisted channel IDs | Slack user IDs | A direct mention starts channel interaction; thread replies follow every_message or start_only | Connection-owned thread state |
| Microsoft Teams | Open or allowlisted channel conversation IDs | Microsoft Entra object IDs | Group and channel messages require an explicit mention | Teams conversation IDs are case-sensitive |
| Telegram | Open or allowlisted group and chat IDs | Numeric Telegram user IDs | No universal Agent Barn mention gate; Telegram privacy mode controls which group messages reach the bot | Group and supergroup IDs are often negative |
| Discord | Open or allowlisted server IDs, optionally narrowed to channel IDs | Discord user IDs | Configurable with Require mention; enabled by default for server messages | Optional user and role restrictions |
These differences come from the Platform Plugins, not from the Agent's Runtime. Runtime selection does not determine which channel policies are available.
Before you begin
You need:
- Access to the Organization that owns the Agent
- Visibility of the Agent
- Agent update permission, to edit a Connection's policies
- Agent secret-management permission, when credentials are also being changed
- The provider identifiers you intend to allow
- Provider-side membership for the bot in each intended location
- A controlled location for testing an allowed and a blocked message
You do not need lifecycle permission to change an access policy, because a policy edit does not restart the Agent.
Recommended baseline
Start narrow, then widen deliberately.
Shared-space policy: allowlist
Allowed identifiers: One controlled test location
Direct messages: off
Mention gating: Enabled where the Platform supports it- Begin with allowlists and direct messages set to
off. - Confirm the intended provider IDs before saving.
- Enable broader access only when it is deliberate.
- Keep provider-side bot membership and permissions as narrow as practical.
- Use Connection diagnostics to observe policy rejections before broadening access.
- Treat provider policy changes and Agent Access changes as separate reviews.
Open the Connection settings
Policies live on the Connection, not on the Agent's profile.
- Open the Organization that owns the Agent.
- Open the Agent.
- Open Configuration.
- Open Messaging.
- Select the Communication Connection you want to change.
Each Connection carries its own policy set. Changing one Connection never changes another, even when both use the same Platform.
Configure Slack
| Setting | Values |
|---|---|
group_policy | open or allowlist |
channel_ids | Allowed Slack channel IDs |
dm_policy | off, open, or allowlist |
dm_user_ids | Allowed Slack DM sender IDs |
thread_mention_policy | every_message or start_only |
How Slack admission works:
- New channel interaction requires a direct bot mention.
every_messagerequires a mention on every channel message, including thread replies.start_onlyallows unmentioned replies only in threads already owned by the same Agent and Connection.- Direct messages do not require mentions but must pass the direct-message policy.
Thread ownership is durable and Connection-scoped, so a thread started through one Connection does not become answerable through another. See Set up Slack.
Configure Microsoft Teams
| Setting | Values |
|---|---|
group_policy | open or allowlist |
channel_ids | Allowed Teams conversation IDs |
dm_policy | off, open, or allowlist |
dm_user_ids | Allowed Microsoft Entra sender object IDs |
How Teams admission works:
- Group-chat and channel messages require a bot mention.
- Direct messages do not require a mention.
- Personal scope remains governed by the configured direct-message policy.
Teams channel conversation IDs commonly resemble 19:...@thread.tacv2 and must retain their original case. A re-cased identifier will not match. See Connect an Agent to Microsoft Teams.
Configure Telegram
| Setting | Values |
|---|---|
group_policy | open or allowlist |
allowed_chat_ids | Allowed group, supergroup, or channel IDs |
dm_policy | off, open, or allowlist |
allowed_user_ids | Allowed Telegram DM sender IDs |
How Telegram admission works:
- Policies use numeric provider IDs, not usernames.
- Group and supergroup IDs are commonly negative.
- Telegram privacy mode determines which group messages Telegram sends to the bot.
- Agent Barn evaluates the Connection policy only after Telegram delivers the update.
- Direct messages are governed independently by
dm_policy. - Telegram does not use Slack's thread mention policy.
Configure Discord
| Setting | Values |
|---|---|
group_policy | open or allowlist |
guild_ids | Allowed Discord servers |
allowed_channel_ids | Optional channel restriction |
allowed_user_ids | Optional user restriction and DM allowlist |
allowed_role_ids | Optional role restriction |
dm_policy | off, open, or allowlist |
require_mention | Whether server messages must mention the bot |
A Discord server message is evaluated in order:
- Approved server Channel access is open, or the server ID appears in Allowed servers
- Approved channel Allowed channels is empty, or the channel ID is listed
- Allowed user or role The sender is an allowed user, or holds at least one allowed role
- Mention satisfied The message mentions the bot, while Require mention is enabled
For direct messages:
offrejects direct messages.openaccepts provider-eligible direct messages.allowlistrequires the sender in Allowed users.require_mentiondoes not apply.
Save the policy change
Policy edits update the Communication Connection, not the Agent.
- Updates use the Connection revision for optimistic concurrency.
- The Communications Gateway reconciles the provider session independently.
- The Agent Runtime is not rebuilt or restarted.
- Existing accepted Conversation history remains scoped to the Connection.
- Disabling a Connection stops new provider traffic without changing the Agent lifecycle.
If a save is rejected for a stale revision, reload the Connection and reapply the change.
Verify the boundaries
Test one allowed and one blocked interaction for each policy you changed.
| Test | Expected result |
|---|---|
| Eligible message from an allowed location | The Agent responds |
| Message from a location outside the allowlist | The Agent does not respond |
| Message from a sender outside the user or role policy | The Agent does not respond |
Direct message while the policy is off | The Agent does not respond |
| Unmentioned shared-space message while mention gating applies | The Agent does not respond |
Confirm the accepted exchange appears in Agent Activity under the expected Connection, and confirm the blocked message produced no canonical Conversation Message.
Provider IDs and directory discovery
Policy lists persist provider IDs rather than names. A display name is never an access identifier.
- Slack can browse channels and active users.
- Discord can browse servers and, after choosing a server, its message channels, human members, and non-default roles.
- Manual ID entry remains supported.
- Directory selection writes only provider IDs.
- Directory lookups are credential-scoped.
- Display-name enrichment does not replace stable provider IDs.
Telegram and Microsoft Teams do not currently offer the same browsable directory picker as Slack and Discord, so collect their identifiers from the provider and enter them manually.
Policy evaluation and diagnostics
An inbound message follows this path:
- The provider supplies an event or activity.
- The Platform Plugin normalizes it.
- The Connection's provider-specific admission policy is evaluated.
- Only accepted messages create inbound Communication Deliveries.
- Rejected messages are recorded as policy-rejected journal activity without creating an inbound Delivery.
The Connection journal records a disposition for each decision:
| Disposition | Meaning |
|---|---|
accepted | The message passed policy and created an inbound Delivery |
bot_ignored | The author was a bot, so the message was skipped |
event_ignored | The provider event type is not handled as an inbound message |
mention_required | A mention was required but not present |
user_denied | The sender did not pass the user or role policy |
channel_denied | The channel, chat, or server did not pass the shared-space policy |
malformed_payload | The provider payload could not be normalized |
Use these to distinguish a policy rejection from a Runtime failure or an outbound-delivery failure. Runtime logs alone will not show an access-policy rejection, because the message never reached the Runtime.
Troubleshooting
Nothing appears in the Connection journal
The provider never delivered the message. Check provider-side installation and permissions, Telegram privacy mode for group messages, and the Connection's own health.
The disposition is mention_required
The message reached Agent Barn but carried no mention where one is required. For Slack, check thread_mention_policy; for Discord, check require_mention; for Teams, a mention is required in group and channel conversations.
The disposition is channel_denied
The shared-space policy rejected the location. Compare the exact provider identifier against the allowlist, including the leading minus sign for Telegram and the original case for Teams.
The disposition is user_denied
The sender failed the user or role policy. For Discord, remember that an allowed role is sufficient on its own. For direct messages, check the direct-message policy and the allowed sender list.
An identifier looks correct but never matches
Confirm you stored a provider ID rather than a name, and that it was copied without truncation or case changes. Re-read it from the provider or from a directory picker where one is available.
The message is accepted but no reply arrives
Admission succeeded, so this is not an access-policy problem. Review Agent Runtime health, then the Connection's outbound delivery diagnostics.
A policy change did not take effect
Confirm the save succeeded and the Connection revision advanced, and confirm you edited the Connection actually serving that location. Do not restart the Agent: policy reconciliation happens in the Communications Gateway.
Next steps
- Review the Connection lifecycle
- Configure an Agent for the surrounding configuration surface
- Share access to an Agent for the separate Agent Access boundary
- Verify your Agent after changing a policy
- Provider setup: Slack, Microsoft Teams, Telegram, and Discord