---
title: MS Teams
category: Agents
order: 7
description: Connect Archestra agents to Microsoft Teams channels
lastUpdated: 2026-06-12
---

Archestra can connect directly to Microsoft Teams channels. When users mention the bot in a channel, messages are routed to your configured agent and responses appear directly in Teams.

## Prerequisites

- **Azure subscription** with permissions to create Azure Bot resources
- **Teams tenant** where you can install custom apps
- **Archestra deployment** with external webhook access

## Setup

The setup wizard in Archestra guides you through the entire MS Teams configuration. Navigate to **Agent Triggers** → **MS Teams** → **Setup MS Teams** and follow the step-by-step instructions.

![MS Teams Setup Wizard](/docs/setup-msteams.webp)

The wizard will walk you through creating an Azure Bot, configuring the Teams app manifest, and installing it to your workspace. All required credentials are collected and saved automatically.

See [Deployment — Environment Variables](/docs/platform-deployment#environment-variables) for the full list of environment variables if you prefer manual configuration.

If your instance is not already publicly reachable (for example, running locally), Archestra can open an [ngrok](https://ngrok.com) tunnel so Teams can deliver messages. The setup wizard's **Configure ngrok** step takes your ngrok auth token and brings the tunnel up live — no restart needed. For Docker or unattended deployments, set `ARCHESTRA_NGROK_AUTH_TOKEN` instead and the tunnel starts on boot.

## Usage

### First Message

When you **first mention the bot** in a channel:

```
@Archestra what's the status of service X?
```

The bot responds with an **Adaptive Card dropdown** to select which agent handles this channel. After selection, the bot processes your message.

### Replying within a thread

In channels the bot stays silent until it is @mentioned. Once mentioned in a thread, it keeps replying to every message in that thread without further mentions. Starting a new thread needs a fresh mention. Direct messages and group chats always get a reply, no mention required.

To stop the bot replying in a thread, send `mute` (you can address it by name with no @mention, e.g. `Archestra mute`), or react to one of its replies with the mute (🔇) or shushing-face (🤫) emoji. It goes quiet until the thread is @mentioned again. As a reminder, the bot adds a short hint about this to its first reply in each thread.

### Commands

| Command | Description |
|---------|-------------|
| `@Archestra /select-agent` | Change which agent handles this channel by default |
| `@Archestra /status` | Show currently set default agent for the channel |
| `@Archestra /help` | Show available commands |

### Default Agent

Each Teams channel requires a **default agent** to be assigned to it. This agent handles all messages in the channel by default. When you first mention the bot in a channel without a binding, you'll be prompted to select an agent from a dropdown.

You can manage the default agent for each channel from the **Agent Triggers** → **MS Teams** page in Archestra.

![MS Teams Agent Selection](/docs/select-agent-msteams.webp)

Once set, the default agent handles messages in that channel's active threads. You can also use the `/select-agent` command directly in Teams to change the default agent.

### Switching Agents Inline

You can temporarily use a different agent for a single message by using the `AgentName >` syntax:

```
@Archestra Sales > what's our Q4 pipeline?
```

This routes the message to the "Sales" agent instead of the channel's default agent. The default binding remains unchanged—only this specific message uses the alternate agent.

**Matching rules:**
- Agent names are matched case-insensitively
- Spaces in agent names are optional: `AgentPeter >` matches "Agent Peter"
- If the agent name isn't found, the message falls back to the default agent with a notice

**Examples:**

| Message | Routed To |
|---------|-----------|
| `@Archestra hello` | Default agent |
| `@Archestra Sales > check revenue` | Sales agent |
| `@Archestra support > help me` | Support agent |
| `@Archestra Unknown > test` | Default agent (with fallback notice) |

### Direct Messages

A DM with the bot behaves just like another channel — each user can choose which agent handles their DMs. On your first message, the bot shows an agent selection card. Use `/select-agent` to change it later.

> **Note:** Installing the bot for a team does not automatically enable direct messages for all team members. Each user must install the Archestra app personally before they can DM the bot. When a user opens a chat with the bot for the first time, Teams prompts them to click **Add** to complete the personal installation. This is a Microsoft Teams platform requirement.

> If you update from a previous manifest without the `"personal"` scope, re-upload the updated manifest to enable DMs.

## Autoprovisioning MS Teams Users

When a user interacts with the bot but hasn't signed up in Archestra yet, they are automatically provisioned with the **Member** role and no teams assigned. The user receives a unique invitation link via Teams DM that they can use to complete sign-up and become a full Archestra user. Until they do, they cannot log in to the Archestra web app.

Admins can view autoprovisioned users on the **Settings → Members** page — from there they can copy the invitation link or delete the user.

![Autoprovisioned MS Teams Users](/docs/autoprovisioned-users-msteams.webp)

## Attachments

Messages sent to the bot can include file attachments (images, PDFs, documents, etc.) in channels, group chats, and direct messages. Attachments are automatically downloaded and passed to the agent for processing. Files the selected model can read — images, PDFs, and text documents such as CSV, TSV, JSON, XML, YAML, TOML, and Markdown — are included inline in the agent's context. When the agent has a code sandbox, other file types (for example a SQLite database or a ZIP archive) are placed into the sandbox so the agent can open them with its tools. Anything that still cannot be provided is noted by name so the agent can tell the user. A message that contains only a file (no text) is processed too.

Adaptive Cards and other Teams-specific card types are not treated as file attachments.

**Limits:**
- Max 20 attachments per message
- Max 10 MB per individual file
- Max 25 MB total across all attachments in a single message

Files exceeding these limits are silently skipped.

## Troubleshooting

**"You don't have access to this app"**
- Your org may have disabled custom app uploads
- Ask IT to enable sideloading in [Teams Admin Center](https://admin.teams.microsoft.com/)

**Bot not responding**
- Verify `ARCHESTRA_CHATOPS_MS_TEAMS_ENABLED=true`
- Check webhook URL is accessible externally
- Verify App ID and Password are correct

**"Could not verify your identity"**
- Ensure `TeamMember.Read.Group` and `ChatMember.Read.Chat` RSC permissions are in your manifest. These are required for the bot to resolve user emails. Reinstall the app after updating the manifest.

**No thread history**
- Ensure `ChannelMessage.Read.Group` and `ChatMessage.Read.Chat` RSC permissions are in your manifest. Reinstall the app after updating the manifest. The team owner must consent to the permissions when adding the app.
