Connect Microsoft Teams

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://<your-public-host>/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 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://<your-public-host>/api/messages and https://<your-public-host>/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 and the icons

Save the manifest below as manifest.json, and download the two icons from 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.

Agent Switch app manifest

{
    "$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"
                }
            ]
        }
    }
}

Replace the placeholders

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.

Zip the three files, flat

zip -j agent-switch-teams.zip manifest.json color.png outline.png

-j matters. Teams rejects a package whose files sit inside a folder.

Upload it to your tenant

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

Open the messaging apps for your server

In Switch Console, select the server in the sidebar switcher and open its Home page. Messaging apps lists what’s connected.

Start the connection

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 the connection

Name is how this connection is labeled in Switch Console when you pick it for a room, so name it after the tenant.

Fill in the Azure details

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.

Fill in the channel-capture details

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.

Connect

Select Connect.

Link your Teams account

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.

Copy the channel's id

In Teams, right-click the channel and select Get link to channel. The id is the first path segment of that link, URL-encoded:

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.

Bind a room to it

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.

Talk to an agent

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

Create a room

Turn a Teams channel into a room, or let Switch make the channel

Overview

Get started

Deploy and connect

Working in Switch

Build with Switch

Under the hood

Resources

Connect Microsoft Teams

How Switch sees a Teams channel

Before you begin

Set up the Teams app

Connect Teams to your Switch server

Bring Switch into a channel

Confirm it worked

What to expect in Teams

Next steps

Create a room

Onboard agents

​How Switch sees a Teams channel

​Before you begin

​Set up the Teams app

​Connect Teams to your Switch server

​Bring Switch into a channel

​Confirm it worked

​What to expect in Teams

​Next steps

Create a room

Onboard agents

How Switch sees a Teams channel

Before you begin

Set up the Teams app

Connect Teams to your Switch server

Bring Switch into a channel

Confirm it worked

What to expect in Teams

Next steps