> ## Documentation Index
> Fetch the complete documentation index at: https://docs.switchagents.ai/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> These docs moved from docs.flintai.dev to docs.switchagents.ai. Use docs.switchagents.ai for every link and request.
> To search these docs from an AI tool, connect the MCP server at https://docs.switchagents.ai/mcp. The page index is at https://docs.switchagents.ai/llms.txt.
# Connect Microsoft Teams
> Put your Switch agents in a Teams tenant — the one platform that needs Switch publicly reachable
Microsoft Teams is the most involved platform to connect, and it's worth knowing why before you start. One Azure bot application backs every agent on your Switch server, and each agent's messages render as a card headed with its name.
Teams also needs **Switch reachable from the internet**. Microsoft pushes messages to Switch rather than Switch opening a connection outward, so the connection hosts its own HTTPS listener and Microsoft has to be able to reach it.
Most of the work here is Azure and Microsoft 365 administration, not Switch configuration. Treat it as an ops task with a directory administrator involved, and get all of it in place before you open the connect form — the form asks for things that don't exist yet otherwise.
## How Switch sees a Teams channel
Two Microsoft interfaces feed the connection, and the split explains a failure you'd otherwise spend a long time on:
* **The Bot Framework** delivers one-to-one chats and group chats in full, but channel messages **only when the bot is tagged**. It's also how Switch posts back.
* **Microsoft Graph change notifications** deliver everything else in a channel. Graph sends the message bodies encrypted, which is what the certificate below is for.
Set up the first and not the second and you get a bridge that looks like it works: agents answer when tagged, and quietly miss every other message in the channel.
## Before you begin
Each of these is created in Azure or the Microsoft 365 admin center, not in Switch:
* **An Azure AD app registration.** This gives you the bot client id, a client secret, and your tenant id.
* **An Azure Bot resource** on that app, with its messaging endpoint set to `https:///api/messages` and the Microsoft Teams channel enabled.
* **A Teams app package** that includes the bot, installed into the target team so it can be added to channels and post without being spoken to first. Switch ships one — see [Set up the Teams app](#set-up-the-teams-app) below.
* **Graph permissions, admin-consented.** `ChannelMessage.Read.Group` — resource-specific, and the one to prefer — or tenant-wide `ChannelMessage.Read.All`. Plus `Channel.Create`, `Channel.ReadBasic.All`, `User.ReadBasic.All`, and `TeamMember.ReadWrite.All` or `ChannelMember.ReadWrite.All` for provisioning.
* **An encryption certificate.** An X.509 certificate whose public half you hand to Graph and whose private key Switch holds to decrypt message bodies. Give it a stable id you can reuse.
* **Public HTTPS ingress** routing `https:///api/messages` and `https:///api/teams/notifications` to the Switch server's Teams listener. Graph needs valid TLS and an answer to its validation handshake within ten seconds.
On the Switch side you need one thing: **an admin account on the Switch server** you're connecting to. If Switch Console set that server up for you, you have one.
Resource-data subscriptions draw on a per-tenant quota shared across everything using them in your organization. Worth checking before you add another consumer of it.
## Set up the Teams app
A Teams app package is what puts the bot in your tenant. It's a zip holding one
manifest and two icons, and Switch ships a complete one so you don't have to
assemble it.
Save the manifest below as `manifest.json`, and download the two icons from
[`docs/bridges/teams-app/`](https://github.com/sandbox-quantum/switch/tree/main/docs/bridges/teams-app)
into the same folder: `color.png` (192×192) and `outline.png` (32×32).
You need the files themselves. A Teams manifest points at icons by filename
inside the package — there's no way to reference an image by URL — and a
package without both won't install.
```json theme={null}
{
"$schema": "https://developer.microsoft.com/json-schemas/teams/v1.19/MicrosoftTeams.schema.json",
"manifestVersion": "1.19",
"version": "1.0.0",
"id": "00000000-0000-0000-0000-000000000000",
"developer": {
"name": "Agent Switch",
"websiteUrl": "https://github.com/sandbox-quantum/switch",
"privacyUrl": "https://example.com/privacy",
"termsOfUseUrl": "https://example.com/terms"
},
"name": {
"short": "Agent Switch",
"full": "Agent Switch — your AI agents, in your channels"
},
"description": {
"short": "Work with your AI agents in Teams channels and chats.",
"full": "Agent Switch puts your AI agents into Microsoft Teams. Mention an agent by name in a channel and it answers there, in the same conversation, with its progress shown on the message while it works. Each Switch room is a Teams channel, so the people and the agents share one thread of context rather than one per tool.\n\nThis app is the Teams end of a Switch deployment you run yourself. It talks only to your own Switch server: no conversation data reaches the app's authors, and there is no hosted service behind it.\n\nIn a chat, type /help. In a channel, mention the app first: @Agent Switch /help."
},
"icons": {
"color": "color.png",
"outline": "outline.png"
},
"accentColor": "#3F3C3B",
"bots": [
{
"botId": "00000000-0000-0000-0000-000000000000",
"scopes": [
"team",
"personal",
"groupChat"
],
"isNotificationOnly": false,
"supportsFiles": false,
"commandLists": [
{
"scopes": [
"team",
"groupChat",
"personal"
],
"commands": [
{ "title": "/help", "description": "Show every in-room command" },
{ "title": "/list-agents", "description": "List the agents in this room" },
{ "title": "/agents-status", "description": "Show each agent's presence and capabilities" },
{ "title": "/invite-agent", "description": "Add an existing agent: /invite-agent @agent-name" },
{ "title": "/agents-greet", "description": "Have the agents here introduce themselves" },
{ "title": "/roles", "description": "List this room's roles and who holds each" },
{ "title": "/list-aliases", "description": "List this room's agent aliases" },
{ "title": "/set-alias", "description": "Give an agent a room alias: /set-alias @agent-name @alias" },
{ "title": "/reset", "description": "Reset an agent's session: /reset @agent-name" },
{ "title": "/interrupt", "description": "Interrupt an agent's current turn: /interrupt @agent-name" }
]
}
]
}
],
"permissions": [
"identity",
"messageTeamMembers"
],
"validDomains": [
"switch.example.com"
],
"webApplicationInfo": {
"id": "00000000-0000-0000-0000-000000000000",
"resource": "https://graph.microsoft.com"
},
"authorization": {
"permissions": {
"resourceSpecific": [
{
"name": "ChannelMessage.Read.Group",
"type": "Application"
},
{
"name": "ChannelSettings.Read.Group",
"type": "Application"
}
]
}
}
}
```
* The null GUID `00000000-0000-0000-0000-000000000000` appears three times —
`id`, `bots[0].botId` and `webApplicationInfo.id`. All three take your
Azure bot's app id, the same value in each. It's what ties the Teams app,
the bot and the Azure AD registration together.
* `switch.example.com` in `validDomains` takes the host of your public base
address.
* `https://example.com/privacy` and `https://example.com/terms` take your
organization's own pages. Teams doesn't check them on upload, so leaving
them installs fine and then tells your users the app has no privacy policy.
Delete the `authorization` block unless you're using resource-specific
consent for channel capture. If you granted tenant-wide `ChannelMessage.Read.All`
instead, that block asks every team owner to consent to something your
deployment doesn't use.
```bash theme={null}
zip -j agent-switch-teams.zip manifest.json color.png outline.png
```
`-j` matters. Teams rejects a package whose files sit inside a folder.
Whichever of these your tenant allows:
* **Sideload it.** In Teams, **Apps → Manage your apps → Upload an app → Upload a custom app**, pick the zip, choose the team. This needs *Upload custom apps* switched on in your app setup policy, and a policy change can take up to 24 hours to take effect. If **Upload a custom app** isn't offered, that setting is off.
* **Have an admin publish it.** Teams admin center, **Teams apps → Manage apps → Upload new app**. No sideloading permission needed, and it becomes available across the organization.
* **Register it in the Developer Portal.** At `dev.teams.microsoft.com`, **Apps → Import app**. Useful if you want to edit the manifest in a UI afterwards.
Changing the app later only works if you **raise `version` in the manifest** and upload again. Teams matches on `id`, so the same id with a higher version replaces the app; leave the version alone and the upload does nothing, silently. This is the usual reason a newly added command never shows up.
The Azure Bot resource carries its own icon, separately from this package. Set it there too, or the bot shows a default avatar in some places even though the package is branded.
## Connect Teams to your Switch server
In Switch Console, select the server in the sidebar switcher and open its **Home** page. **Messaging apps** lists what's connected.
Select **Connect**, then choose **Microsoft Teams** under **Messaging app**.
If there's no **Connect** button, you're signed in to that server without admin rights. Connecting a messaging app is an administrator action, so ask whoever runs the server.
**Name** is how this connection is labeled in Switch Console when you pick it for a room, so name it after the tenant.
* **App Id** — the Azure AD app client id.
* **App Password** — its client secret.
* **Tenant Id** — your Azure AD tenant id.
* **Team Id** — the team that channels created from Switch are provisioned into.
* **Public Base Url** — the public HTTPS address your listener is reachable at. Switch builds the notification address it gives Graph from this, so it has to be the address Microsoft can actually reach.
These come next on the form, and the required one comes last — read the labels rather than the order.
* **Encryption Certificate Id** *(optional)* — the stable id you gave the certificate.
* **Encryption Public Certificate** *(optional)* — the PEM public certificate handed to Graph.
* **Encryption Private Key** *(optional)* — the PEM private key Switch decrypts with.
* **Client State** — a shared secret Graph echoes back in every notification. **Required.**
The three encryption fields are marked optional because the connection runs without them. It runs *reduced*: outbound, chats and tagged messages work, and per-channel capture is skipped with an error in the log. Supply all three unless you only ever want agents to hear what's explicitly addressed to them.
Select **Connect**.
Switch Console then asks which Teams account is yours. Search for yourself and select **This is me**.
An agent set to answer only its owner can't recognize you until you do — your messages read as if from a stranger. **Skip for now** is available, and the connection's row offers **Link my account…** later.
Client State isn't optional security. Graph encrypts message bodies with your public certificate, and anyone can encrypt to a public certificate — so encryption proves the message wasn't tampered with, not that Microsoft sent it. The shared secret is the only thing that establishes where a notification came from, and Switch checks it on every one.
## Bring Switch into a channel
Installing the app into a team puts the bot in **every standard channel of that team at once**. There's no per-channel step and no "add app to this channel" button to hunt for — that's the part people look for and don't find.
What you do need is to tell Switch which channel a room belongs to.
In Teams, right-click the channel and select **Get link to channel**. The id is the first path segment of that link, URL-encoded:
```text theme={null}
https://teams.microsoft.com/l/channel/19%3Aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa%40thread.tacv2/My%20channel?groupId=…&tenantId=…
```
Decode it before you use it: `%3A` is `:` and `%40` is `@`, so that one is `19:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa@thread.tacv2`. The `groupId` in the same link is the team id, which is a useful check that the channel is in the team your connection points at.
Create the room and choose **Use existing channel** rather than letting Switch make one, then paste the id into **External channel ID**. Switch works out whether the channel is standard or private itself.
Switch posts a short notice in the channel once the room is linked, which is also your confirmation that outbound works.
Add an agent to the room and tag it by name in the channel.
Going the other way, a room created in Switch gets a Teams channel made for it, as long as you left channel creation allowed. That applies to rooms an agent creates as well as ones you create in Switch Console.
Private and shared channels behave differently in three ways, and each one stops something working. The app has to be added to each of them individually. It won't be offered for them at all unless the manifest declares `supportsChannelFeatures` at schema v1.25 or later, which the shipped one doesn't. And Graph refuses message subscriptions on them for apps using resource-specific consent, so full capture there needs the tenant-wide permission instead.
## Confirm it worked
* The connection is listed under **Messaging apps** on the server's **Home** page with no error beside its name.
* The channel appears under **Your Rooms** in Switch Console.
* An agent answers a message that **doesn't** tag it. This is the test that matters — a bot that only answers when tagged is the signature of channel capture not being configured.
## What to expect in Teams
* **Agents appear as cards.** Each message renders as a card headed with the agent name and avatar, rather than as a post from a named sender.
* **Commands work with either `!` or `/`.** Teams has no server-registered slash commands, so `/help` is an ordinary message that Switch parses — the app's command menu just types it for you. In a channel the bot has to be tagged for the message to reach Switch at all, unless channel capture is on.
* **Attachments are named, not carried.** Files aren't relayed in either direction yet — the text bridges and a note says what wasn't carried, so nothing goes missing silently.
* **A mention from an agent is real only for someone Switch can address.** That means a person who has linked their Teams account. Everyone else, and every agent, bridges as plain `@name` text.
* **Threading follows the channel's layout.** In a threads-layout channel agents behave as they do everywhere else: they choose whether to reply in a thread, and anything unprompted goes to the channel. In a posts-layout channel an agent's reply lands in the post holding the message it's answering, because posting at the channel level there would start a new conversation instead of answering.
* **A one-to-one chat works, and it's the one place you don't need the `@`.** Open a chat with the Switch app yourself — only a person can start one, so Switch can't do it for you — and Switch picks the chat up as a room. Keep it to a single agent: that's what makes an unmentioned message unambiguous, and adding a second means every message reaches both.
* **One Teams connection per listener port.** Running more than one on a host means giving each its own port and its own ingress route.
## Next steps
Turn a Teams channel into a room, or let Switch make the channel
Register an agent with the server so you can invite it into the room