From 03ade44f5e19cc91dae3777dea7bd37504e67267 Mon Sep 17 00:00:00 2001 From: SirajShaik-MSFT Date: Mon, 27 Jul 2026 10:24:31 +0530 Subject: [PATCH 1/3] Initial draft --- msteams-platform/TOC.yml | 3 + .../conversations/detect-app-version.md | 107 ++++++++++++++++++ 2 files changed, 110 insertions(+) create mode 100644 msteams-platform/bots/how-to/conversations/detect-app-version.md diff --git a/msteams-platform/TOC.yml b/msteams-platform/TOC.yml index 49b441a7056..7a032a2f0f4 100644 --- a/msteams-platform/TOC.yml +++ b/msteams-platform/TOC.yml @@ -34,6 +34,9 @@ - name: Expose slash commands href: agents-in-teams/agent-slash-commands.md displayName: private messages, ephemeral messages, targeted messages, message extension command, bot command, agent command, named command + - name: Detect installed app version + href: bots/how-to/conversations/detect-app-version.md + displayName: channelData, app version, installationUpdate, upgrade, version detection, manifest version - name: Extend agents to Microsoft 365 hubs href: /microsoft-365/copilot/extensibility/ecosystem?toc=/microsoftteams/platform/toc.json&bc=/microsoftteams/platform/breadcrumb/toc.json displayName: AI bot, Teams AI library, Teams SDK, custom agent diff --git a/msteams-platform/bots/how-to/conversations/detect-app-version.md b/msteams-platform/bots/how-to/conversations/detect-app-version.md new file mode 100644 index 00000000000..a2281b8c387 --- /dev/null +++ b/msteams-platform/bots/how-to/conversations/detect-app-version.md @@ -0,0 +1,107 @@ +--- +title: Detect installed app version in agent activities +description: Learn how to use channelData.app.version to determine the installed version of your app and adapt agent behavior based on available features, permissions, or capabilities. +ms.localizationpriority: medium +ms.topic: how-to +ms.date: 07/24/2026 +zone_pivot_groups: teams-sdk-languages +--- + +# Detect installed app version in agent activities + +Teams includes the installed app version in all activity payloads delivered to your agent through the `channelData.app.version` field. This field appears in messages, invokes, and `installationUpdate` activities. + +Use the app version to build logic that adapts your agent's behavior based on the version of the app the user has installed. + +## How it works + +Every activity delivered to your agent in a 1:1 chat includes a `channelData.app` object with the `id` and `version` of the installed app: + +```json +{ + "type": "message", + "conversation": { "id": "conv-id" }, + "channelData": { + "app": { + "id": "your-app-id", + "version": "1.2.3" + } + } +} +``` + +The `version` value corresponds to the version declared in your app manifest. Compare this value against known version numbers to determine what features or permissions are available. + +## When to use version detection + +Version detection is useful in several scenarios: + +### Check feature or permission availability + +If a newer version of your manifest introduces a new capability (such as sessions, new RSC permissions, or additional scopes), your agent can check the installed version and enable or disable functionality accordingly. + +### Prompt users to update + +When your agent detects an outdated version, it can send a message encouraging the user to update the app to access new features. + +### Gather install base metrics + +Track version distribution across your user base to understand adoption of newer releases and plan deprecation timelines. + +### Detect session support + +If your agent has both session-enabled and non-session versions in use, checking the version helps determine whether to create sessions proactively or fall back to the single chat model. For more information, see [Structure conversations with sessions](agent-sessions.md). + +## Read the version from an activity + +::: zone pivot="teams-sdk-csharp" + + + +::: zone-end + +::: zone pivot="teams-sdk-typescript" + + + +::: zone-end + +::: zone pivot="teams-sdk-python" + + + +::: zone-end + +## Detect app upgrades + +When a user upgrades the app to a newer version, your agent receives an `installationUpdate` activity with `action: "upgrade"`. The new version is included in `channelData.app.version`: + +```json +{ + "type": "installationUpdate", + "action": "upgrade", + "conversation": { "id": "base-conversation-id" }, + "channelData": { + "app": { + "version": "2.0.0" + } + } +} +``` + +The full set of `installationUpdate` actions: + +| Action | When | +|---|---| +| `add` | Agent is installed | +| `remove` | Agent is uninstalled | +| `upgrade` | App version is upgraded with property value changes | +| `add-upgrade` | Agent is added as part of an app upgrade | +| `remove-upgrade` | Agent is removed as part of an app upgrade | + +Use the `upgrade` action to detect version changes and migrate user state, adjust behavior, or trigger setup flows as needed. + +## See also + +- [Structure conversations with sessions](agent-sessions.md) +- [Conversation events in your Teams bot](subscribe-to-conversation-events.md) From aa3ec1c92d8e745b10090f402c3ca951e9813e01 Mon Sep 17 00:00:00 2001 From: SirajShaik-MSFT Date: Mon, 27 Jul 2026 10:29:11 +0530 Subject: [PATCH 2/3] Update detect-app-version.md --- .../bots/how-to/conversations/detect-app-version.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/msteams-platform/bots/how-to/conversations/detect-app-version.md b/msteams-platform/bots/how-to/conversations/detect-app-version.md index a2281b8c387..78f96fe5644 100644 --- a/msteams-platform/bots/how-to/conversations/detect-app-version.md +++ b/msteams-platform/bots/how-to/conversations/detect-app-version.md @@ -56,19 +56,19 @@ If your agent has both session-enabled and non-session versions in use, checking ::: zone pivot="teams-sdk-csharp" - +TODO ::: zone-end ::: zone pivot="teams-sdk-typescript" - +TODO ::: zone-end ::: zone pivot="teams-sdk-python" - +TODO ::: zone-end From 08270ab13540e5e1f04aeacbb69ac11319ec3c64 Mon Sep 17 00:00:00 2001 From: SirajShaik-MSFT Date: Tue, 28 Jul 2026 17:34:13 +0530 Subject: [PATCH 3/3] Update detect-app-version.md --- .../bots/how-to/conversations/detect-app-version.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/msteams-platform/bots/how-to/conversations/detect-app-version.md b/msteams-platform/bots/how-to/conversations/detect-app-version.md index 78f96fe5644..12d7aa226cd 100644 --- a/msteams-platform/bots/how-to/conversations/detect-app-version.md +++ b/msteams-platform/bots/how-to/conversations/detect-app-version.md @@ -30,7 +30,7 @@ Every activity delivered to your agent in a 1:1 chat includes a `channelData.app } ``` -The `version` value corresponds to the version declared in your app manifest. Compare this value against known version numbers to determine what features or permissions are available. +The `version` value is the manifest version (`version` property in the app manifest), not a runtime or SDK version. Since different users may have different versions of your app installed, your agent can branch its logic based on this value to determine what features or permissions are available in each user's context. ## When to use version detection