{"id":4135,"date":"2020-02-27T10:33:16","date_gmt":"2020-02-27T17:33:16","guid":{"rendered":"https:\/\/developer.microsoft.com\/en-us\/office\/blogs\/?p=4135"},"modified":"2020-02-27T10:33:16","modified_gmt":"2020-02-27T17:33:16","slug":"changes-coming-to-microsoft-teams-bot-apis-for-fetching-team-chat-members","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/changes-coming-to-microsoft-teams-bot-apis-for-fetching-team-chat-members\/","title":{"rendered":"Changes coming to Microsoft Teams Bot APIs for fetching team\/chat members"},"content":{"rendered":"<p>Currently, bot developers who want to retrieve information for one or more members of a chat or team use the Microsoft Teams bot APIs <code>TeamsInfo.GetMembersAsync<\/code>\u00a0(for C#) or <code>TeamsInfo.getMembers<\/code>\u00a0(for TypeScript\/Node.js) APIs (<a href=\"https:\/\/docs.microsoft.com\/en-us\/microsoftteams\/platform\/bots\/how-to\/get-teams-context?tabs=dotnet#fetching-the-roster-or-user-profile\">documented here<\/a>). These APIs have several shortcomings today:<\/p>\n<ul>\n<li><strong>For large teams, performance is poor and timeouts are more likely.<\/strong> The maximum team size has grown considerably since Microsoft Teams was released in early 2017. Since <code>GetMembersAsync\/getMembers<\/code> returns the entire member list, it takes a long time for the API call to return for large teams, and it&#8217;s not uncommon for the call to time out and you have to try again.<\/li>\n<li><strong>Getting profile details for a single user is cumbersome.<\/strong> To get the profile information for a single user, you have to retrieve the entire member list and then search for the one you want. True, there&#8217;s a helper function in the Bot Framework SDK to make it simpler, but under the covers it&#8217;s not efficient.<\/li>\n<\/ul>\n<p>Separately, with the introduction of <a href=\"https:\/\/docs.microsoft.com\/en-us\/microsoftteams\/create-an-org-wide-team\">org-wide teams<\/a>, we realized it was time to better align these APIs with Office 365 privacy controls: bots used in large teams are able to retrieve basic profile information, which is similar to the <code>User.ReadBasic.All<\/code> <a href=\"https:\/\/docs.microsoft.com\/en-us\/graph\/permissions-reference#user-permissions\">Microsoft Graph permission<\/a>. Tenant administrators have a great deal of control over which apps and bots can be used in their tenant, but these settings are different than the ones governing Microsoft Graph.<\/p>\n<p>Here&#8217;s a sample JSON representation of what&#8217;s returned by these APIs today. I&#8217;ll refer to some of the fields below.<\/p>\n<pre class=\"font-size-enable:true font-size:9 lang:null decode:true lang: \" title=\"JSON Representation of the getMembers\/getMembersAsync APIs\">[{\n    \"id\": \"29:1GcS4EyB_oSI8A88XmWBN7NJFyMqe3QGnJdgLfFGkJnVelzRGos0bPbpsfJjcbAD22bmKc4GMbrY2g4JDrrA8vM06X1-cHHle4zOE6U4ttcc\",\n    \"objectId\": \"9d3e08f9-a7ae-43aa-a4d3-de3f319a8a9c\",\n    \"givenName\": \"Larry\",\n    \"surname\": \"Brown\",\n    \"email\": \"Larry.Brown@fabrikam.com\",\n    \"userPrincipalName\": \"labrown@fabrikam.com\"\n}, {\n    \"id\": \"29:1bSnHZ7Js2STWrgk6ScEErLk1Lp2zQuD5H2qQ960rtvstKp8tKLl-3r8b6DoW0QxZimuTxk_kupZ1DBMpvIQQUAZL-PNj0EORDvRZXy8kvWk\",\n    \"objectId\": \"76b0b09f-d410-48fd-993e-84da521a597b\",\n    \"givenName\": \"John\",\n    \"surname\": \"Patterson\",\n    \"email\": \"johnp@fabrikam.com\",\n    \"userPrincipalName\": \"johnp@fabrikam.com\"\n}, {\n    \"id\": \"29:1URzNQM1x1PNMr1D7L5_lFe6qF6gEfAbkdG8_BUxOW2mTKryQqEZtBTqDt10-MghkzjYDuUj4KG6nvg5lFAyjOLiGJ4jzhb99WrnI7XKriCs\",\n    \"objectId\": \"6b7b3b2a-2c4b-4175-8582-41c9e685c1b5\",\n    \"givenName\": \"Rick\",\n    \"surname\": \"Stevens\",\n    \"email\": \"Rick.Stevens@fabrikam.com\",\n    \"userPrincipalName\": \"rstevens@fabrikam.com\"\n}]<\/pre>\n<h3>API changes<\/h3>\n<p>We are announcing the following changes:<\/p>\n<ul>\n<li><strong>We are creating a new paged API for retrieving profile information for members of a chat\/team.<\/strong> Preliminary documentation for the C# function <a href=\"https:\/\/docs.microsoft.com\/en-us\/dotnet\/api\/microsoft.bot.connector.conversationsextensions.getconversationpagedmembersasync?view=botbuilder-dotnet-stable\"><code>GetConversationPagedMembers<\/code><\/a> in the Bot Framework 4.x SDK is available <a href=\"https:\/\/docs.microsoft.com\/en-us\/dotnet\/api\/microsoft.bot.connector.conversationsextensions.getconversationpagedmembersasync?view=botbuilder-dotnet-stable\">now<\/a>; documentation for the TypeScript\/Node.js version is forthcoming. This API will also be available in Bot Framework 3.x. Note: this API is currently available, but the documentation isn&#8217;t finished, and the schema of the JSON object it returns will change slightly in the near future: we are changing <code>objectId<\/code> to <code>aadObjectId<\/code> to match what it&#8217;s called in the Activity object of a Bot Framework message.<\/li>\n<li><strong>We are creating a new API for retrieving the profile information for a single user.<\/strong> We will document this new API in March 2020, but we can provide a few details: it will take the ID of the team\/chat and a <a href=\"https:\/\/docs.microsoft.com\/en-us\/windows\/win32\/ad\/naming-properties#userprincipalname\">UPN<\/a> (<code>userPrincipalName<\/code> above), Azure Active Directory Object ID (<code>objectId<\/code> above), or the Teams user ID (<code>id<\/code> above) as parameters and return the profile information for that user.<\/li>\n<li><strong><code>TeamsInfo.GetMembersAsync<\/code> (C#) and <code>TeamsInfo.getMembers<\/code> (TypeScript\/Node.js) is formally deprecated and will stop working in late 2021.<\/strong> We will announce a specific timetable in May based on feedback from developers, but once the new paged API is available, developers should update their bots to use it. (This also applies to the <a href=\"https:\/\/docs.microsoft.com\/en-us\/microsoftteams\/platform\/bots\/how-to\/get-teams-context?tabs=json#tabpanel_CeZOj-G++Q_json\">underlying REST API these APIs use<\/a>.)<\/li>\n<li><strong>By late 2021, bots will not be able to proactively retrieve the <code>userPrincipalName<\/code> or <code>email<\/code> properties for members of a chat\/team and will need to use Microsoft Graph to retrieve them.<\/strong> Specifically, <code>userPrincipalName<\/code> and <code>email<\/code> properties will not be returned from the new <code>GetConversationPagedMembers<\/code> API starting in late 2021. Bots will have to use Microsoft Graph with an access token to retrieve this information. This is obviously a major change: we must make it easier for bots to get an access token, and we must streamline and simplify the end-user consent process.<\/li>\n<\/ul>\n<p>More information on all of this is forthcoming, including more specific timeframes; for now, we wanted to give everyone a heads up on what was coming.<\/p>\n<h3>Feedback and more information<\/h3>\n<p>We have created a <a href=\"https:\/\/docs.microsoft.com\/en-us\/microsoftteams\/platform\/resources\/team-chat-member-api-changes\">new page in the Teams platform documentation<\/a> to provide up-to-date information on these changes. If you have questions, please post an issue on <a href=\"https:\/\/docs.microsoft.com\/en-us\/microsoftteams\/platform\/resources\/team-chat-member-api-changes\">that page<\/a>:<\/p>\n<p><img decoding=\"async\" class=\"aligncenter wp-image-4150\" src=\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2020\/02\/github-feedback.png\" alt=\"Leaving documentation feedback\" width=\"700\" height=\"126\" srcset=\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2020\/02\/github-feedback.png 959w, https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2020\/02\/github-feedback-300x54.png 300w, https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2020\/02\/github-feedback-768x138.png 768w\" sizes=\"(max-width: 700px) 100vw, 700px\" \/><\/p>\n<p>We&#8217;ll do our best to answer your questions quickly.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Currently, bot developers who want to retrieve information for one or more members of a chat or team use the Microsoft Teams bot APIs TeamsInfo.GetMembersAsync\u00a0(for C#) or TeamsInfo.getMembers\u00a0(for TypeScript\/Node.js) APIs (documented here). These APIs have several shortcomings today: For large teams, performance is poor and timeouts are more likely. The maximum team size has grown [&hellip;]<\/p>\n","protected":false},"author":69074,"featured_media":25159,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[128],"tags":[37],"class_list":["post-4135","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-microsoft-teams","tag-bot-framework"],"acf":[],"blog_post_summary":"<p>Currently, bot developers who want to retrieve information for one or more members of a chat or team use the Microsoft Teams bot APIs TeamsInfo.GetMembersAsync\u00a0(for C#) or TeamsInfo.getMembers\u00a0(for TypeScript\/Node.js) APIs (documented here). These APIs have several shortcomings today: For large teams, performance is poor and timeouts are more likely. The maximum team size has grown [&hellip;]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/4135","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/users\/69074"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/comments?post=4135"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/4135\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media\/25159"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media?parent=4135"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/categories?post=4135"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/tags?post=4135"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}