Edit

Get Teams specific context for your bot

  • Article

Important

The code samples in this section are based on version 4.6 and later versions of the Bot Framework SDK. If you are looking for documentation for earlier versions, see the bots - v3 SDK section in the Legacy SDKs folder of the documentation.

A bot can access additional context data about a team or chat where it's installed. This information can be used to enrich the bot's functionality and provide a more personalized experience.

Fetch the roster or user profile

Your bot can query for the list of members and their basic user profiles, including Teams user IDs and Microsoft Entra information, such as name and objectId. You can use this information to correlate user identities. For example, to check whether a user logged into a tab through Microsoft Entra credentials is a member of the team. For get conversation members, minimum or maximum page size depends on the implementation. Page size less than 50, are treated as 50, and greater than 500, are capped at 500. Even if you use the non-paged version, it's unreliable in large teams and must not be used. For more information, see changes to Teams Bot APIs for fetching team or chat members.

Note

  • Pagination is available in a team and a channel.
  • Pagination isn't supported in chats. For chats, the entire roster is always returned.

The following sample code uses the paged endpoint for fetching the roster:

public class MyBot : TeamsActivityHandler
{
    protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
    {
        var members = new List<TeamsChannelAccount>();
        string continuationToken = null;

        do
        {   
            // Gets a paginated list of members of one-on-one, group, or team conversation.
            var currentPage = await TeamsInfo.GetPagedMembersAsync(turnContext, 100, continuationToken, cancellationToken);
            continuationToken = currentPage.ContinuationToken;
            members.AddRange(currentPage.Members);
         }
         while (continuationToken != null);
     }
}

After you fetch the roster or user profile, you can get details of a single member. Currently, to retrieve information for one or more members of a chat or team, use the Microsoft Teams bot APIs TeamsInfo.GetMembersAsync for C# or TeamsInfo.getMembers for TypeScript APIs.

Get single member details

You can also retrieve the details of a particular user using their Teams user ID, UPN, or Microsoft Entra Object ID.

The following sample code is used to get single member details:

public class MyBot : TeamsActivityHandler
{
    protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
    {   
        // Gets the account of a single conversation member.
        // This works in one-on-one, group, and team scoped conversations.
        var member = await TeamsInfo.GetMemberAsync(turnContext, turnContext.Activity.From.Id, cancellationToken);
    }
}

After you get details of a single member, you can get details of the team. Currently, to retrieve information for a team, use the Teams bot APIs TeamsInfo.GetMemberDetailsAsync for C# or TeamsInfo.getTeamDetails for TypeScript.

Get team's details

When installed in a team, your bot can query for metadata about that team including the Microsoft Entra group ID.

The following sample code is used to get team's details:

public class MyBot : TeamsActivityHandler
{
    protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
    {
        // Gets the details for the given team id. This only works in team scoped conversations.
        // TeamsGetTeamInfo: Gets the TeamsInfo object from the current activity.
        TeamDetails teamDetails = await TeamsInfo.GetTeamDetailsAsync(turnContext, turnContext.Activity.TeamsGetTeamInfo().Id, cancellationToken);
        if (teamDetails != null) {
            await turnContext.SendActivityAsync($"The groupId is: {teamDetails.AadGroupId}");
        }
        else {
            // Sends a message activity to the sender of the incoming activity.
            await turnContext.SendActivityAsync($"Message did not come from a channel in a team.");
        }
    }
}

After you get details of the team, you can get the list of channels in a team. Currently, to retrieve information for a list of channels in a team, use the Teams bot APIs TeamsInfo.GetTeamChannelsAsync for C# or TeamsInfo.getTeamChannels for TypeScript APIs.

Get the list of channels in a team

Your bot can query the list of channels in a team.

Note

  • The name of the default General channel is returned as null to allow for localization.
  • The channel ID for the General channel always matches the team ID.

The following sample code is used to get the list of channels in a team:

public class MyBot : TeamsActivityHandler
{
    // Override this in a derived class to provide logic specific to Message activities.
    protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
    {
        // Returns a list of channels in a Team. This only works in team scoped conversations.
        IEnumerable<ChannelInfo> channels = await TeamsInfo.GetTeamChannelsAsync(turnContext, turnContext.Activity.TeamsGetTeamInfo().Id, cancellationToken);

        // Sends a message activity to the sender of the incoming activity.
        await turnContext.SendActivityAsync($"The channel count is: {channels.Count()}");
    }
}

Teams bot samples

Code sample

For complete working samples demonstrating the functionality, see the following Teams samples for Bot Framework:

Sample name Description .NET Node.js Python Manifest
Teams conversation bot This sample shows how to use different bot conversation events available in bot framework v4 for personal and teams scope. View View View View
Authentication with OAuthPrompt This sample shows authentication and basic messaging in Bot Framework v4. View View View View
Teams file upload This sample shows how to use files with a bot in a one-to-one conversation. View View View View
Dialog (referred as task module in TeamsJS v1.x) This sample shows how to use a dialog and values from cards in it for a message extension. View View View View
Start new thread in a channel This sample shows how to use a new thread in a channel using bot. View View View View
Teams app localization This sample shows how to use Teams app localization using bot and tab. View View NA View

Next step

Send and receive files using bot

See also