Skip to content

Microsoft Teams

Connecting Microsoft Teams lets your users chat with an agent from a team channel, a group chat, or a personal chat, and lets agents post messages, cards, and files back into Teams.

Teams has the longest setup of all channels because it involves three Microsoft surfaces: an Entra ID app registration for the identity and permissions, an Azure Bot resource for message delivery, and a Teams app package for installation in the tenant. Read Channels and bots first for the concepts shared with the other platforms.

Before you start

  • You need an Entra ID (Azure AD) administrator, or someone who can grant admin consent for application permissions.
  • You need permission to upload a custom app to your Teams tenant, or a Teams administrator to do it for you.
  • You need administrator rights in XTM One.
  • The platform must be reachable from the internet over HTTPS, because Teams posts messages to it.

Step 1: Register the application in Entra ID

  1. In the Azure portal, go to Entra ID > App registrations > New registration.
  2. Note the Application (client) ID and the Directory (tenant) ID from the overview page.
  3. Under Certificates & secrets, create a client secret and copy its value immediately — it is shown only once.
  4. Under API permissions, add the Microsoft Graph application permissions listed below, then click Grant admin consent. They must be application permissions, not delegated ones.

Application permissions

Permission Why it is needed
Channel.ReadBasic.All List the channels the bot can work with
Chat.Create Start a chat with a user
Chat.Read.WhereInstalled Read messages in chats where the app is installed
Chat.ReadWrite.WhereInstalled Read and write messages in those chats
ChatMember.Read.WhereInstalled Read the members of those chats
Team.ReadBasic.All List the teams the bot can work with

Step 2: Create the Azure Bot resource

  1. Create an Azure Bot resource in the Azure portal.
  2. Choose Single Tenant and Use existing app registration, using the application ID from step 1.
  3. In Settings > Configuration, set the messaging endpoint to the webhook URL shown on the Teams card in XTM One — it ends with /api/channels/teams/messages.
  4. In Channels, add the Microsoft Teams channel.

Step 3: Connect the bot in XTM One

  1. Go to Settings > Channels & Bots and click Configure on the Microsoft Teams card.
  2. Paste the application ID into App ID / Client ID.
  3. Paste the client secret into App Password / Client Secret.
  4. Paste the directory ID into Entra ID (Azure AD) Tenant ID.
  5. Click Save Channel. The card shows Connected and displays the webhook URL used in step 2.

The application ID is also what authenticates incoming traffic: XTM One validates the signed token on every Teams request against it, so requests that do not come from the Bot Framework are rejected.

Step 4: Build and install the Teams app package

Teams needs an app package to install the bot in your tenant.

  1. Open the Teams Developer Portal and create the app.
  2. Use the manifest template offered by the Setup Guide button on the Teams card — it already carries your deployment name — and replace the placeholders with your application ID and domain.
  3. Declare the resource-specific consent permissions listed below under authorization.permissions.resourceSpecific.
  4. Package manifest.json, color.png, and outline.png into a .zip file.
  5. Install it through the Teams admin center, or sideload it if your tenant allows custom apps.

Resource-specific permissions

Permission Why it is needed
ChannelMessage.Read.Group Read channel messages in teams where the app is installed
ChatMessage.Read.Chat Read messages in chats where the app is installed

Enable file support if users will send attachments

Set supportsFiles to true in the manifest for the bot to receive files sent in personal chats. Files shared in group chats and channels are retrieved through Graph and work regardless of this setting.

Step 5: Enable Teams on an agent

Open the agent, go to Configuration > Channels & Bots, and enable Microsoft Teams:

  • Turn on Receive so the agent answers Teams messages, and optionally restrict it to specific channels.
  • Turn on Publish if the agent should post to Teams on its own, and pick the channels it may post to.
  • Adjust Allow anonymous, Allow private, and Only mention within what the bot allows.

The channel picker resolves team and channel identifiers for you. Group chats are never listed — their identifiers cannot be enumerated — so they are governed by Allow private, Only mention, and agent routing instead of by whitelists.

Standard, private, and shared channels

Teams delivers messages differently depending on the channel type, and XTM One compensates for it.

  • In standard channels, every message is delivered to the bot, so mention behavior is entirely up to your settings.
  • In private and shared channels, Microsoft only delivers messages that @mention the bot. After the bot has answered a mention there, XTM One subscribes to that thread through Graph so follow-up messages keep reaching the agent without a new mention. Monitoring stops after seven days of inactivity, and the bot posts a short notice when it does.

What the agent can do in Teams

When Publish is on, the agent gets Teams tools: send a message or an adaptive card to a channel, a personal chat, or a group chat, edit a message it already sent, read channel messages, chat messages, or thread replies, list teams and channels, list chats, upload a file to a channel, download a file it received, and delete one of its own channel messages.

Chat and group chat messaging is not governed by channel whitelists — those cover teams and channels. Long answers are split automatically, and images are delivered as separate cards because Teams rejects an activity carrying both text and attachments.

Best practices

  • Grant admin consent once and keep the client secret in a password manager. When it expires, Teams stops delivering messages with no other symptom — use Edit credentials to paste the new value.
  • Note the secret expiry date in your calendar. Entra ID secrets are time-limited and this is the most common cause of a bot going silent months after a working setup.
  • Use Only when mentioned for busy team channels; thread continuation keeps follow-up questions working without a new mention.
  • Keep the publish whitelist to the channels the agent genuinely reports into.

Troubleshooting

The bot is installed but never answers. Check the messaging endpoint in the Azure Bot resource, confirm the Teams channel is added there, and confirm an agent has Teams Receive enabled.

It worked and suddenly stopped. The client secret has almost certainly expired. Create a new one and update it in XTM One.

The bot answers in standard channels but not in a private one. That is expected until the bot has been @mentioned in the thread once. After that first mention, follow-ups are picked up for seven days.

Messages are rejected as unauthorized. The application ID stored in XTM One does not match the app the Azure Bot resource uses. They must be the same registration.

The bot cannot read files sent in a chat. Confirm supportsFiles is set in the manifest for personal chats, and that admin consent was granted for the Graph permissions used to fetch files shared in channels.

Mentions are not detected in group chats. Teams sometimes strips the mention data from the delivered message. XTM One re-reads the message through Graph to recover it, which requires the resource-specific permissions from step 4 to be declared and consented.

Next step

Connect another platform, such as Slack, or review how agents use channels in Agents.