--- title: Connect a communication platform canonical: "https://agentbarn.dev/guides/get-started/connect-a-platform" pubDate: "2026-08-29T00:00:00.000Z" updatedDate: "2026-09-14T04:31:13.000Z" author: Agent Barn description: "Connect an Agent to Slack, Teams, Telegram, Discord, or deployment-enabled Email, or use built-in Web Chat." tags: [Get started, Guide, "Agent operators, Organization owners, and Organization administrators", Email, Web Chat, external Platform Plugins, Communication Connection, Slack, Teams, Telegram, Discord] categories: [Guides, Get started] --- A newly hired Agent is headless. It runs, executes its Template, and uses its Skills, and can use built-in Web Chat once Running and Working. External messaging is configured separately. A Communication Connection is what gives the Agent a place to listen and reply. This guide takes one existing Agent from headless to its first enabled Communication Connection, then verifies one allowed and one blocked interaction. ## What you will accomplish By the end of this guide, you will have: - Added a Communication Connection to an existing Agent - Selected a shipped Platform Plugin and named the Connection clearly - Configured a narrow initial access policy - Completed the selected provider’s credential or deployment setup - Confirmed the Connection is enabled and healthy - Tested one allowed and one blocked interaction ## Overview Every Agent is created headless. Hiring an Agent does not select or configure a Communication Platform, so communication is always a separate, later step. A Communication Connection links one Agent to one provider-side bot, application, account, or endpoint. - An Agent may own zero or many Communication Connections. - An Agent may own several Connections for the same Platform. - Communication Connections are independent of whether the Agent uses Hermes or OpenClaw. - Both Runtimes use the same runtime-neutral Communications protocol. - Adding a Connection does not require recreating or changing the Agent's Runtime. For the complete ownership and lifecycle model, see [Communication Connections](/guides/agents/communication-connections). ## Before you begin You need: - An active Organization - Access to the Agent - Agent update permission - Agent secret-management permission when provider credentials are created, replaced, or retired - Provider setup for the selected Platform: bot/application credentials, or deployment-enabled Email - The credentials required by that Platform Plugin - Permission for the provider setup required by the selected plugin - At least one controlled channel, chat, server, team, or direct-message scope for testing **Security** Provider credentials must be entered only into the Connection credential fields. Never place credentials in an Agent name, Template, Skill, description, screenshot, documentation page, or chat message. Communication credentials are separate from Agent Secrets used for tool Integrations. ## Choose a Platform Agent Barn ships five external Platform Plugins: Slack, Microsoft Teams, Telegram, Discord, and Email. Email requires deployment configuration before a Connection can be created. Built-in Web Chat is a separate dashboard option that needs no external provider credentials. | Platform | Provider identity | Ingress model | | --- | --- | --- | | Slack | Slack application with bot and app-level tokens | Supervised Socket Mode | | Microsoft Teams | Azure Bot and Teams application | Authenticated provider webhook | | Telegram | Telegram bot | Supervised polling | | Discord | Discord application and bot | Supervised Gateway session | | Email | Allocated address; deployment-managed credentials | Cloudflare Email Worker to authenticated Communications inbound route | Platform support is independent of Runtime selection. The external plugins can connect Agents using Hermes or OpenClaw. Their capabilities differ; support for inbound messages and replies does not imply support for independently initiated delivery. Platform choice does not change the Agent's Template, model, Skills, Integrations, Runtime, or lifecycle. Detailed provider preparation belongs to the corresponding Platform guide: [Slack](/guides/platforms/slack), [Microsoft Teams](/guides/platforms/microsoft-teams), [Telegram](/guides/platforms/telegram), [Discord](/guides/platforms/discord), and [Email](/guides/platforms/email). ## Open Communication Connections 1. Select the Organization that owns the Agent. 2. Open the Agent. 3. Open **Configuration**. 4. Find **Communication Connections**. 5. Select **Add connection**. Communication Connections are managed independently from **Profile**, **Template**, **Skills**, **Keys & integrations**, and Agent Template Overrides. Adding communication to an existing Agent never means going back through the hire flow. ## Select the Platform Plugin 1. Select Slack, Microsoft Teams, Telegram, Discord, or deployment-enabled Email. 2. Review the Platform Plugin's setup guidance. 3. Choose the provider's setup path. Slack, Teams, Telegram, and Discord require their provider credentials. Email requires deployment-enabled sending and inbound routing and allocates an address when the Connection is created. Follow the selected plugin's setup guidance rather than entering credentials it does not request. 4. Enter a descriptive Connection name. Use a name that identifies the provider environment or purpose, such as: - `Slack: Support workspace` - `Discord: Community server` - `Teams: Operations tenant` - `Telegram: Incident bot` The name identifies the Connection inside Agent Barn. It does not automatically rename the provider-side application. ## Configure Connection settings The settings form is supplied by the selected Platform Plugin, so it is schema-driven and the exact fields differ by Platform. Depending on the Platform, settings may include: - Open or allowlisted shared-space access - Channel, chat, server, team, user, or role identifiers - Direct-message policy - Mention policy - Thread behavior - Default delivery target where initiated delivery is supported - Provider-specific behavior such as response verbosity These settings belong to the Connection rather than the Agent, so two Connections on the same Agent can carry completely different policies. **Important** Policy in Agent Barn and presence in the provider are two different things. A provider application must still be installed, invited, or added to each permitted provider location, an allowlist does not install the provider application, and provider-side permissions remain effective even when Agent Barn policy is open. Start with the narrowest usable access policy: one test location, no open direct messages, and mentions required where the Platform supports it. You can widen it after the first successful exchange. ## Enter credentials The selected Platform Plugin defines the credential fields. In summary: | Platform | Connection credentials | | --- | --- | | Email | No per-Connection provider credentials. Cloudflare sending credentials and the inbound secret belong to the deployment. The Connection receives an allocated address and sender policy. | | Slack | A bot token with the `xoxb-` prefix and an app-level token with the `xapp-` prefix | | Microsoft Teams | Application ID, application password, and tenant ID | | Telegram | Bot token | | Discord | Bot token | For Slack, configuration access tokens and configuration refresh tokens are not used, and Agent Barn does not automatically create a Slack application. Prepare the Slack application yourself, then bring its tokens here. Communication credentials are encrypted, and plaintext credentials are not returned by read operations. Provider credentials remain inside the Communications boundary: Hermes and OpenClaw never receive them. ## Save the Connection 1. Review the Connection name. 2. Review the selected Platform. 3. Review the access settings. 4. Enter credentials only where the selected plugin requests them. 5. Save the Connection. Saving may perform provider credential validation, so expect a short pause while the provider is contacted. After saving, review: - Whether the Connection is enabled - Its revision - Its observed provider health - Any provider-specific setup instructions - Suggested provider directory values, where supported **Note** A validation error belongs to the Connection workflow. It does not mean the Agent Runtime failed. ## Complete provider-side setup Saving the Connection configures Agent Barn. Depending on the Platform, you may still need to: - Install or add the provider application - Invite the bot to private locations - Enable required provider permissions, scopes, events, or intents - Enable Microsoft Teams as an Azure Bot channel - Configure the Microsoft Teams messaging endpoint - Disable Telegram Group Privacy when the intended workflow requires provider delivery of group messages - Enable Discord Message Content Intent - Enable Discord Server Members Intent when member or role discovery is used - Enable Slack Socket Mode - Install or reinstall a Slack application after changing OAuth scopes Follow the guide for your Platform for the exact provider steps: [Set up Slack](/guides/platforms/slack), [Set up Microsoft Teams](/guides/platforms/microsoft-teams), [Set up Telegram](/guides/platforms/telegram), or [Set up Discord](/guides/platforms/discord). ### Microsoft Teams messaging endpoint Microsoft Teams is the one Platform that needs public provider ingress. Its messaging endpoint is Connection-scoped and uses this shape: ``` https://AGENT_BARN_HOST/communications/v1/webhooks/CONNECTION_ID ``` Use the Connection's own identifier, not the Agent's. The Teams app package may be downloadable from the Connection when the Platform Plugin exposes application provisioning. Complete Azure Bot and Teams application instructions belong to [Set up Microsoft Teams](/guides/platforms/microsoft-teams). ## Confirm the Connection is enabled Check the state shown on the Connection rather than assuming it, then enable it if it is not already enabled. - An enabled Connection is eligible for provider ingress and outbound delivery. - A disabled Connection preserves its configuration and history but does not actively participate. - Enabling or disabling a Connection does not start, stop, or restart the Agent Runtime. Connection health remains separate from Agent lifecycle. A running Agent can have both healthy and unhealthy Connections, and one failed Connection does not disable the Agent's other Connections. ## Test the Connection Verify one allowed and one blocked interaction before widening any policy. 1. Confirm the Agent Runtime is running. 2. Confirm the Connection is enabled. 3. Confirm the Connection does not show a provider error. 4. Add or install the provider application in a controlled test location. 5. Send one message that satisfies the configured access and mention policy. 6. Confirm the Agent responds through the same Connection. 7. Send one message that should be rejected by the configured policy. 8. Confirm the Agent does not respond. 9. Open Agent Activity and confirm the allowed Conversation appears under the expected Connection and location. **Expected:** the allowed message produces a reply in the same location, the blocked message produces nothing, and the allowed exchange is visible in Agent Activity. A Conversation is scoped by both Connection ID and provider channel identifier, so check that the Conversation you find is the one from this Connection. **Note** Tool Calls are a separate Runtime telemetry path. Use Conversation Messages, not Tool Calls, as evidence that provider delivery succeeded. ## How messages stay isolated Connections on the same Agent do not blur together. - Every canonical Conversation Message records its source Connection. - Provider message identity is unique within the Connection. - Conversation location identity includes both `connection_id` and `channel_id`. - Replies are delivered through the Connection that produced the inbound source delivery. - Two Connections may safely use the same provider channel identifier. - An Agent with several Connections does not merge their provider identities or access policies. Delivery internals are covered in the architecture and diagnostics guides. ## Change a Connection later Connection settings and credentials can be changed independently of each other and of the Agent. - Updates use the current Connection revision. - Saving a change increments the revision. - The Communications Gateway reconciles its provider session. - Connection-only updates do not require **Apply & Restart**. - A stale revision should be refreshed before retrying. Updating a Connection does not change the Agent's Runtime, model, Template, Skills, Integrations, or Agent Access. Leave the Agent running while you edit a Connection. ## Completion checklist Confirm that you have: - Selected the correct Agent - Chosen a shipped Platform Plugin - Named the Connection clearly - Configured a narrow initial access policy - Completed the selected provider’s credential or deployment setup - Completed provider-side installation or membership - Confirmed the Connection is enabled - Confirmed provider health separately from Agent health - Tested one allowed interaction - Tested one blocked interaction - Confirmed the Conversation appears under the expected Connection ## Troubleshooting ### Credentials are rejected Check the Platform, the format, and the provider configuration - Confirm the token or application values belong to the selected Platform. - Confirm the credential format. - Confirm required scopes, channels, intents, or tenant configuration. Replace credentials through the Connection rather than through Agent **Keys & integrations**. ### The Connection remains disconnected or in error Review Connection health before touching the Agent - Review Connection health. - Review provider-specific setup guidance. - Confirm the application or bot is enabled in the provider. - Confirm the relevant Socket Mode, polling, Gateway, or webhook path is available. Do not restart the Agent unless there is a separate Runtime problem. ### The Agent is running but does not respond Check the Connection, the install, and the policy - Confirm the Connection is enabled. - Confirm the provider application is installed in the location. - Confirm the message satisfies allowlists, user or role policy, direct-message policy, and mention policy. - Confirm the Connection is healthy. Keep provider delivery diagnosis separate from Agent Runtime health. ### The message appears but no reply is delivered Check the Runtime, delivery state, and outbound permissions - Confirm the Runtime is running. - Review Connection diagnostics and delivery state. - Confirm outbound provider permissions. - Confirm the source Connection remains enabled. ### A directory entry does not appear Check credentials, visibility, and provider intents - Confirm credentials are valid. - Confirm the bot can see the provider location. - Confirm required provider intents or scopes. Use the provider's stable identifier when the interface permits manual entry. ### Another Organization Member cannot edit the Connection Check Agent Access and secret-management permission - Confirm they can access the Agent. - Confirm their effective Agent Access includes Agent update permission. - Confirm they have Agent secret-management permission when changing credentials. ## Next steps - [Verify your Agent](/guides/get-started/verify-agent) against its operational signals - Review the full [Communication Connection](/guides/agents/communication-connections) lifecycle - Tighten or widen [channel access](/guides/agents/channel-access) for the Connection - Review Agent [health and logs](/guides/agents/health-and-logs) separately from Connection health - Complete provider setup with [Slack](/guides/platforms/slack), [Microsoft Teams](/guides/platforms/microsoft-teams), [Telegram](/guides/platforms/telegram), or [Discord](/guides/platforms/discord) ## Email and Web Chat Agent Barn ships external Platform Plugins for Slack, Microsoft Teams, Telegram, Discord, and Email, plus built-in Web Chat. Email requires deployment configuration. Web Chat is built into the Agent page and does not require external provider credentials. For allocated addresses and sender policy, see [Connect an Agent to Email](/guides/platforms/email).