Connect Microsoft Teams

Connecting Microsoft Teams takes Azure and Microsoft 365 administration, and a publicly reachable HTTPS address. One Azure bot application represents every agent on your Switch server, and each agent’s messages render as a card headed with its name. Microsoft pushes messages to Switch, so the connection runs its own HTTPS listener, and Microsoft must be able to reach it from the internet.

Complete the Azure and Microsoft 365 steps with a directory administrator before you open the connect form. The form asks for the values these steps produce.

How Switch sees a Teams channel

Teams sends messages to Switch through two Microsoft interfaces. This split explains why tagged messages can work while other channel messages don’t:

The Bot Framework delivers one-to-one chats and group chats in full, but channel messages only when the bot is tagged. Switch also posts replies through the Bot Framework.
Microsoft Graph change notifications deliver everything else in a channel. Graph sends the message bodies encrypted, and Switch creates the certificate that decrypts them when you connect.

If you set up only the Bot Framework, the connection looks like it works: agents answer when tagged, but miss every other message in the channel.

Before you begin

In Azure and the Microsoft 365 admin center, you’ll need:

An Azure AD app registration: it gives you the bot client id, a client secret and your tenant id.
An Azure Bot resource on that app: its messaging endpoint set to https://<your-public-host>/api/messages, with the Microsoft Teams channel enabled.
A Teams app package that includes the bot: installed into the target team, so the bot can be added to channels and post without being spoken to first. Switch ships one; see Set up the Teams app.
Admin-consented Graph permissions:
- ChannelMessage.Read.Group (resource-specific, and preferred) or tenant-wide ChannelMessage.Read.All
- For provisioning: Channel.Create, Channel.ReadBasic.All, User.ReadBasic.All, TeamMember.ReadWrite.All for standard channels, and ChannelMember.ReadWrite.All for private channels. Grant all of them.
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, which listens on port 3978 unless a server administrator has set another. Graph needs valid TLS and an answer to its validation handshake within ten seconds.

In Switch, you’ll need:

An admin account on the Switch server you’re connecting to: if Switch Console set up the server for you, you have one.

Resource-data subscriptions draw on a per-tenant quota shared by everything in your organization that uses them. Check it before adding another consumer.

Set up the Teams app

A Teams app package puts the bot in your tenant. It’s a zip holding one manifest and two icons, and Switch ships a complete one.

Save the manifest and the icons

Save the manifest below as manifest.json, and download the two icons from docs/old/bridges/teams-app/ into the same folder: color.png (192×192) and outline.png (32×32).A Teams manifest points at icons by filename inside the package, not by URL, and a package without both won’t install.

Agent Switch app manifest

{
    "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.29/MicrosoftTeams.schema.json",
    "manifestVersion": "1.29",
    "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 \u2014 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",
    "supportsChannelFeatures": "tier1",
    "bots": [
        {
            "botId": "00000000-0000-0000-0000-000000000000",
            "scopes": [
                "team",
                "personal",
                "groupChat"
            ],
            "supportsTargetedMessages": true,
            "isNotificationOnly": false,
            "supportsFiles": false,
            "commandLists": [
                {
                    "scopes": [
                        "team",
                        "groupChat",
                        "personal"
                    ],
                    "triggers": [
                        "mention"
                    ],
                    "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"
                        },
                        {
                            "title": "/list-switch-agents",
                            "description": "List every agent on this Switch, to find one to invite"
                        },
                        {
                            "title": "/room-url",
                            "description": "Show this room's address in Switch"
                        }
                    ]
                },
                {
                    "scopes": [
                        "team",
                        "groupChat",
                        "personal"
                    ],
                    "triggers": [
                        "slash"
                    ],
                    "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"
                        },
                        {
                            "title": "list-switch-agents",
                            "description": "List every agent on this Switch, to find one to invite"
                        },
                        {
                            "title": "room-url",
                            "description": "Show this room's address in Switch"
                        }
                    ]
                }
            ]
        }
    ],
    "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

Replace the null GUID 00000000-0000-0000-0000-000000000000 in id, bots[0].botId and webApplicationInfo.id with your Azure bot’s app ID. Use the same value in all three places. The shared ID ties the Teams app, the bot and the Azure AD registration together.
Replace switch.example.com in validDomains with the host of your public base address.
Replace https://example.com/privacy and https://example.com/terms with your organization’s own pages. Teams accepts the placeholders, but your users then see an app with no privacy policy.

