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.

Graph notifications for private channels

Follow-ups in private and shared channels reach XTM One as Microsoft Graph notifications on <BASE_URL>/api/channels/teams/graph-notifications, a public endpoint Microsoft must be able to reach. Every subscription XTM One creates carries a random secret that Microsoft sends back with each notification; XTM One stores it encrypted and checks it, together with the subscription id, against what it recorded for the channel. Every notification of a delivery is checked before any work is queued for it, so one the verification policy below refuses costs nothing beyond that check. In the default mode, a forged notification that carries what earlier releases accepted (such as the copilot_ value for a channel with no record) is still acted on: one task per distinct message it names, the same message named twice in one delivery counting once. A delivery larger than 4 MiB, far above what Microsoft sends, is refused with HTTP 413, and one XTM One cannot check or record because its Redis does not answer gets HTTP 503, so Microsoft delivers it again later. A follow-up posted while no subscription could notify it - a subscription Microsoft removed, or one XTM One had to recreate - is read back from Microsoft Graph once the channel has a subscription again, up to four hours back, and answered once.

By default, XTM One also acts on a notification that earlier releases acted on without that proof: one carrying the secret of the subscriptions created before 2026-07-02 (copilot_ followed by the team id, which anyone who knows the team id can compute), or the channel's secret under another subscription id. Each case is logged as a warning, at most once every 15 minutes, and reported by the security audit in Settings > Security. Subscriptions created by an earlier release are kept and renewed as before, so nothing changes for your channels on upgrade.

To refuse every notification that does not prove its subscription, turn on Require verified integration notifications in Settings > Security > Security options, or set INTEGRATION_NOTIFICATIONS_REQUIRE_VERIFICATION=true - the switch that also refuses the unverified Slack, Microsoft Graph and LinkedIn notifications of integrations. The maintenance pass, which runs shortly after XTM One starts and then about once an hour, then replaces the subscriptions whose secret is derivable or can no longer be decrypted. Microsoft allows one subscription per channel, so it deletes the old one before creating the new one; what the old one was still delivering is accepted for four hours, and what was posted in between is read back from Microsoft Graph.

If Microsoft refuses the replacement

With the option on, a replacement deletes the old subscription first. If Microsoft Graph then refuses to create the new one, that channel's follow-ups stop until a later pass creates it, and the log says Graph subscription creation failed. With the option off, no subscription is deleted to be replaced.

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.

Private-channel follow-ups after an upgrade or a SECRET_KEY change. By default nothing changes: a subscription created by an older release keeps working and is renewed, and after a SECRET_KEY change a notification naming the subscription recorded for its channel is still acted on, with a warning. With Require verified integration notifications on, such subscriptions are replaced by the maintenance pass instead (see Graph notifications for private channels). Nothing needs to change in Teams or Entra ID: the same permissions and the same public endpoint are used. Microsoft must be able to reach <BASE_URL>/api/channels/teams/graph-notifications, which also receives the subscription's lifecycle notifications.

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.