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.
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 and a client secret, which together let Switch sign in as the bot, and your tenant id, which identifies your organization in Microsoft 365.
- An Azure Bot resource on that app: Its messaging endpoint, the address Microsoft sends Teams messages to, 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, chosen for what you want Switch to do:
- Read channel messages:
ChannelMessage.Read.Group(resource-specific, granted team by team) or tenant-wideChannelMessage.Read.All. Without either, only messages that tag the bot reach Switch. With resource-specific consent, Switch can’t read private or shared channels, so choose tenant-wide if you’ll use those. Tenant-wide consent covers every channel in your organization, but Switch receives messages only from the channels it bridges. - Create channels for rooms:
Channel.Create. - Find people:
User.ReadBasic.All. - Add people to channels:
TeamMember.ReadWriteNonOwnerRole.Allfor standard channels, andChannelMember.ReadWrite.Allfor private channels. - Read channel names and types:
Channel.ReadBasic.All. Switch reads each channel’s name, its layout (posts or chat), and whether it’s private or standard.
- Read channel messages:
- Public HTTPS ingress: Routing
https://<your-public-host>/api/messagesandhttps://<your-public-host>/api/teams/notificationsto the Switch server’s Teams listener, on port 3978 unless the connection sets another. The administrator of your Switch server sets up this routing. Graph needs a valid HTTPS certificate, and an answer within ten seconds when it checks the address.
The Graph permissions listed above are for a Teams app you register yourself. If you connect the Switch Teams app from Switch instead, a Microsoft Global Administrator or Privileged Role Administrator needs to approve every permission it asks for, for the whole organization. Microsoft’s consent screen lists them.
- An admin account on the Switch server you’re connecting to: If Switch Console set up the server for you, you have one.
- A listener port of its own, if the server already has a Teams connection: Each connection needs its own port and ingress route. The port is part of the connection, and an admin sets it through the Switch server’s API. The administrator of your Switch server routes traffic to it.
- The server’s public address, if you want links to Switch Console to open from Teams. It’s separate from the connection’s Public Base Url, where Microsoft reaches Switch. The connection works without one, but those links then show as text naming the page.
Graph change notifications 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
First, put the bot in your tenant with a Teams app package: a zip holding the manifest, the file that describes the app to Teams, and its icons. Switch ships a complete one.1
Save the manifest and the icons
Save the manifest below as
manifest.json, and download the 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
Agent Switch app manifest
2
Replace the placeholders
- Replace the null GUID
00000000-0000-0000-0000-000000000000inid,bots[0].botId, andwebApplicationInfo.idwith your Azure bot’s app ID. Use the same value in each place. The shared ID ties the Teams app, the bot, and the Azure AD registration together. - Replace
switch.example.cominvalidDomainswith the host of your public base address. - Replace
https://example.com,https://example.com/privacy, andhttps://example.com/termswith your organization’s pages. Teams accepts the placeholders, but your users then see an app with no privacy policy.
authorization block unless you’re using resource-specific
consent for channel capture, which lets Switch read every message in a channel. With tenant-wide ChannelMessage.Read.All,
the block asks every team owner to consent to something your deployment doesn’t use.3
Zip the files, flat
-j: Teams rejects a package whose files sit inside a folder.4
Upload it to your tenant
Choose the upload method your tenant allows:
- Sideload it to upload it yourself to one team. In Teams, select Apps → Manage your apps → Upload an app → Upload a custom app, pick the zip, and choose the team. This needs Upload custom apps turned on in your app setup policy. If Upload a custom app isn’t offered, that policy setting is off. A policy change can take up to 24 hours to apply.
- Have an admin publish it. In the Teams admin center, select 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, select Apps → Import app. Choose this if you want to edit the manifest in a UI later.
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 workspace Admin
Next, give Switch the Azure details in Switch Console. You can also connect it in the Gateway, under Settings › Messaging apps, without Switch Console.1
Open the messaging apps for your server
In the Switch Console sidebar switcher, select the server, then, in the sidebar, select Settings, then Messaging apps. It lists what’s connected.
2
Start the connection
Select Connect. Under Messaging app, choose Microsoft Teams.
3
Name the connection
Name labels this connection when you pick it for a room in Switch Console, so name it after the tenant.
4
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.
5
Connect
Select Connect.
Link your Teams account
Finally, Switch Console asks which Teams account is yours. Search for yourself and select This is me. Switch Console then shows a code. From that Teams account, in a channel or chat the Switch app is in, mention the app and addlink-account followed by the code. The code works only from your account, so posting it in a busy channel is safe. It expires after 30 minutes. If it does, select Get a new code in Switch Console.
Once you confirm, your agents recognize you as their owner in Teams. If you skip this step, see Link your chat account.
Bring Switch into a channel
Installing the app into a team puts the bot in every standard channel of that team at once. For standard channels, 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.Private and shared channels need more. In each one, add the app from the channel’s Add an app list. A channel shared into your team has to be added from the team that hosts it. Graph refuses message subscriptions on these channels for apps using resource-specific consent, so full capture there needs tenant-wide
ChannelMessage.Read.All. Full capture in private and shared channels is supported but hasn’t been proven. Without it, the channel still gets messages that tag the bot.1
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: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.2
Bind a room to it
In the Gateway, create the room, choose Use existing channel, and paste the id into External channel ID. See Create a room in the Gateway. Switch works out whether the channel is standard or private.
3
Talk to an agent
Add an agent to the room and tag it by name in the channel.
When a channel is renamed
Renaming a channel or a group chat renames its room. A room named after its team follows the team’s name. Once someone renames the room in Switch, it keeps that name. A room renamed in Switch 0.31 or earlier wasn’t marked as renamed, so while its name still matches the channel’s, it follows the next rename. Rename it again in Switch to keep your name. The room’s settings in Switch Console then show the channel’s current name, with Use channel name to take it.Confirm it worked
- The connection is listed under Settings, then Messaging apps, with no error beside its name.
- The channel appears under 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. If it still can’t, see Agents answer only when tagged under Troubleshooting.
Troubleshooting
Agents answer only when tagged
Agents answer only when tagged
Only the Bot Framework is set up, so Microsoft Graph change notifications aren’t arriving. The Bot Framework delivers channel messages only when the bot is tagged. See How Switch sees a Teams channel.To fix it:
- Grant the Graph permissions and set up the notifications route in Before you begin.
- In a private or shared channel, add the app from that channel’s Add an app list. Installing the app into the team doesn’t add it to private or shared channels. With resource-specific consent, Switch can’t capture messages there, so use tenant-wide
ChannelMessage.Read.All, or accept that the channel gets only messages that tag the bot. - If the connection has only just started, wait a minute and try again. Switch keeps retrying while capture starts.
- If agents still miss untagged messages, check the Switch server’s log for the cause. On a Compose deployment, run
docker compose logs -f switch. 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.
A second Teams connection won't start
A second Teams connection won't start
Switch refuses a second connection on a listener port that’s already taken, and names the port.To fix it, ask the administrator of your Switch server to give each connection its own port and its own ingress route.
Next steps
Bring your team in
New to Switch? switch-buddy sets up an agent and its room for your team
Create a room
Turn a Teams channel into a room, or let Switch make the channel
Add a custom agent
Register an agent with the server so you can invite it into a room

