Share via

Bot Multi-Tenant to Single-Tenant Migration — Expected User Experience When Changing botId in Manifest via Global Publish (Developer Portal) vs Tenant Upload (Admin Center)

Yifan Shao 40 Reputation points Microsoft Employee
2026-05-26T22:24:04.6733333+00:00

Context

We are migrating a Microsoft Teams bot from a multi-tenant AAD app registration to a single-tenant AAD app registration as part of our compliance and security posture improvements. As the final step of the migration, we need to update the botId in the Teams app manifest to point to the new single-tenant bot registration and then publish the updated app package globally to all tenants where the app is currently installed.

What We Have Tested So Far

In our test environment, we uploaded the updated manifest (with the new botId) to a specific test tenant via Teams Admin Center (admin.teams.microsoft.com). The observed behavior was:

  1. After the manifest update, end users see an "An update is available" banner in the existing 1:1 bot chat.
  2. When the user clicks Update:
    • The existing 1:1 chat history with the bot appears to be wiped.
    • A new app instance is effectively created.
    • The bot sends a new welcome message in what looks like a fresh conversation thread.

We understand this is because changing the botId introduces a new bot identity, and Teams treats the new identity as a different bot — so existing conversation references no longer map cleanly to the new bot.

What We Need to Validate for Production

For the actual production migration, we cannot use Teams Admin Center because the app is published globally to all tenants. The published app needs to be updated via Teams Developer Portal (dev.teams.microsoft.com) and goes through the standard global publish/approval flow ring by ring.

Our core question: Is the end-user experience after a global manifest update (via Developer Portal) the same to what we observed in the tenant-level update via Admin Center — specifically regarding:

  • The "update available" banner behavior
  • Loss / orphaning of existing 1:1 chat history
  • Creation of a new conversation thread
  • Welcome message re-trigger
  • Invalidation of stored conversation references for proactive messaging

Why We Cannot Easily Test This in Production

The Developer Portal global publish flow is irreversible in practice and affects all tenants where the app is installed. We do not have a way to test the global publish path in isolation without impacting real users. Therefore, we are relying on understanding whether the client-side update behavior in Teams is determined by:

  • (a) The publish channel (Admin Center tenant upload vs Developer Portal global publish), or
  • (b) The content of the manifest change itself (specifically, the botId change), independent of how the package was delivered.

Our working assumption is (b) — the behavior is driven by the botId change, not the publish channel — but we would like official confirmation before rolling out to production.

What we have not been able to validate:

  • Whether the Developer Portal global publish path produces a different (or identical) user experience.
  • After we update and publish our app in Developer Portal for each and every ring, will we still need to do tenant level install or the changes will automatically apply to each tenant/user/app, and the update banner will show up automatically?

Any guidance, documentation links, or confirmation from the Teams platform team would be greatly appreciated. This will directly influence our customer communication plan and migration rollout strategy.

Microsoft Teams | Development
Microsoft Teams | Development

Building, integrating, or customizing apps and workflows within Microsoft Teams using developer tools and APIs

0 comments

Answer accepted by question author

Teddie-D 16,370 Reputation points Microsoft External Staff Moderator
2026-05-27T01:03:04.9433333+00:00

Hi @Yifan Shao

Please note that we're not Microsoft support; this is a user-to-user support forum. Moderators here don’t have backend access to Microsoft systems, so we can only provide technical guidance based on public resources.

Your understanding is largely correct, the behavior is driven by the manifest change (specifically botId), not the publishing channel.

In Microsoft Teams, the botIdrepresents the bot’s identity. When you update the manifest to use a different botId, Teams treats it as a new bot instance, even if the Teams app ID remains the same.

As a result, the expected user experience may include:

  • Users seeing an Update available prompt once the updated app version becomes available in their tenant/client.
  • Existing 1:1 chat with the previous bot no longer being used and not continuing with the updated bot.
  • A new conversation thread being created with the updated bot.
  • A welcome message being triggered again if your bot sends one on installation or conversation start.
  • Previously stored conversation references used for proactive messaging typically needing to be re-established, as they are tied to the previous bot identity.

The Teams client determines update behavior based on manifest differences, not how the app package is delivered. There is no documented difference between Admin Center uploads and Developer Portal / global publish. Therefore, you should expect the same end-user experience in production.

After publishing via Developer Portal, the updated version becomes available to all tenants where the app is installed. Users will be prompted to update the app in place (no reinstall required), since changes such as updating the botId can require consent.

Reference: Microsoft Teams apps update experience and admin role - Microsoft Teams | Microsoft Learn 

I hope this information is helpful. 

Note: Please follow the steps in our documentation to enable e-mail notifications if you want to receive the related email notification for this thread. 

Was this answer helpful?

1 person found this answer helpful.
0 comments

1 additional answer

Sort by: Most helpful
Most helpful Newest Oldest

  1. AI answer

    2026-05-26T22:24:27.7666667+00:00

    The end-user behavior is determined by the manifest change (specifically the botId change), not by whether the package is distributed via Teams Admin Center (tenant upload) or Developer Portal (global publish).

    From the documented behavior of app updates:

    • Changing the botId in the app manifest is explicitly called out as a change that:
      • Requires user/admin consent for the update.
      • Causes a new bot instance to engage with users.
    • When the botId is changed:
      • The previous bot is no longer part of the app because its botId is no longer present in the manifest.
      • The previous bot’s chat history is preserved but becomes orphaned from the new app/bot identity.
      • The previous bot reverts to the icon and name from its original Bot Framework registration and is no longer governed by app permission policies.

    This behavior is tied to the botId change itself, not to the distribution channel. Therefore, when the globally published app (via Developer Portal) is updated with a new botId, the expected user experience is the same pattern observed in the tenant-level test:

    • Users will see an update flow that requires consent when the app version with the new botId is applied.
    • The existing 1:1 conversation with the old bot identity is preserved but effectively disconnected from the new bot (appearing as a separate, historical thread).
    • A new conversation with the new bot identity is created, and the bot will send its welcome message as in a fresh install.
    • Any stored conversation references tied to the old botId will no longer be valid for proactive messaging with the new bot, because they point to the previous bot identity.

    The documentation does not differentiate client behavior based on whether the app package was delivered through Admin Center or Developer Portal; it only specifies behavior based on changes in the manifest (such as botId and other permission-related properties). This aligns with assumption (b): the behavior is driven by the botId change itself.

    References:

    AI-generated content may be incorrect. Read our transparency notes for more information.

    Was this answer helpful?

Your answer

Answers can be marked as 'Accepted' by the question author and 'Recommended' by moderators, which helps users know the answer solved the author's problem.