Get Teams specific context for your bot

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 Resources folder of the documentation.

A bot can access additional context data about a team or chat where it is 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 Azure Active Directory (AAD) 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 AAD 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 is unreliable in large teams and must not be used. For more information, see changes to Teams Bot APIs for fetching team or chat members.

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
        {
            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 AAD 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)
    {
        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 Microsoft 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 AAD 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)
    {
        TeamDetails teamDetails = await TeamsInfo.GetTeamDetailsAsync(turnContext, turnContext.Activity.TeamsGetTeamInfo().Id, cancellationToken);
        if (teamDetails != null) {
            await turnContext.SendActivityAsync($"The groupId is: {teamDetails.AadGroupId}");
        }
        else {
            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 Microsoft 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
{
    protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
    {
        IEnumerable<ChannelInfo> channels = await TeamsInfo.GetTeamChannelsAsync(turnContext, turnContext.Activity.TeamsGetTeamInfo().Id, cancellationToken);

        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 Description .NET JavaScript Python
Teams conversation bot Messaging and conversation event handling. View View View
Authentication with OAuthPrompt Authentication and basic messaging in Bot Framework v4. View View View
Teams file upload Exchanging files with a bot in a one-to-one conversation. View View View
Task module Retrieving a task module and values from cards in it for a messaging extension. View View View
Start new thread in a channel Creating a new thread in a channel. View View View

Next step