Get context for your Microsoft Teams bot

Your bot can access additional context about the team or chat, such as user profile. This information can be used to enrich your bot's functionality and provide a more personalized experience.

Fetch the team roster

Your bot can query for the list of team members and their basic profiles. The basic profiles include Teams user IDs and Microsoft Entra information such as name and object ID. You can use this information to correlate user identities. For example, check if a user logged into a tab through Microsoft Entra credentials is a team member.

REST API example

Directly issue a GET request on /conversations/{teamId}/members/, using the serviceUrl value as the endpoint.

The teamId can be found in the channeldata object of the activity payload that your bot receives in the following scenarios:

• When a user messages or interacts with your bot in a team context. For more information, see receiving messages.
• When a new user or bot is added to a team. For more information, see bot or user added to a team.

GET /v3/conversations/19:[email protected]/members

Response body
[{
    "id": "29:1GcS4EyB_oSI8A88XmWBN7NJFyMqe3QGnJdgLfFGkJnVelzRGos0bPbpsfJjcbAD22bmKc4GMbrY2g4JDrrA8vM06X1-cHHle4zOE6U4ttcc",
    "objectId": "9d3e08f9-a7ae-43aa-a4d3-de3f319a8a9c",
    "givenName": "Larry",
    "surname": "Brown",
    "email": "[email protected]",
    "userPrincipalName": "[email protected]"
}, {
    "id": "29:1bSnHZ7Js2STWrgk6ScEErLk1Lp2zQuD5H2qQ960rtvstKp8tKLl-3r8b6DoW0QxZimuTxk_kupZ1DBMpvIQQUAZL-PNj0EORDvRZXy8kvWk",
    "objectId": "76b0b09f-d410-48fd-993e-84da521a597b",
    "givenName": "John",
    "surname": "Patterson",
    "email": "[email protected]",
    "userPrincipalName": "[email protected]"
}, {
    "id": "29:1URzNQM1x1PNMr1D7L5_lFe6qF6gEfAbkdG8_BUxOW2mTKryQqEZtBTqDt10-MghkzjYDuUj4KG6nvg5lFAyjOLiGJ4jzhb99WrnI7XKriCs",
    "objectId": "6b7b3b2a-2c4b-4175-8582-41c9e685c1b5",
    "givenName": "Rick",
    "surname": "Stevens",
    "email": "[email protected]",
    "userPrincipalName": "[email protected]"
}]

.NET example

Call GetConversationMembersAsync using Team.Id to return a list of user IDs. Call GetConversationMembersAsync to get userRole property return the value as user.

// Fetch the members in the current conversation
var connector = new ConnectorClient(new Uri(context.Activity.ServiceUrl));
var teamId = context.Activity.GetChannelData<TeamsChannelData>().Team.Id;
var members = await connector.Conversations.GetConversationMembersAsync(teamId);

// Concatenate information about all members into a string
var sb = new StringBuilder();
foreach (var member in members.AsTeamsChannelAccounts())
{
    sb.AppendFormat(
        "GivenName = {0}, TeamsMemberId = {1}",
        member.Name, member.Id);

    sb.AppendLine();
}

// Post the member info back into the conversation
await context.PostAsync($"People in this conversation: {sb.ToString()}");

Node.js or TypeScript example

[...]
import * as builder from "botbuilder";
[...]

var teamId = session.message.sourceEvent.team.id;
connector.fetchMembers(
  (<builder.IChatConnectorAddress>session.message.address).serviceUrl,
  teamId,
  (err, result) => {
    if (err) {
      session.endDialog('There is some error');
    }
    else {
      session.endDialog('%s', JSON.stringify(result));
    }
  }
);

Fetch user profile or roster in personal or group chat

You can make the API call for any personal chat to obtain the profile information of the user chatting with your bot.

The API call, SDK methods, and the response object are identical to fetching the team roster. The only difference is you pass the conversationId instead of the teamId.

Fetch the list of channels in a team

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

REST API example

Directly issue a GET request on /teams/{teamId}/conversations/, using the serviceUrl value as the endpoint.

The only source for teamId is a message from the team context. The message is either a message from a user or the message that your bot receives when it is added to a team. For more information, see bot or user added to a team.

GET /v3/teams/19%3A033451497ea84fcc83d17ed7fb08a1b6%40thread.skype/conversations

Response body
{
    "conversations": [{
        "id": "19:[email protected]",
        "name": null
    }, {
        "id": "19:[email protected]",
        "name": "Materials"
    }, {
        "id": "19:[email protected]",
        "name": "Design"
    }, {
        "id": "19:[email protected]",
        "name": "Marketing"
    }]
}

.NET example

The following example uses the FetchChannelList call from the Teams extensions for the Bot Builder SDK for .NET:

ConversationList channels = client.GetTeamsConnectorClient().Teams.FetchChannelList(activity.GetChannelData<TeamsChannelData>().Team.Id);

Node.js example

The following example uses fetchChannelList call from the Teams extensions for the Bot Builder SDK for Node.js:

var teamId = session.message.sourceEvent.team.id;
connector.fetchChannelList(
  (session.message.address).serviceUrl,
  teamId,
  (err, result) => {
    if (err) {
      session.endDialog('There is an error');
    }
    else {
      session.endDialog('%s', JSON.stringify(result));
    }
  }
);

Get clientInfo in your bot context

You can fetch the clientInfo within your bot's activity. The clientInfo contains the following properties:

• Locale
• Country
• Platform
• Timezone

JSON example

[
    {
        "type": "clientInfo",
        "locale": "en-US",
        "country": "US",
        "platform": "Windows",
        "timezone": "Asia/Calcutta"
    }
]

C# example

var connector = new ConnectorClient(new Uri(context.Activity.ServiceUrl));

{
    var clientinfo = context.Activity.Entities[0];
    await context.PostAsync($"ClientInfo: clientinfo ");
}

See also

Bot Framework samples.