A connection lets people message an Agent through a chat service such as Slack, Microsoft Teams, Telegram, or Discord.
Create the Agent first, then add a connection for the chat service you want to use. You can connect the same Agent to several services or add multiple connections for one service.
Connections work with both Hermes and OpenClaw. You do not need to change the Agent's runtime to add another chat service.
Overview
See Agents for the complete Agent lifecycle, and Configure an Agent for where connections sit inside Agent configuration.
Before you begin
You need:
- An existing Agent in your Organization.
- Permission to update that Agent and manage its credentials. Agent Editor and Agent Owner provide this access; Organization Owners and Admins also have authority over their Organization’s Agents.
- Access to create or configure the bot or application in your chosen chat service. You may need help from that service’s administrator.
- The credentials requested by the setup guide for that service.
If you have Agent Viewer access, ask an Organization Owner or Admin to review your access before continuing.
Choose the guide for your chat service:
| Chat service | Setup guide |
|---|---|
| Slack | Set up Slack |
| Microsoft Teams | Connect Microsoft Teams |
| Telegram | Connect Telegram |
| Discord | Connect Discord |
Microsoft Teams needs a publicly reachable HTTPS webhook endpoint for your Agent Barn installation. A local installation available only at localhost does not meet that requirement. Arrange the public endpoint with your installation administrator before beginning the Teams setup.
Add a connection
- Open the Agent in Agent Barn.
- Open Configuration and find the connections section.
- Select Add connection.
- Choose Slack, Microsoft Teams, Telegram, or Discord.
- Follow that service’s setup guide to create or configure its bot or application and obtain the required credentials.
- Enter the credentials in the connection form and give the connection a recognizable name, such as Slack: Engineering.
- Choose which channels, groups, or people may interact with the Agent. The available settings depend on the chat service.
- Save the connection and complete any remaining provider setup, such as installing the bot or registering its webhook.
- Review the connection’s status and follow the service’s setup guide to send a test message.
The Agent’s runtime must be running to process messages. Adding a connection does not replace the separate Start action for a stopped Agent.
An access allowlist controls which messages Agent Barn accepts. It does not install the bot, invite it to a channel, or grant permissions in the chat service.
What you manage on a connection
Each connection has its own chat service, name, credentials, access settings, enabled state, and health information.
For example, an Agent connected to Slack and Discord has separate settings for each. Changing the Slack connection does not change the Discord connection.
Chat connection credentials are separate from credentials used by the Agent’s tools. Enter a Slack bot token for messaging in the Slack connection, not in a Template, Skill, or tool-credential field.
Slack Connections can hold the Agent's one default delivery target for scheduled work created outside a conversation. Configure it in the Connection editor. Jobs with a recorded conversation origin keep that origin; changing the default does not move them. See the Slack guide for setup and runtime limitations.
You can update a connection independently of the Agent’s runtime. Connection changes do not use Apply & Restart.
Settings and credentials
A Connection separates three kinds of material:
| Category | Contains |
|---|---|
| Connection settings | Routing and admission policy, such as allowlists, direct-message policy, mention behavior, and proactive destinations |
| Connection credentials | Encrypted provider authentication material |
| Agent Secrets | Credentials for tool Integrations used by the Runtime |
- Connection credentials are not Agent Secrets.
- Connection credentials are never returned in plaintext.
- Connection credentials are not materialized into Hermes or OpenClaw.
- The Runtime receives only its versioned Communications protocol credentials.
Change a Connection
Connection changes use optimistic revision control.
- Updating settings or credentials increments the Connection revision.
- The Communications Gateway reconciles the provider session.
- A running Agent does not need to restart when Connection settings or credentials change.
- Changing a Connection does not alter the Agent’s Runtime, Template, Skills, model, or lifecycle state.
- A stale revision should be refreshed before retrying an update.
Enable, disable, and retire
| Operation | Effect |
|---|---|
| Disable | Stops the Connection from participating while preserving its configuration and history |
| Enable | Makes the configured Connection eligible for provider ingress and delivery again |
| Retire | Removes the Connection from active use, releases protected provider credential identity where applicable, and preserves historical Conversation Messages |
Retiring a connection keeps its historical Conversation Messages. It does not delete the bot or application in the chat service; remove that through the service’s own administration if you no longer need it.
Retiring an Agent also retires its active Communication Connections.
Check the connection and the runtime separately
A running Agent can have a failed chat connection. A connected chat service also does not prove that the Agent’s runtime is ready to answer.
If messages are not working:
- Check the affected connection’s status.
- Confirm that its credentials, provider installation, and access settings are correct.
- Confirm that the Agent is running and its runtime is healthy.
- Open the connection’s diagnostics for delivery failures and available recovery actions.
Use connection recovery actions for provider-session problems. Restarting the Agent does not rebuild the provider connection.
See Communication Diagnostics and Review Agent health and logs.
How the two states differ
Connection health is independent of Agent lifecycle.
- A Connection can be degraded or in error while the Agent Runtime remains running.
- A running Agent can have a mixture of healthy and unhealthy Connections.
- Provider authentication or session failures update Connection health rather than changing the Agent to
ERROR. - Runtime or Kubernetes startup failures affect Agent lifecycle instead.
- Connection diagnostics, journals, reconnects, and delivery retries belong to the Communications operational surface.
This guide does not cover that diagnostics workflow. For Agent-level health and logs, see Review Agent health and logs.
Conversation isolation
- Every canonical Conversation Message records its source Communication Connection.
- Conversation location identity includes both the Connection ID and provider channel ID.
- Two Connections may safely use the same provider channel identifier.
- Replies remain bound to the Connection and conversation that produced the source delivery.
- One Connection cannot accidentally deliver a reply through another Connection.
Technical details
This section is for developers and installation administrators. You do not need it to add a connection.
A Communication Connection is an Agent-owned subordinate resource that links one Agent to one configured endpoint on a communication Platform. Each Connection owns:
- Its Platform Plugin selection
- A human-readable Connection name
- Platform-specific settings
- Encrypted provider credentials
- Enabled or disabled state
- A revision used for safe updates and gateway reconciliation
- Observed provider health
- Durable inbound and outbound Communication Deliveries
- Connection-scoped Conversation Messages and provider locations
Platform Plugins provide the settings and credential schemas for a Connection. The Connection interface is schema-driven: the fields shown come from the selected Platform Plugin, not from a fixed set of Agent columns.
Provider ingress by Platform
Agent Barn currently ships Platform Plugins for these Platforms. Ingress differs by Platform:
| Platform | Ingress |
|---|---|
| Slack | Supervised Socket Mode |
| Microsoft Teams | Authenticated provider webhook ingress |
| Telegram | Supervised polling |
| Discord | Supervised Gateway session |
See Platforms for the complete set of provider guides.
API reference summary
| Method and endpoint | Purpose |
|---|---|
GET /api/v1/organizations/{organization_id}/communication-platforms | List the Platform Plugins available for a Connection |
GET /api/v1/organizations/{organization_id}/agents/{agent_id}/connections | List an Agent’s Communication Connections |
POST /api/v1/organizations/{organization_id}/agents/{agent_id}/connections | Create a Communication Connection |
PATCH /api/v1/organizations/{organization_id}/agents/{agent_id}/connections/{connection_id} | Update a Connection’s settings, credentials, or enabled state |
DELETE /api/v1/organizations/{organization_id}/agents/{agent_id}/connections/{connection_id} | Retire the Connection |
The DELETE operation retires the Connection and requires its current revision.
Provider ingress belongs to /communications/v1, an internal deployment boundary rather than a normal user API route.
Recommended practices
- Use descriptive Connection names.
- Use separate provider identities for separate production Connections.
- Begin with narrow channel, chat, server, team, user, role, and DM policies.
- Keep provider credentials in the Connection credential fields.
- Test one allowed and one blocked interaction.
- Monitor Connection health separately from Agent runtime health.
- Disable a Connection before provider-side maintenance when practical.
- Retire unused Connections instead of leaving abandoned credentials enabled.
- Review all Connections before retiring an Agent.
Chat in the dashboard
For an initial conversation without external provider setup, use the experimental Chat tab once the Agent is Running and Working. See Chat with an Agent in the dashboard for permissions and thread behavior. External Connections can be configured separately.