How to control and identify target channel/group for proactive notifications in multi-tenant Teams bot?

[gauravsarwal]

I’m building a multi-tenant Microsoft Teams bot (published via marketplace most probably) that supports all scopes: personal (1:1), group chat, and channel.

My use case is to send proactive notifications (e.g., when a new ticket is created in my system), need approval for a ticket, SLA is breached etc.

Here’s where I’m confused:

A customer tenant can install my bot in multiple places:
Personal chat (multiple users)
Multiple group chats
Multiple channels across different teams
For proactive messaging, I understand that I must store the conversation reference (conversationId etc.) when the bot is installed or used.
However, if the bot is installed in, say, 5 different channels or in 10 groups, I don’t have any prior knowledge of which channel should receive notifications from my back end when something happened, for example a ticket is created from UI and assigned to 2 people etc.

My questions:

How do production-grade apps determine which channel (or scope) to send proactive notifications to when multiple installations exist?
Is there any built-in way in Teams to restrict installation to specific channels or groups, or must this always be handled in the app logic?

What is the recommended pattern for:

Mapping a Teams channel/group to a business entity (e.g., project, customer, ticket queue)?
Allowing customers to configure where notifications should go?
Should this be handled via:
A registration/configuration step inside Teams (e.g., bot command or adaptive card)?
Or via an external admin UI?

What I’m currently considering:

Capturing all conversation references on install (conversationUpdate)
Asking users to explicitly “register” a channel for notifications
Storing mapping like: Channel → Project/Customer → Notification Type

But I want to confirm if this is the recommended approach or if there’s a better/native way.

Any guidance, best practices, or real-world patterns would be very helpful.

[Nivedipa-MSFT]

Hello gauravsarwal - Thanks for bringing this issue to our attention.
Teams does not offer a built-in feature to automatically route notifications, so you'll need to create your own mapping process.

Recommended approach: Capture conversation references during installation, then have users register each channel or group for specific notification types and business entities (like projects or queues). Store this mapping and send proactive messages only to the appropriate, registered targets. For personal notifications such as approvals or assignments, map users by their AAD objectId to their direct conversation reference.

You can use Adaptive Cards for straightforward registration within Teams, and an external admin portal for more advanced configuration. This method is commonly used by production apps like ServiceNow and Jira, so your approach aligns with industry standards.

Please let us know if you have any other query here.

[gauravsarwal]

Nivedipa-MSFT (@Nivedipa-MSFT) Thanks for replying back, When you say

_Capture conversation references during installation, then have users register each channel or group for specific notification types and business entities (like projects or queues) _

What do you mean here by users register each channel or group for specific notification types and business entities (like projects or queues)? When I add my bot to a channel or group do i need to ask this information via some adaptive card and save to database as when I install the bot in a group or channel without explicitly asking user no way to know that it will receive what kind of notification.

Store this mapping and send proactive messages only to the appropriate, registered targets

By storage you mean to save it to database or some persistence storage?

For personal notifications such as approvals or assignments, map users by their AAD objectId to their direct conversation reference.

I thought in 1:1 chat for personal notification in user interaction with bot only conversationId is sufficient and will remain same as long as bot is installed in personal scope same for group and channel etc. Why I need to map users by their AAD objectId to their direct conversation reference or you mean to save AAD objectId and conversationId in back end to map that user to conversation. Can you please clarify.

You can use Adaptive Cards for straightforward registration within Teams, and an external admin portal for more advanced configuration.

By this you mean to get context about notification and their mapping to channel, group etc? I am not sure how it can be dome in admin portal because conversationId is only available inside code context or misunderstood something here.

Also, I did not find link to Team SDK documentation which has events list for below one so that I can understand when to use which on, for example when Bot is added to a channel or group, when bot is removed from a channel etc.

Thanks again for your help and patience here.

[Nivedipa-MSFT]

Hello gauravsarwal - These are excellent questions. I'll address each one directly below.

1. "What do you mean by users register each channel or group?"

Exactly as you guessed—when the bot is added to a channel or group, it doesn't automatically know which notifications to send. You need to specify this explicitly.

For example: When your bot receives the OnMembersAdded or installationUpdate event (i.e., when the bot is added to a channel), you can send an Adaptive Card to prompt configuration.

2. "By storage you mean to save it to database?"

Yes, use a database or persistent storage like SQL, Cosmos DB, or PostgreSQL. Avoid in-memory or local file storage, since the data should persist through restarts and scaling. For each registration, store the necessary mapping information.

3. "Why map AAD objectId? Isn't conversationId enough for 1:1?"

While the 1:1 conversationId remains the same as long as the bot is installed, you also need the AAD objectId for backend lookups. For example, if your system assigns a ticket to "Alice," it knows her AAD objectId but not her Teams conversationId. The mapping helps resolve this.

So, store both: use the AAD objectId as the key, with conversationId and serviceUrl as the delivery address. Without this mapping, the backend can't identify the correct conversation.

The bot code captures and stores these conversation references, while the admin portal manages the mappings using this data.

4. "How can an admin portal work if conversationId is only available in code?"

The admin portal can't generate conversationIds—they originate from Teams. In practice, the bot captures and saves them when added, and the portal manages the mappings.

5. Events reference — Teams AI Library vs Bot Framework SDK

Your screenshot is from the Teams AI Library (Microsoft.Teams.AI), not the base Bot Framework TeamsActivityHandler.

The admin portal queries your database (populated by the bot code). It displays friendly names like channel or team names for admin configuration, while the actual conversationId is used internally for message delivery.

Key events for proactive messaging:

• Bot installed in channel/group: OnMembersAdded—check if the added member's Id matches the bot's Id, then send a configuration Adaptive Card and save the conversation reference.
• Bot removed from channel/group: OnChannelMemberRemoved or OnMembersRemoved—remove the stored conversation reference from your database.
• Bot installed in personal scope: OnMembersAdded in a personal context—save the 1:1 conversation reference mapped to the user's AAD objectId.

Reference Docs:
https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/subscribe-to-conversation-events?tabs=dotnet
https://learn.microsoft.com/en-us/microsoftteams/platform/bots/bot-concepts?tabs=csharp%2Cdotnet
https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/send-proactive-messages?tabs=dotnet
https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/subscribe-to-conversation-events?tabs=dotnet#installation-update-event

Please let us know if you have any further query here.

[microsoft-github-policy-service]

Tell us about your experience!

Hi @gauravsarwal! This issue is closed in our system. We would like your feedback on your experience with our support team and Platform.

Best regards,
Teams Platform

[Nivedipa-MSFT]

Hello gauravsarwal - If you found the information above helpful, I would appreciate it if you could share your feedback.
Your feedback is important to us. Please rate us: 🤩 Excellent 🙂 Good 😐 Average 🙁 Needs Improvement 😠 Poor