Delete the authorization block unless you’re using resource-specific consent for channel capture. With tenant-wide ChannelMessage.Read.All, it the 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

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

Upload it to your tenant

Choose the upload method 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 turned on in your app setup policy; if Upload a custom app isn’t offered, it’s off. A policy change can take up to 24 hours to apply.
Have an admin publish it. Teams admin center, Teams apps → Manage apps → Upload new app. This doesn’t need sideloading permission, and the app becomes available across the organization.
Register it in the Developer Portal. At dev.teams.microsoft.com, Apps → Import app. Choose this if you want to edit the manifest in a UI later.

Uploading a changed package with the same version has no effect, and it’s the usual reason a new command never shows up. Teams replaces the app only when the id matches and the version is higher, so raise version in the manifest each time you upload a change.

The Azure Bot resource has its own icon, separate from this package. Set it there too, or the bot shows a default avatar in some places.

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. Ask whoever runs the server.

Name the connection

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

Fill in the Azure details

App Id: paste the Azure AD app client id.
App Password: paste its client secret.
Tenant Id: paste your Azure AD tenant id.
Team Id: paste the id of the team that channels created from Switch are provisioned into.
Public Base Url: enter the public HTTPS address your listener is reachable at. Switch builds the notification address for Graph from this value, so Microsoft must be able to reach it.

Connect

Select Connect.

Link your Teams account

Switch Console then asks which Teams account is yours. Search for yourself and select This is me.Until you do, an agent set to answer only its owner doesn’t recognize you as its owner. You can select Skip for now and use Link my account… on the connection’s row later. For how linking works in every connected app, see Link your account, and why it matters.

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. You do need to tell Switch which channel each room belongs to.

Copy the channel's id

In Teams, open the context menu on the channel (right-click, or press and hold) 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 the id in this example is 19:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa@thread.tacv2. The groupId in the same link is the team id, so you can check the channel is in the team your connection points at.

Bind a room to it

Create the room, choose Use existing channel and paste the id into External channel ID. Switch works out whether the channel is standard or private.Once the room is linked, Switch posts a short notice in the channel, which confirms that Switch can post to the channel.

Talk to an agent

Add an agent to the room and tag it by name in the channel.

If you or an agent creates a room in Switch, Switch creates a matching Teams channel when channel creation is allowed.

Private and shared channels need more. The app has to be added to each one individually, and Graph refuses message subscriptions on them for apps using resource-specific consent, so full capture there needs the tenant-wide permission. The shipped manifest lets Teams offer the app in these channels, but Switch hasn’t been proven there.

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 can see a message that tags nobody. Post one in a standard channel, then tag an agent and ask what you just said. This verifies that channel capture is working. If the agent can’t see it, wait a minute and try again, because capture can fail for a short while after the connection starts and Switch keeps retrying. If it still can’t, channel capture isn’t running, though tagged messages still work. Check the Switch server’s log for the cause. The log records the first failure in full and after that only changes in the error, so a single older entry can still be the current cause.

What to expect in Teams

Agents appear as cards. Each message renders as a card headed with the agent’s name and avatar, not as a post from a named sender.
Commands work with either ! or /. Typing / offers the Switch commands, and a command picked there reaches Switch without a mention. Other people in the channel don’t see it. In a channel, a command you type out reaches Switch only when you mention the bot, unless channel capture is on.
“Open in Switch Console” links need GATEWAY_PUBLIC_URL set on the Switch server. Teams keeps only http and https links, so without it the link is removed and only empty brackets show.
Attachments are named, not carried. Files aren’t relayed in either direction yet. The text bridges, with a note saying what wasn’t carried.
Link your Teams account to get real mentions from agents. An agent’s mention of anyone who hasn’t linked, and of 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.
In a one-to-one chat, you don’t need the @. Only a person can start one, so open a chat with the Switch app yourself. Switch creates a room for the chat, and every message in it reaches the agent. Use one agent per chat. If you add a second agent, both receive every message.
One Teams connection per listener port. Switch refuses a second connection on a port that’s already taken, and names the port. To run more than one on a host, a server administrator gives each its own port, and each needs 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

Use cases

Set up Switch

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