Slack & Teams Bots

Bring Archyl into the tools your team already lives in. Mention @Archyl in Slack or Microsoft Teams and ask questions about your software architecture — the C4 model, ADRs, dependencies, ownership and more — and get answers grounded in your real data, right in the channel.

Overview

The bot is connected per organization. Once an admin connects a workspace, anyone in it can ask the bot questions by mentioning it. The bot answers using the permissions of the admin who connected it, and its scope is your organization's projects.

By default that scope is every project in the organization. An admin can narrow any channel to a team or a set of projects — see Scoping a channel to a team or projects below.

There are two ways the bot answers:

You switch between them by selecting an API key in Organization → Bot → MCP tools (see Enabling MCP tools below).

Connecting Slack

1. In Archyl, go to Organization → Bot.
2. Click Add to Slack. You'll be taken to Slack to authorize the Archyl app and pick a workspace.
3. After approving, you're returned to Archyl and the workspace appears under Connected.
4. In Slack, invite the bot to a channel and mention it:

   @Archyl what depends on the payments service?
   

The bot replies in a thread to keep channels tidy. Mention it again (in the channel or inside the thread) to ask a follow-up.

• Edit re-runs the Slack install (refresh the connection).
• Disconnect removes the integration.

Connecting Microsoft Teams

Teams uses an app package and a one-time linking code.

1. In Archyl, go to Organization → Bot and click Download Teams app to get archyl-teams-app.zip.
2. In Teams, install the app: Apps → Manage your apps → Upload a custom app, and select the .zip. (If you don't see that option, a Teams admin must allow custom app uploads or upload it to your org's app catalog.)
3. Back in Archyl, click Connect Teams. You'll get a code like @Archyl link 6GXH6NKL.
4. In Teams, send that exact message to the Archyl bot (in a 1:1 chat, just link 6GXH6NKL). The bot replies ✅ Connected to your Archyl organization.
5. Now mention it with questions:

   @Archyl which team owns the API gateway?
   

The link code is valid for 15 minutes and is single-use. Generate a fresh one anytime from the Bot tab.

Note: Microsoft Teams bots require a work or school (Microsoft 365) account — they don't work with personal Microsoft accounts.

Enabling MCP tools (agentic mode)

By default the bot answers directly from your architecture context. To let it use live MCP tools — looking projects up by name, tracing dependencies, creating ADRs or documentation, and more — give it an API key:

1. Create an API key under Profile → API Keys (or reuse an existing one).
2. Go to Organization → Bot → MCP tools and select that key.
3. That's it — the next time someone mentions the bot, it reasons over your architecture with the MCP server tools and shows each action it takes before answering.

Scope matters:

• A read key lets the bot look things up but not change anything.
• A write key additionally lets it create or update elements, ADRs, documentation, and so on. Only choose a write key if you want the bot to make changes.

Select None at any time to turn agentic mode off and return to direct answers.

Scoping a channel to a team or projects

By default every channel sees every project in your organization. That is often what you want — but a #payments channel usually should not answer questions about the lending platform.

To narrow one, go to Organization → Bot → Channel scope and click Scope a channel:

1. What the channel sees — a team, or one or more projects.
2. Which channel — pick the platform and give the channel a name for the list, then click Get the command.
3. Paste the command — send @Archyl scope <code> in that channel. The bot confirms, and the channel appears in the list as soon as it has been applied.

Codes are valid for 15 minutes and can be used once. To widen a channel again, click Clear next to it in the list.

Why a code and not a button? The bot answers with the connecting admin's permissions and cannot tell who is speaking in a channel. The code is the authorization: it was minted by an admin in Archyl, so scoping cannot be changed by anyone who simply types in the channel.

A few things worth knowing:

• Team scope follows the team. A project added to a scoped team later is covered automatically, with no need to re-scope the channel.
• The scope is enforced, not suggested. It is applied on every tool call and every listing, so a scoped channel cannot read another project even if someone asks for it by ID.
• Organization-level ADRs, docs and API contracts stay visible — they belong to the organization rather than to any project.
• The name is only a label. The bot has no access to channel names, so the one you type is what the list shows; the binding itself is to whichever channel you paste the command in.

How permissions work

• The bot answers with the permissions of the admin who connected the workspace, scoped to your organization's projects.
• A scoped channel sees only the projects of its team or list. That is enforced on every tool call and every listing, not left to the prompt.
• In agentic mode, what the bot can read and change is further governed by the scope of the selected API key.
• Each question counts toward your organization's AI usage, the same as the in-app chat.

Tips

• Be specific by name. You can refer to projects, systems, ADRs and docs by name — the bot resolves them to the right items for you.
• Follow up in the thread. Mention the bot again to continue a line of questioning.
• Markdown just works. Answers are formatted for each platform (bold, lists, links, code).
• Scope shared channels. Narrow #payments to the Payments team, and the wrong answer never lands in the wrong room (Scoping a channel to a team or projects).

Next steps

• MCP Server — Connect AI agents and IDEs to Archyl's tools
• Webhook Notifications — Push architecture events to external systems