Updates from: 06/25/2021 03:18:01
Service Microsoft Docs article Related commit history on GitHub Change details
platform Designing Apps In Meetings https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/apps-in-teams-meetings/design/designing-apps-in-meetings.md
Optimize your in-meeting tab to fit edge-to-edge within the 280 pixel-wide ifram
### Scrolling
-Iframe contents should scroll vertically. You can only see the content you've scrolled to (nothing above or below). The scrollbar is part of the iframe content.
+Remember the following if you allow scrolling:
+
+* Content in the iframe contents should only scroll vertically.
+* Users should only see the content they've scrolled to (nothing above or below).
+* The scrollbar is part of the iframe content.
:::image type="content" source="../../assets/images/apps-in-meetings/in-meeting-tab-scrolling.png" alt-text="Example shows how the in-meeting tab scrolls." border="false":::
There are two header variants. When possible, use the variant with the avatar to
|4|**Close button**: Dismisses the dialog.| |5|**Action string**: Typically describes who initiated the dialog.|
-### Responsive behavior
+### Responsive behavior: In-meeting dialogs
In-meeting dialogs can vary in size to account for different scenarios. Make sure to maintain padding and component sizes.
To implement, specify the width and height using the [`externalResourceUrl`](~/a
:::image type="content" source="../../assets/images/apps-in-meetings/in-meeting-dialog-responsive.png" alt-text="Example shows the in-meeting dialog. Width: Min--280 pixels (248 pixels iframe). Max--460 pixels (428 pixels iframe). Height: 300 pixels (iframe)." border="false":::
+## Use the shared meeting stage
+
+Shared meeting stage helps meeting participants interact with and collaborate on app content in real-time. For example, users can focus their call on editing a document, brainstorming with a whiteboard, or reviewing a dashboard.
+
+Apps shared to the meeting stage occupy the same space as a shared screen. The stage reorients for all meeting participants.
+
+### Use cases
+
+The shared meeting stage is all about collaboration and participation. Here are some example scenarios to help you get started.
+
+ :::column span="1":::
+
+**Edit and review**: Dive into dashboards and planning with everyone on the call.
+
+ :::column-end:::
+ :::column span="3":::
++
+ :::column-end:::
+
+ :::column span="1":::
+
+**Whiteboard**: Draw and ideate together on a shared canvas.
+
+ :::column-end:::
+ :::column span="3":::
++
+ :::column-end:::
+
+ :::column span="1":::
+
+**Quiz**: Test knowledge and gain insights with interactive materials.
+
+ :::column-end:::
+ :::column span="3":::
++
+ :::column-end:::
+
+### Anatomy: Shared meeting stage
++
+|Counter|Description|
+|-|--|
+|1|**App icon**: The highlighted icon indicates the app's in-meeting tab is open.|
+|2|**Share to meeting stage button**: The entry point to share the app to the meeting stage. Displays if you configure your app to use the shared meeting stage.|
+|3|**iframe**: Displays your app content.|
+|4|**Stop sharing button**: Stops sharing the app to the meeting stage. Displays only for the participant who started the share.|
+|5|**Presenter attribution**: Displays the name of the participant who shared the app.|
+
+### Responsive behavior: Shared meeting stage
+
+Apps shared to the meeting stage vary in size based on the state of the meeting and how the user resizes the window. Maintain padding and the responsive layout of navigation and controls just as you would in a browser.
+
+* **Side panel**: A user can have the side panel open at any time during a meeting to chat, view the roster, or use an app (i.e., in-meeting tab). The stage dynamically rearranges when the panel is open.
+* **Video and audio grid**: The video and audio grid is always visible to show meeting participants. When a user spotlights or pins someone in the meeting, this increases the height or width of the participant grid depending on the orientation.
+
+#### Meeting stage (without side panel)
+
+When the side panel isn't open, the meeting stage is 994x678 pixels by default and can be a minimum 792x382 pixels.
++
+#### Meeting stage (with side panel)
+
+When the side panel is open, the meeting stage is 918x540 pixels by default and can be a minimum 472x382 pixels.
++ ## After a meeting You can go back to a meeting after it ends and view app content. In this example, the meeting organizer can look at poll results in the **Contoso** tab. (Note: From a design standpoint, there's no difference between a the pre- and post-meeting tab experience.)
A single in-meeting dialog with multiple interactions can distract from the call
:::column-end::: :::row-end:::
+ :::column span="":::
+
+#### Do: Create a focused environment
+
+We recommend keeping your appΓÇÖs experience scoped to just the meeting stage. You can use an in-meeting tab in the side panel as a secondary, private view for certain scenarios.
+
+ :::column-end:::
+ :::column span="":::
+
+#### Don't: Include competing surfaces
+
+Your app should only ask users to focus on a single surface a time, whether it's collaborating on the stage or responding to an in-meeting dialog. (Note: You canΓÇÖt keep dialogs being triggered by other apps while your app is on the stage.)
+
+ :::column-end:::
+ ### Layout :::row::: :::column span=""::: :::image type="content" source="../../assets/images/apps-in-meetings/in-meeting-dialog-layout-do.png" alt-text="Example showing how you should use a single-column dialog layout." border="false":::
-#### Do: Use a single-column dialog layout
+#### Do: Use a one-column dialog
Since the dialogs are at the center of the meeting stage, task completion should be fast and simple to avoid user frustration.
Dense or overly structured content can be distracting and overwhelming, especial
:::column span=""::: :::image type="content" source="../../assets/images/apps-in-meetings/in-meeting-tab-layout-do.png" alt-text="Example showing a single-column tab layout." border="false":::
-#### Do: Use a single-column tab layout
+#### Do: Use a one-column tab
Given the in-meeting tab's narrow nature, we strongly recommend displaying the contents in a single column.
This deviates from the standard Teams pattern for control placement in a dialog
:::column-end::: :::row-end:::
-### Scroll
+### Scrolling
:::row::: :::column span="":::+ :::image type="content" source="../../assets/images/apps-in-meetings/in-meeting-dialog-scroll-do.png" alt-text="Example showing vertical scrolling in an in-meeting tab." border="false"::: + #### Do: Scroll vertically
-Users expect vertical scrolling in Teams (and elsewhere).
+Users expect vertical scrolling in Teams (and elsewhere). This may not apply if you have a creative canvas, such as a whiteboard, which users can pan across the x and y axis.
:::column-end::: :::column span="":::+ :::image type="content" source="../../assets/images/apps-in-meetings/in-meeting-dialog-scroll-dont.png" alt-text="Example showing horizontal scrolling in an in-meeting tab." border="false"::: + #### Don't: Scroll horizontally
-Horizontal scrolling isnΓÇÖt an expected behavior in Teams. Other canvases in the meeting environment scroll vertically.
+Horizontal scrolling isnΓÇÖt an expected behavior in Teams (including the meeting environment).
:::column-end::: :::row-end:::
In-meeting dialogs are intended for brief interactions.
:::row::: :::column span="":::+ :::image type="content" source="../../assets/images/apps-in-meetings/in-meeting-tab-theming-do.png" alt-text="Example showing a meeting extension with the dark theme." border="false":::
-#### Do: Use Teams color tokens
+
+#### Do: Focus on dark theme
-Teams meetings are optimized for dark mode to help reduce visual and cognitive noise so users can focus on the discussion and shared content. Learn about using <a href="https://fluentsite.z22.web.core.windows.net/0.51.3/colors#color-scheme" target="_blank">color tokens (Fluent UI)</a>.
+Teams meetings are optimized for dark theme to help reduce visual and cognitive noise so users can focus on the discussion and shared content. Keep in mind certain types of apps (such as whiteboarding and document editing) don't need a dark canvas.
:::column-end::: :::column span="":::
-#### Don't: Hard code hex values
+
-If you donΓÇÖt use Teams color tokens, your designs will be less scalable and take more time to manage.
+#### Don't: Use unfamiliar colors
+
+Colors that clash with the meeting environment may be distracting and appear less native to Teams. Learn about the Teams [color ramp](https://developer.microsoft.com/fluentui#/styles/web/colors/products), including call theme neutrals.
:::column-end::: :::row-end:::
Modals (also known as task modules) in the already narrow in-meeting tab might w
:::column-end::: :::row-end:::+
+### Responsive behavior
+
+ :::column span="":::
+
+#### Do: Resize and scale your app responsively
+
+App content should dynamically resize and condense in smaller windows. Keep your appΓÇÖs main navigation and any floating controls visible.
+
+ :::column-end:::
+ :::column span="":::
+
+#### Don't: Crop or clip primary UI components
+
+Floating navigation and controls off screen and requiring a scroll to find can be confusing for users. Your app content shouldnΓÇÖt scroll horizontally when it can't fit in the iframe.
+
+ :::column-end:::
+
+## Next step
+
+> [!div class="nextstepaction"]
+> [Configure your app for meetings](~/apps-in-teams-meetings/enable-and-configure-your-app-for-teams-meetings.md)
platform Enable And Configure Your App For Teams Meetings https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/apps-in-teams-meetings/enable-and-configure-your-app-for-teams-meetings.md
After you enable your app for Teams meetings, you must configure your app before
> * The in-meeting experiences that is in-meeting dialog box and tab is currently not supported on mobile clients. For more information, see [guidance for tabs on mobile](../tabs/design/tabs-mobile.md) while creating your tabs for mobile. Teams meetings provides a unique collaborative experience for your organization. It provides the opportunity to configure your app for different meeting scenarios. You can configure your apps to enhance the meeting experience based on participant role or user type. Now you can identify what actions can be taken in the following meeting scenarios:
-* [Pre-meeting](#pre-meeting)
-* [In-meeting](#in-meeting)
-* [Post-meeting](#post-meeting)
-### Pre-meeting
+* [Before a meeting](#before-a-meeting)
+* [During a meeting](#during-a-meeting)
+* [After a meeting](#after-a-meeting)
+
+### Before a meeting
Before a meeting, users can add tabs, bots, and messaging extensions. Users with organizer and presenter roles can add tabs to a meeting.
In a meeting chat, enter the **@** key and select **Get bots**.
> * Based on the user role, the app has the capability to provide role specific experiences. For example, a polling app allows only organizers and presenters to create a new poll. > * Role assignments can be changed while a meeting is in progress. For more information, see [roles in a Teams meeting](https://support.microsoft.com/office/roles-in-a-teams-meeting-c16fa7d0-1666-4dde-8686-0a0bfe16e019).
-### In-meeting
+### During a meeting
During a meeting, you can use the meetingSidePanel or the in-meeting dialog box to build unique experiences for your apps.
In-meeting dialog must not use task module. Task module is not invoked in a meet
> * You must invoke the [submitTask()](../task-modules-and-cards/task-modules/task-modules-bots.md#submitting-the-result-of-a-task-module) function to dismiss automatically after a user takes an action in the web view. This is a requirement for app submission. For more information, see [Teams SDK task module](/javascript/api/@microsoft/teams-js/microsoftteams.tasks?view=msteams-client-js-latest#submittask-stringobject--stringstring&preserve-view=true). > * If you want your app to support anonymous users, your initial invoke request payload must rely on the `from.id` request metadata in the `from` object, not the `from.aadObjectId` request metadata. `from.id` is the user ID and `from.aadObjectId` is the Azure Active Directory (AAD) ID of the user. For more information, see [using task modules in tabs](../task-modules-and-cards/task-modules/task-modules-tabs.md) and [create and send the task module](../messaging-extensions/how-to/action-commands/create-task-module.md?tabs=dotnet#the-initial-invoke-request).
-#### Share to stage
+#### Shared meeting stage
> [!NOTE] > * This capability is currently available in [developer preview](../resources/dev-preview/developer-preview-intro.md) only.
-> * To use this feature, the app must support an in-meeting meetingSidePanel.
-This capability gives developers the ability to share an app to the meeting stage. By enabling share to the meeting stage, meeting participants can collaborate in real-time.
+Shared meeting stage allows meeting participants to interact with and collaborate on app content in real-time.
The required context is `meetingStage` in the app manifest. A prerequisite for this is to have the `meetingSidePanel` context. This enables **Share** in the meetingSidePanel. ![Share to stage during meeting experience](~/assets/images/apps-in-meetings/share_to_stage_during_meeting.png)
-The manifest change that is needed to enable this capability is as follows:
+To enable shared meeting stage, configure your app manifest like this:
```json "configurableTabs": [
The manifest change that is needed to enable this capability is as follows:
] ```
-### Post-meeting
+See how to [design a shared meeting stage experience](~/apps-in-teams-meetings/design/designing-apps-in-meetings.md).
+
+### After a meeting
-The post-meeting and [pre-meeting](#pre-meeting) configurations are the same.
+The configurations after and [before meetings](#before-a-meeting) are the same.
## Code sample |Sample name | Description | Sample | |-|--|--|-|--|
-| Meeting app | Demonstrates how to use the Meeting Token Generator app to request a token, which is generated sequentially so that each participant has a fair opportunity to interact. This can be useful in situations like scrum meetings, Q&A sessions, and so on. | [View](https://github.com/OfficeDev/microsoft-teams-sample-meetings-token) |
+| Meeting app | Demonstrates how to use the Meeting Token Generator app to request a token, which is generated sequentially so that each participant has a fair opportunity to contribute in a meeting. This can be useful in situations like scrum meetings and Q&A sessions. | [View](https://github.com/OfficeDev/microsoft-teams-sample-meetings-token) |
## See also
platform Graph Proactive Bots And Messages https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/graph-api/proactive-bots-and-messages/graph-proactive-bots-and-messages.md
keywords: teams proactive messaging chat installation Graph + # Proactive installation of apps using Graph API to send messages >[!IMPORTANT]
keywords: teams proactive messaging chat installation Graph
Proactive messages are initiated by bots to start conversations with a user. They serve many purposes including sending welcome messages, conducting surveys or polls, and broadcasting organization-wide notifications. Proactive messages in Teams can be delivered as either **ad-hoc** or **dialog-based** conversations:
-|Message Type | Description |
+|Message type | Description |
|-|-- | |Ad-hoc proactive message| The bot interjects a message without interrupting the conversation flow.| |Dialog-based proactive message | The bot creates a new dialog thread, takes control of a conversation, delivers the proactive message, closes, and returns control to the previous dialog.| ## Proactive app installation in Teams
-Before your bot can proactively message a user, it must be installed either as a personal app or in a team where the user is a member. At times, you need to proactively message users that have not installed or previously interacted with your app. For example, the need to message vital information to everyone in your organization. For such scenarios, you can use the Microsoft Graph API to proactively install your bot for your users.
+Before your bot can proactively message a user, it must be installed either as a personal app or in a team where the user is a member. At times, you need to proactively message users that have not installed or previously interacted with your app. For example, the need to message important information to everyone in your organization. For such scenarios, you can use the Microsoft Graph API to proactively install your bot for your users.
## Permissions
-Microsoft Graph [teamsAppInstallation resource type](/graph/api/resources/teamsappinstallation?view=graph-rest-1.0&preserve-view=true) permissions helps you to manage your app's installation lifecycle for all user (personal) or team (channel) scopes within the Microsoft Teams platform:
+Microsoft Graph [teamsAppInstallation resource type](/graph/api/resources/teamsappinstallation?view=graph-rest-1.0&preserve-view=true) permissions help you to manage your app's installation lifecycle for all user (personal) or team (channel) scopes within the Microsoft Teams platform:
|Application permission | Description| |||
-|`TeamsAppInstallation.ReadWriteSelfForUser.All`|Allows a Teams app to read, install, upgrade, and uninstall itself for any **user**, without prior sign in or use.|
-|`TeamsAppInstallation.ReadWriteSelfForTeam.All`|Allows a Teams app to read, install, upgrade, and uninstall itself in any **team**, without prior sign in or use.|
+|`TeamsAppInstallation.ReadWriteSelfForUser.All`|Allows a Teams app to read, install, upgrade, and uninstall itself for any *user*, without prior sign in or use.|
+|`TeamsAppInstallation.ReadWriteSelfForTeam.All`|Allows a Teams app to read, install, upgrade, and uninstall itself in any *team*, without prior sign in or use.|
To use these permissions, you must add a [webApplicationInfo](../../resources/schem#webapplicationinfo) key to your app manifest with the following values:
-> [!div class="checklist"]
-> [!div class="checklist"]
->
-> * **id** ΓÇö your Azure AD app ID.
-> * **resource** ΓÇö the resource URL for the app.
->
->[!NOTE]
+
+* **id**: Your Azure Active Directory (AAD) app ID.
+* **resource**: The resource URL for the app.
+
+> [!NOTE]
> > * Your bot requires application and not user delegated permissions because the installation is for others. >
-> * An Azure AD tenant administrator must [explicitly grant permissions to an application](/graph/security-authorization#grant-permissions-to-an-application). After an application is granted permissions, all members of the Azure AD tenant gain the granted permissions.
+> * An AAD tenant administrator must [explicitly grant permissions to an application](/graph/security-authorization#grant-permissions-to-an-application). After the application is granted permissions, all members of the AAD tenant get the granted permissions.
## Enable proactive app installation and messaging > [!IMPORTANT]
->Microsoft Graph can only install apps published to your organization's app store or the Teams store.
+> Microsoft Graph can only install apps published to your organization's app store or the Teams store.
-### Γ£ö Create and publish your proactive messaging bot for Teams
+### Create and publish your proactive messaging bot for Teams
-To get started, you need a [bot for Teams](../../bots/how-to/create-a-bot-for-teams.md) with [proactive messaging](../../concepts/bots/bot-conversations/bots-conv-proactive.md) capabilities that's in your [organization's app store](../../concepts/deploy-and-publish/apps-publish-overview.md#publish-your-app-to-your-org) or the [Teams store](../../concepts/deploy-and-publish/apps-publish-overview.md#publish-your-app-to-the-teams-store).
+To get started, you need a [bot for Teams](../../bots/how-to/create-a-bot-for-teams.md) with [proactive messaging](../../concepts/bots/bot-conversations/bots-conv-proactive.md) capabilities that is in your [organization's app store](../../concepts/deploy-and-publish/apps-publish-overview.md#publish-your-app-to-your-org) or the [Teams store](../../concepts/deploy-and-publish/apps-publish-overview.md#publish-your-app-to-the-teams-store).
->[!TIP]
-> The production-ready [**Company Communicator**](../..//samples/app-templates.md#company-communicator) app template permits broadcast messaging and is a good foundation for building your proactive bot application.
+> [!TIP]
+> The production-ready [*Company Communicator*](../..//samples/app-templates.md#company-communicator) app template permits broadcast messaging and is a good start to build your proactive bot application.
-### Γ£ö Get the `teamsAppId` for your app
+### Get the `teamsAppId` for your app
-**1.** You need the `teamsAppId` for the next steps.
+You can retrieve the `teamsAppId` in the following ways:
-The `teamsAppId` can be retrieved from your organization's app catalog:
+* From your organization's app catalog:
-**Microsoft Graph page reference:** [teamsApp resource type](/graph/api/resources/teamsapp?view=graph-rest-1.0&preserve-view=true)
+ **Microsoft Graph page reference:** [teamsApp resource type](/graph/api/resources/teamsapp?view=graph-rest-1.0&preserve-view=true)
-**HTTP GET** request:
+ **HTTP GET** request:
-```http
-GET https://graph.microsoft.com/v1.0/appCatalogs/teamsApps?$filter=externalId eq '{IdFromManifest}'
-```
+ ```http
+ GET https://graph.microsoft.com/v1.0/appCatalogs/teamsApps?$filter=externalId eq '{IdFromManifest}'
+ ```
-The request must return a `teamsApp` object. The returned object `id` is the app's catalog generated app ID and is different from the ID that you provided in your Teams app manifest:
+ The request must return a `teamsApp` object `id`, which is the app's catalog generated app ID. This is different from the ID that you provided in your Teams app manifest:
-```json
-{
- "value": [
+ ```json
{
- "id": "b1c5353a-7aca-41b3-830f-27d5218fe0e5",
- "externalId": "f31b1263-ba99-435a-a679-911d24850d7c",
- "name": "Test App",
- "version": "1.0.1",
- "distributionMethod": "Organization"
+ "value": [
+ {
+ "id": "b1c5353a-7aca-41b3-830f-27d5218fe0e5",
+ "externalId": "f31b1263-ba99-435a-a679-911d24850d7c",
+ "name": "Test App",
+ "version": "1.0.1",
+ "distributionMethod": "Organization"
+ }
+ ]
}
- ]
-}
-```
+ ```
-**2.** If your app has already been uploaded or sideloaded for a user in the personal scope, you can retrieve the `teamsAppId` as follows:
+* If your app has already been uploaded or sideloaded for a user in personal scope:
-**Microsoft Graph page reference:** [List apps installed for user](/graph/api/userteamwork-list-installedapps?view=graph-rest-v1.0&tabs=http&preserve-view=true)
+ **Microsoft Graph page reference:** [List apps installed for user](/graph/api/userteamwork-list-installedapps?view=graph-rest-v1.0&tabs=http&preserve-view=true)
-**HTTP GET** request:
+ **HTTP GET** request:
-```http
-GET https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps?$expand=teamsApp&$filter=teamsApp/externalId eq '{IdFromManifest}'
-```
+ ```http
+ GET https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps?$expand=teamsApp&$filter=teamsApp/externalId eq '{IdFromManifest}'
+ ```
-**3.** If your app has been uploaded or sideloaded for a channel in the team scope, you can retrieve the `teamsAppId` as follows:
+* If your app has already been uploaded or sideloaded for a channel in team scope:
-**Microsoft Graph page reference:** [List apps in team](/graph/api/team-list-installedapps?view=graph-rest-v1.0&tabs=http&preserve-view=true)
+ **Microsoft Graph page reference:** [List apps in team](/graph/api/team-list-installedapps?view=graph-rest-v1.0&tabs=http&preserve-view=true)
-**HTTP GET** request:
+ **HTTP GET** request:
-```http
-GET https://graph.microsoft.com/v1.0/teams/{team-id}/installedApps?$expand=teamsApp&$filter=teamsApp/externalId eq '{IdFromManifest}'
-```
+ ```http
+ GET https://graph.microsoft.com/v1.0/teams/{team-id}/installedApps?$expand=teamsApp&$filter=teamsApp/externalId eq '{IdFromManifest}'
+ ```
+
+ > [!TIP]
+ > To narrow the list of results, you can filter any of the fields of the [**teamsApp**](/graph/api/resources/teamsapp?view=graph-rest-1.0&preserve-view=true) object.
->[!TIP]
-> To narrow the list of results, you can filter on any of the fields of [**teamsApp**](/graph/api/resources/teamsapp?view=graph-rest-1.0&preserve-view=true) object.
+### Determine whether your bot is currently installed for a message recipient
-### Γ£ö Determine whether your bot is currently installed for a message recipient
+You can determine whether your bot is currently installed for a message recipient as follows:
**Microsoft Graph page reference:** [List apps installed for user](/graph/api/userteamwork-list-installedapps?view=graph-rest-v1.0&tabs=http&preserve-view=true)
GET https://graph.microsoft.com/v1.0/teams/{team-id}/installedApps?$expand=teams
GET https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps?$expand=teamsApp&$filter=teamsApp/id eq '{teamsAppId}' ```
-This request returns an empty array if the app is not installed and an array with a single [teamsAppInstallation](/graph/api/resources/teamsappinstallation?view=graph-rest-v1.0&preserve-view=true) object if the app is installed.
+The request returns:
-### Γ£ö Install your app
+* An empty array if the app is not installed.
+* An array with a single [teamsAppInstallation](/graph/api/resources/teamsappinstallation?view=graph-rest-v1.0&preserve-view=true) object if the app is installed.
+
+### Install your app
+
+You can install your app as follows:
**Microsoft Graph page reference:** [Install app for user](/graph/api/userteamwork-post-installedapps?view=graph-rest-v1.0&tabs=http&preserve-view=true)
Content-Type: application/json
} ```
-If the user has Microsoft Teams running, app installation is seen immediately. A restart may be required to view the installed app.
+If the user has Microsoft Teams running, app installation occurs immediately. A restart may be required to view the installed app.
-### Γ£ö Retrieve the conversation **chatId**
+### Retrieve the conversation `chatId`
When your app is installed for the user, the bot receives a `conversationUpdate` [event notification](../../resources/bot-v3/bots-notifications.md#team-member-or-bot-addition) that contains the necessary information to send the proactive message.
-The `chatId` can also be retrieved as follows:
- **Microsoft Graph page reference:** [Get chat](/graph/api/chat-get?view=graph-rest-beta&tabs=http&preserve-view=true)
-**1.** You must need your app's `{teamsAppInstallationId}`. If you don't have it, use the following:
+1. You must have your app's `{teamsAppInstallationId}`. If you do not have it, use the following:
-**HTTP GET** request:
+ **HTTP GET** request:
-```http
-GET https://graph.microsoft.com/beta/users/{user-id}/teamwork/installedApps?$expand=teamsApp&$filter=teamsApp/id eq '{teamsAppId}'
-```
+ ```http
+ GET https://graph.microsoft.com/beta/users/{user-id}/teamwork/installedApps?$expand=teamsApp&$filter=teamsApp/id eq '{teamsAppId}'
+ ```
-The **id** property of the response is the `teamsAppInstallationId`.
+ The **id** property of the response is the `teamsAppInstallationId`.
-**2.** Make the following request to fetch the `chatId`:
+1. Make the following request to fetch the `chatId`:
-**HTTP GET** request (permission ΓÇö `TeamsAppInstallation.ReadWriteSelfForUser.All`):
+ **HTTP GET** request (permission ΓÇö `TeamsAppInstallation.ReadWriteSelfForUser.All`):
-```http
-GET https://graph.microsoft.com/beta/users/{user-id}/teamwork/installedApps/{teamsAppInstallationId}/chat
-```
+ ```http
+ GET https://graph.microsoft.com/beta/users/{user-id}/teamwork/installedApps/{teamsAppInstallationId}/chat
+ ```
-The **id** property of the response is the `chatId`.
+ The **id** property of the response is the `chatId`.
-You can also retrieve the `chatId` with the following request but it requires the broader `Chat.Read.All` permission:
+ You can also retrieve the `chatId` with the following request but it requires the broader `Chat.Read.All` permission:
-**HTTP GET** request (permission ΓÇö `Chat.Read.All`):
+ **HTTP GET** request (permission ΓÇö `Chat.Read.All`):
-```http
-GET https://graph.microsoft.com/beta/users/{user-id}/chats?$filter=installedApps/any(a:a/teamsApp/id eq '{teamsAppId}')
-```
+ ```http
+ GET https://graph.microsoft.com/beta/users/{user-id}/chats?$filter=installedApps/any(a:a/teamsApp/id eq '{teamsAppId}')
+ ```
-### Γ£ö Send proactive messages
+### Send proactive messages
-Your bot can [send proactive messages](/azure/bot-service/bot-builder-howto-proactive-message?view=azure-bot-service-4.0&tabs=csharp&preserve-view=true) after the bot has been added for a user or a team and has received all the user information.
+Your bot can [send proactive messages](/azure/bot-service/bot-builder-howto-proactive-message?view=azure-bot-service-4.0&tabs=csharp&preserve-view=true) after the bot has been added for a user or a team, and has received all the user information.
## See also * [**Manage app setup policies in Microsoft Teams**](/MicrosoftTeams/teams-app-setup-policies#create-a-custom-app-setup-policy) * [Send proactive notifications to users SDK v4](/azure/bot-service/bot-builder-howto-proactive-message?view=azure-bot-service-4.0&tabs=csharp&preserve-view=true)
-## View additional code samples
+## Additional code samples
> > [!div class="nextstepaction"] > [**Teams proactive messaging code samples**](/samples/officedev/msteams-samples-proactive-messaging/msteams-samples-proactive-messaging/)
platform Resource Specific Consent https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/graph-api/rsc/resource-specific-consent.md
Title: Resource-specific consent in Teams
+ Title: Enable resource-specific consent in Teams
description: Describes resource-specific consent in Teams and how to make advantage of it. localization_priority: Normal
keywords: teams authorization OAuth SSO AAD rsc Graph
-# Resource-specific consent (RSC)
+
+# Resource-specific consent
> [!NOTE] > Resource-specific consent for chat scope is available in [public developer preview](../../resources/dev-preview/developer-preview-intro.md) only.
-Resource-specific consent (RSC) is a Microsoft Teams and Microsoft Graph API integration that enables your app to use API endpoints to manage specific resourcesΓÇöeither teams or chatsΓÇöwithin an organization. The resource-specific consent (RSC) permissions model enables *team owners* and *chat owners* to grant consent for an application to access and/or modify a team's data and a chat's data, respectively. The granular RSC permissions define what an application can do within a specific resource:
+Resource-specific consent (RSC) is a Microsoft Teams and Microsoft Graph API integration that enables your app to use API endpoints to manage specific resources, either teams or chats, within an organization. The RSC permissions model enables *team owners* and *chat owners* to grant consent for an application to access and modify a team's data and a chat's data, respectively.
## Resource-specific permissions
+The granular, Teams-specific, RSC permissions define what an application can do within a specific resource.
+ ### Resource-specific permissions for a team+ |Application permission| Action | | -- | -- | |TeamSettings.Read.Group | Get this team's settings.|
Resource-specific consent (RSC) is a Microsoft Teams and Microsoft Graph API int
|TeamsTab.Delete.Group|Delete this team's tabs. | |TeamMember.Read.Group|Get this team's members. |
-For more details, see [Team resource-specific consent permissions](/graph/permissions-reference#team-resource-specific-consent-permissions).
+For more details, see [team resource-specific consent permissions](/graph/permissions-reference#teams-resource-specific-consent-permissions).
### Resource-specific permissions for a chat+
+The following table provides resource-specific permissions for a chat:
+ |Application permission| Action | | -- | -- | | ChatSettings.Read.Chat | Get this chat's settings. |
For more details, see [Team resource-specific consent permissions](/graph/permis
| TeamsTab.Delete.Chat | Delete this chat's tabs. | | TeamsTab.ReadWrite.Chat | Manage this chat's tabs. | | TeamsAppInstallation.Read.Chat | Get which apps are installed in this chat. |
-| OnlineMeeting.ReadBasic.Chat | Get basic propertiesΓÇösuch as name, schedule, organizer, and join linkΓÇöof a meeting associated with this chat. |
-
-For more details, see [Chat resource-specific consent permissions](/graph/permissions-reference#chat-resource-specific-consent-permissions).
+| OnlineMeeting.ReadBasic.Chat | Get basic properties, such as name, schedule, organizer, and join link of a meeting associated with this chat. |
->[!NOTE]
->Resource-specific permissions are only available to Teams apps installed on the Teams client and are currently not part of the Azure Active Directory portal.
+For more details, see [chat resource-specific consent permissions](/graph/permissions-reference#chat-resource-specific-consent-permissions).
-## Enable resource-specific consent in your application
+> [!NOTE]
+> Resource-specific permissions are only available to Teams apps installed on the Teams client and are currently not part of the Azure Active Directory (AAD) portal.
-The steps for enabling RSC in your application are as follows:
+## Enable RSC in your application
-1. [Configure consent settings in the Azure Active Directory portal](#configure-consent-settings-in-the-azure-ad-portal).
+1. [Configure consent settings in the AAD portal](#configure-consent-settings-in-the-aad-portal).
1. [Configure group owner consent settings for RSC in a team](#configure-group-owner-consent-settings-for-rsc-in-a-team). 1. [Configure user consent settings for RSC in a chat](#configure-user-consent-settings-for-rsc-in-a-chat).
-1. [Register your app with Microsoft identity platform via the Azure AD portal](#register-your-app-with-microsoft-identity-platform-via-the-azure-ad-portal).
-1. [Review your application permissions in the Azure AD portal](#review-your-application-permissions-in-the-azure-ad-portal).
-1. [Obtain an access token from the Microsoft Identity platform](#obtain-an-access-token-from-the-microsoft-identity-platform).
+1. [Register your app with Microsoft identity platform using the AAD portal](#register-your-app-with-microsoft-identity-platform-using-the-aad-portal).
+1. [Review your application permissions in the AAD portal](#review-your-application-permissions-in-the-aad-portal).
+1. [Obtain an access token from the identity platform](#obtain-an-access-token-from-the-microsoft-identity-platform).
1. [Update your Teams app manifest](#update-your-teams-app-manifest). 1. [Install your app directly in Teams](#sideload-your-app-in-teams). 1. [Check your app for added RSC permissions](#check-your-app-for-added-rsc-permissions). 1. [Check your app for added RSC permissions in a team](#check-your-app-for-added-rsc-permissions-in-a-team). 1. [Check your app for added RSC permissions in a chat](#check-your-app-for-added-rsc-permissions-in-a-chat).
-## Configure consent settings in the Azure AD portal
+## Configure consent settings in the AAD portal
### Configure group owner consent settings for RSC in a team You can enable or disable [group owner consent](/azure/active-directory/manage-apps/configure-user-consent-groups?tabs=azure-portal) directly within the Azure portal:
-> [!div class="checklist"]
->
->- Sign in to the [Azure portal](https://portal.azure.com) as a [Global Administrator/Company Administrator](/azure/active-directory/roles/permissions-reference#global-administrator&preserve-view=true).
- > - [Select](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ConsentPoliciesMenuBlade/UserSettings) **Azure Active Directory** => **Enterprise applications** => **Consent and permissions** => **User consent settings**.
-> - Enable, disable, or limit user consent with the control labeled **Group owner consent for apps accessing data** (The default is **Allow group owner consent for all group owners**). For a team owner to install an app using RSC, group owner consent must be enabled for that user.
+1. Sign in to the [Azure portal](https://portal.azure.com) as a [Global Administrator or Company Administrator](/azure/active-directory/roles/permissions-reference#global-administrator&preserve-view=true).
+1. Select **Azure Active Directory** > **Enterprise applications** > **Consent and permissions** > [**User consent settings**](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ConsentPoliciesMenuBlade/UserSettings).
+1. Enable, disable, or limit user consent with the control labeled **Group owner consent for apps accessing data**. The default is **Allow group owner consent for all group owners**. For a team owner to install an app using RSC, group owner consent must be enabled for that user.
-![azure rsc team configuration](../../assets/images/azure-rsc-team-configuration.png)
+ ![Azure RSC team configuration](../../assets/images/azure-rsc-team-configuration.png)
-To enable or disable group owner consent using PowerShell, follow the steps outlined in [Configure group owner consent using PowerShell](/azure/active-directory/manage-apps/configure-user-consent-groups?tabs=azure-powershell).
+In addition, you can enable or disable group owner consent using PowerShell, follow the steps outlined in [configure group owner consent using PowerShell](/azure/active-directory/manage-apps/configure-user-consent-groups?tabs=azure-powershell).
### Configure user consent settings for RSC in a chat You can enable or disable [user consent](/azure/active-directory/manage-apps/configure-user-consent?tabs=azure-portal) directly within the Azure portal:
-> [!div class="checklist"]
->
->- Sign in to the [Azure portal](https://portal.azure.com) as a [Global Administrator/Company Administrator](/azure/active-directory/roles/permissions-reference#global-administrator&preserve-view=true).
- > - [Select](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ConsentPoliciesMenuBlade/UserSettings) **Azure Active Directory** => **Enterprise applications** => **Consent and permissions** => **User consent settings**.
-> - Enable, disable, or limit user consent with the control labeled **User consent for applications** (The default is **Allow user consent for apps**). For a chat member to install an app using RSC, user consent must be enabled for that user.
-
-![azure rsc chat configuration](../../assets/images/azure-rsc-chat-configuration.png)
+1. Sign in to the [Azure portal](https://portal.azure.com) as a [Global Administrator or Company Administrator](/azure/active-directory/roles/permissions-reference#global-administrator&preserve-view=true).
+1. Select **Azure Active Directory** > **Enterprise applications** > **Consent and permissions** > [**User consent settings**](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ConsentPoliciesMenuBlade/UserSettings).
+1. Enable, disable, or limit user consent with the control labeled **User consent for applications**. The default is **Allow user consent for apps**. For a chat member to install an app using RSC, user consent must be enabled for that user.
-To enable or disable user consent using PowerShell, follow the steps outlined in [Configure user consent using PowerShell](/azure/active-directory/manage-apps/configure-user-consent?tabs=azure-powershell).
+ ![Azure RSC chat configuration](../../assets/images/azure-rsc-chat-configuration.png)
+In addition, you can enable or disable user consent using PowerShell, follow the steps outlined in [configure user consent using PowerShell](/azure/active-directory/manage-apps/configure-user-consent?tabs=azure-powershell).
-## Register your app with Microsoft identity platform via the Azure AD portal
+## Register your app with Microsoft identity platform using the AAD portal
-The Azure Active Directory portal provides a central platform for you to register and configure your apps. Your app must be registered in the Azure AD portal to integrate with the Microsoft identity platform and call Microsoft Graph APIs. For more information, see [Register an application with the Microsoft identity platform](/graph/auth-register-app-v2).
+The AAD portal provides a central platform for you to register and configure your apps. Your app must be registered in the AAD portal to integrate with the identity platform and call Microsoft Graph APIs. For more information, see [register an application with the identity platform](/graph/auth-register-app-v2).
->[!WARNING]
->An Azure AD app ID should not be shared across multiple Teams apps. There should be a 1:1 mapping between a Teams App and an Azure AD app. Attempts to install multiple Teams apps which are associated with the same Azure AD app ID will cause installation/runtime failures.
+> [!WARNING]
+> An AAD app ID must not be shared across multiple Teams apps. There must be a 1:1 mapping between a Teams app and an AAD app. Attempts to install multiple Teams apps which are associated with the same AAD app ID will cause installation or runtime failures.
-## Review your application permissions in the Azure AD portal
+## Review your application permissions in the AAD portal
-Navigate to the **Home** => **App registrations** page and select your RSC app. Choose **API permissions** from the left nav bar and examine the list of configured permissions for your app. If your app will only make RSC Graph API calls, delete all the permission on that page. If your app will also make non-RSC calls, keep those permissions as needed.
+1. Go to the **Home** > **App registrations** page and select your RSC app.
+1. Choose **API permissions** from the left pane and go through the list of **Configured permissions** for your app. If your app only makes RSC Graph API calls, delete all the permissions on that page. If your app also makes non-RSC calls, keep those permissions as required.
->[!IMPORTANT]
->The Azure AD portal cannot be used to request RSC permissions. RSC permissions are currently exclusive to Teams applications installed in the Teams client and are declared in the Teams app manifest (JSON) file.
+> [!IMPORTANT]
+> The AAD portal cannot be used to request RSC permissions. RSC permissions are currently exclusive to Teams applications installed in the Teams client and are declared in the Teams app manifest (JSON) file.
## Obtain an access token from the Microsoft identity platform
-To make Graph API calls, you must obtain an access token for your app from the identity platform. Before your app can get a token from the Microsoft identity platform, it must be registered in the Azure AD portal. The access token contains information about your app and the permissions it has for the resources and APIs available through Microsoft Graph.
+To make Graph API calls, you must obtain an access token for your app from the identity platform. Before your app can get a token from the identity platform, it must be registered in the AAD portal. The access token contains information about your app and the permissions it has for the resources and APIs available through Microsoft Graph.
-You'll need to have the following values from the Azure AD registration process to retrieve an access token from the identity platform:
+You must have the following values from the AAD registration process to retrieve an access token from the identity platform:
-- The **Application ID** assigned by the app registration portal. If your app supports single sign-on (SSO) you should use the same Application ID for your app and SSO.-- The **Client secret/password** or a public/private key pair (**Certificate**). This is not required for native apps.-- A **Redirect URI** (or reply URL) for your app to receive responses from Azure AD.
+- The **Application ID** assigned by the app registration portal. If your app supports single sign-on (SSO) you must use the same Application ID for your app and SSO.
+- The **Client secret/password** or a public or private key pair that is **Certificate**. This is not required for native apps.
+- A **Redirect URI** or reply URL for your app to receive responses from AAD.
- *See* [Get access on behalf of a user](/graph/auth-v2-user?view=graph-rest-1.0#3-get-a-token&preserve-view=true) and [Get access without a user](/graph/auth-v2-service)
+For more information, see [get access on behalf of a user](/graph/auth-v2-user?view=graph-rest-1.0#3-get-a-token&preserve-view=true) and [get access without a user](/graph/auth-v2-service).
## Update your Teams app manifest
-The RSC permissions are declared in your app manifest (JSON) file. Add a [webApplicationInfo](../../resources/schem#webapplicationinfo) key to your app manifest with the following values:
+The RSC permissions are declared in your app manifest JSON file. Add a [webApplicationInfo](../../resources/schem#webapplicationinfo) key to your app manifest with the following values:
-> [!div class="checklist"]
->
-> - **id** ΓÇö your Azure AD app ID. For more information, see [Register your app in the Azure AD portal](resource-specific-consent.md#register-your-app-with-microsoft-identity-platform-via-the-azure-ad-portal).
-> - **resource** ΓÇö any string. This field has no operation in RSC, but must be added and have a value to avoid an error response; any string will do.
-> - **application permissions** ΓÇö RSC permissions for your app. For more information, see [Resource-specific Permissions](resource-specific-consent.md#resource-specific-permissions).
+|Name| Type | Description|
+||||
+|`id` |String |Your AAD app ID. For more information, see [register your app in the AAD portal](resource-specific-consent.md#register-your-app-with-microsoft-identity-platform-using-the-aad-portal).|
+|`resource`|String| This field has no operation in RSC, but must be added and have a value to avoid an error response; any string will do.|
+|`applicationPermissions`|Array of strings|RSC permissions for your app. For more information, see [resource-specific permissions](resource-specific-consent.md#resource-specific-permissions).|
>
->[!IMPORTANT]
+> [!IMPORTANT]
> Non-RSC permissions are stored in the Azure portal. Do not add them to the app manifest. > ### Example for RSC in a team+ ```json "webApplicationInfo": { "id": "XXxxXXXXX-XxXX-xXXX-XXxx-XXXXXXXxxxXX",
The RSC permissions are declared in your app manifest (JSON) file. Add a [webAp
``` ### Example for RSC in a chat+ ```json "webApplicationInfo": { "id": "XXxxXXXXX-XxXX-xXXX-XXxx-XXXXXXXxxxXX",
The RSC permissions are declared in your app manifest (JSON) file. Add a [webAp
} ```
->[!NOTE]
->If the app is meant to support installation in both team and chat scopes, then both team and chat permissions can be specified in the same manifest under `applicationPermissions`.
+> [!NOTE]
+> If the app is meant to support installation in both team and chat scopes, then both team and chat permissions can be specified in the same manifest under `applicationPermissions`.
## Sideload your app in Teams
If your Teams admin allows custom app uploads, you can [sideload your app](~/con
## Check your app for added RSC permissions
->[!IMPORTANT]
->The RSC permissions are not attributed to a user. Calls are made with app permissions, not user delegated permissions. Thus, the app may be allowed to perform actions that the user cannot, such as deleting a tab. You should review the team owner's or chat owner's intent for your use case prior to making RSC API calls. For more information, see [Microsoft Teams API overview](/graph/teams-concept-overview).
+> [!IMPORTANT]
+> The RSC permissions are not attributed to a user. Calls are made with app permissions, not user delegated permissions. The app can be allowed to perform actions that the user cannot, such as deleting a tab. You must review the team owner's or chat owner's intent for your use before making RSC API calls. For more information, see [Microsoft Teams API overview](/graph/teams-concept-overview).
-Once the app has been installed to a resource, you can use [Graph Explorer](https://developer.microsoft.com/graph/graph-explorer) to view the permissions that have been granted to the app in the resource:
+After the app has been installed to a resource, you can use [Graph Explorer](https://developer.microsoft.com/graph/graph-explorer) to view the permissions that have been granted to the app in the resource.
### Check your app for added RSC permissions in a team
-> [!div class="checklist"]
->
->- Get the team's **groupId** from the Teams client.
-> - In the Teams client, select **Teams** from the far left nav bar.
-> - Select the team where the app is installed from the drop-down menu.
-> - Select the **More options** icon (&#8943;).
-> - Select **Get link to team**.
-> - Copy and save the **groupId** value from the string.
-> - Log into **Graph Explorer**.
-> - Make a **GET** call to the following endpoint: `https://graph.microsoft.com/beta/teams/{teamGroupId}/permissionGrants`. The `clientAppId` field in the response will map to the `webApplicationInfo.id` specified in the Teams app manifest.
- ![Graph explorer response to GET call for team RSC permissions.](../../assets/images/team-graph-permissions.png)
-
-For information about how to get details about apps installed in a specific team, see [Get the names and other details of apps installed in the specified team](/graph/api/team-list-installedapps#example-2-get-the-names-and-other-details-of-installed-apps).
+1. Get the team's **groupId** from Teams.
+1. In Teams, select **Teams** from the leftmost pane.
+1. Select the team where the app is to be installed.
+1. Select the ellipses &#x25CF;&#x25CF;&#x25CF; for that team.
+1. Select **Get link to team** from the team drop-down menu.
+1. Copy and save the **groupId** value from the **Get a link to the team** pop-up dialog box.
+1. Sign in to **Graph Explorer**.
+1. Make a **GET** call to this endpoint: `https://graph.microsoft.com/beta/teams/{teamGroupId}/permissionGrants`. The `clientAppId` field in the response will map to the `webApplicationInfo.id` specified in the Teams app manifest.
+
+ ![Graph explorer response to GET call for team RSC permissions](../../assets/images/team-graph-permissions.png)
+
+For more information on how to get details of the apps installed in a specific team, see [get the names and other details of apps installed in the specified team](/graph/api/team-list-installedapps#example-2-get-the-names-and-other-details-of-installed-apps).
### Check your app for added RSC permissions in a chat
-> [!div class="checklist"]
->
->- Get the chat thread ID from the Teams *web* client.
-> - In the Teams web client, select **Chat** from the far left nav bar.
-> - Select the chat where the app is installed from the drop-down menu.
-> - Copy the web URL and save the chat thread ID from the string.
-![Chat thread id from web URL.](../../assets/images/chat-thread-id.png)
-> - Log into **Graph Explorer**.
-> - Make a **GET** call to the following endpoint: `https://graph.microsoft.com/beta/chats/{chatId}/permissionGrants`. The `clientAppId` field in the response will map to the `webApplicationInfo.id` specified in the Teams app manifest.
- ![Graph explorer response to GET call for chat RSC permissions.](../../assets/images/chat-graph-permissions.png)
+1. Get the chat thread ID from the Teams *web* client.
+1. In the Teams web client, select **Chat** from the leftmost pane.
+1. Select the chat where the app is installed from the drop-down menu.
+1. Copy the web URL and save the chat thread ID from the string.
+
+ ![Chat thread ID from web URL](../../assets/images/chat-thread-id.png)
+
+1. Sign in to **Graph Explorer**.
+1. Make a **GET** call to the following endpoint: `https://graph.microsoft.com/beta/chats/{chatId}/permissionGrants`. The `clientAppId` field in the response will map to the `webApplicationInfo.id` specified in the Teams app manifest.
-For information about how to get details about apps installed in a specific chat, see [Get the names and other details of apps installed in the specified chat](/graph/api/chat-list-installedapps#example-2-get-the-names-and-other-details-of-apps-installed-in-the-specified-chat).
+ ![Graph explorer response to GET call for chat RSC permissions](../../assets/images/chat-graph-permissions.png)
+
+For more information on how to get details of apps installed in a specific chat, see [get the names and other details of apps installed in the specified chat](/graph/api/chat-list-installedapps#example-2-get-the-names-and-other-details-of-apps-installed-in-the-specified-chat).
## Code sample+ | **Sample name** | **Description** | **.NET** |**Node.js** | |--|--|-|-|
-| Resource Specific Consent (RSC) | Use RSC to call Graph APIs. | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/graph-rsc/csharp)|[View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/graph-rsc/nodeJs)|
--
+| Resource-Specific Consent (RSC) | Use RSC to call Graph APIs. | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/graph-rsc/csharp)|[View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/graph-rsc/nodeJs)|
## See also * [Test resource-specific consent permissions in Teams](test-resource-specific-consent.md) * [Resource-specific consent in Microsoft Teams for admins](/MicrosoftTeams/resource-specific-consent)--
platform Test Resource Specific Consent https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/graph-api/rsc/test-resource-specific-consent.md
Resource-specific consent (RSC) is a Microsoft Teams and Graph API integration t
> [!NOTE] > To test the RSC permissions, your Teams app manifest file must include a **webApplicationInfo** key populated with the following fields: >
-> - **id**: Your Azure AD app ID, see [Register your app in the Azure AD portal](resource-specific-consent.md#register-your-app-with-microsoft-identity-platform-via-the-azure-ad-portal).
+> - **id**: Your Azure AD app ID, see [Register your app in the Azure AD portal](resource-specific-consent.md#register-your-app-with-microsoft-identity-platform-using-the-aad-portal).
> - **resource**: Any string, see the note in [Update your Teams app manifest](resource-specific-consent.md#update-your-teams-app-manifest). > - **application permissions**: RSC permissions for your app, see [Resource-specific Permissions](resource-specific-consent.md#resource-specific-permissions).
platform Get Started Use App Studio https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/includes/get-started/get-started-use-app-studio.md
### Use App Studio to update the app package
+> [!TIP]
+> **Try the Developer Portal**: App Studio will soon be depricated. Configure, distribute, and manage your Teams apps with the new [Developer Portal](https://dev.teams.microsoft.com/).
+ App Studio is a Teams app that you can install from the Teams store. It simplifies the creation and registration of an app. Complete the following steps to update the app package:
Complete the following steps to update the app package:
<img width="450px" alt="App Studio" src="~/assets/images/get-started/AppStudio.png"/>
- The sample comes with its own manifest and is designed to build an app package when the project is built. You can build the app package on .NET with Visual Studio. In Visual Studio, the manifest.json file is located in under **Manifest** in `Microsoft.Teams.Samples.HelloWorld.Web`. This step is described by the following image:
+
+ The sample comes with its own manifest and is designed to build an app package when the project is built. On .NET, the manifest.json file can be located in Visual Studio in Manifest under ```Microsoft.Teams.Samples.HelloWorld.Web```. On Node.js, this is done by typing `gulp` at the command line in the root directory of the project.
+
+ In Visual Studio, the manifest.json file is located in under **Manifest** in `Microsoft.Teams.Samples.HelloWorld.Web`. This step is described by the following image:
<img width="450px" alt="Build the app package on .NET with Visual Studio" src="~/assets/images/get-started/app-package-on-.NET-with-Visual-Studio.png"/> You can build the app package on Node.js by typing `gulp` at the command line in the root directory of the project. + ```bash $ gulp [13:39:27] Using gulpfile ~\documents\github\msteams-samples-hello-world-nodejs\gulpfile.js
Complete the following steps to update the app package:
<img width="450px" alt="Newly imported app view" src="~/assets/images/get-started/HelloWorldappdetails.png"/>
-The following image shows the imported app package in App Studio:
+ The following image shows the imported app package in App Studio:
-<img width="450px" alt="Importing the app package" src="~/assets/images/get-started/Importinganapp2.png"/>
+ <img width="450px" alt="Importing the app package" src="~/assets/images/get-started/Importinganapp2.png"/>
-On the left-hand side of the Manifest editor there is a list of steps. On the right-hand side there is a list of properties that need to be filled in for each step. As you started with a sample app, much of the information is already completed. The next steps enable you to update the properties of the Hello World app.
+ On the left-hand side of the Manifest editor there is a list of steps. On the right-hand side there is a list of properties that need to be filled in for each step. As you started with a sample app, much of the information is already completed. The next steps enable you to update the properties of the Hello World app.
#### App details
Your app can only have one Team tab:
<img width="450px" alt="Adding a Teams tab" src="~/assets/images/get-started/TeamTab.png"/>
-In this sample, the Team tab is where your configuration page is displayed. Select the **...** symbol of the **Tab configuration url** and choose **Edit** from the drop-down menu. Change the URL to `https://yourteamsapp.ngrok.io/configure` where `yourteamsapp.ngrok.io` must be replaced with the URL that you used when [hosting your app](#host-the-sample-app).
+In this sample, the Team tab is where your configuration page is displayed. Select the **...** symbol of the **Tab configuration url** and choose **Edit** from the drop-down menu. Change the URL to `https://yourteamsapp.ngrok.io/configure` where `yourteamsapp.ngrok.io` must be replaced with the URL that you used when hosting your app.
##### Personal tabs
After entering the details of your app, complete the following steps to register
1. Select the **Search** box in the **Add to a team** section and select a team to add the sample app. You can set up a special team for testing. 1. Select the **Install** button at the bottom of the dialog box.
-Your app is now available in Teams. However, the bot and the messaging extension will not work until you update the hosted applications environment with the App IDs and passwords.
+ Your app is now available in Teams. However, the bot and the messaging extension will not work until you update the hosted applications environment with the App IDs and passwords.
-<img width="450px" alt="The finished app" src="~/assets/images/get-started/Finishedhelloworld.png"/>
+ <img width="450px" alt="The finished app" src="~/assets/images/get-started/Finishedhelloworld.png"/>
platform Prepare Environment https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/includes/prepare-environment.md
## Prepare your development environment
-The first thing to do is to prepare your development environment. Custom app uploading must be enabled for the Office 365 organization where you want to build your app. If you need a dedicated development tenant, you can sign up for the [Office 365 developer program](https://developer.microsoft.com/office/dev-program). For more information, see [setup your development environment](~/concepts/build-and-test/prepare-your-o365-tenant.md).
+Before you begin, you must prepare your development environment. Custom app uploading must be enabled for the Office 365 organization where you want to build your app. If you need a dedicated development tenant, you can sign up for the [Office 365 developer program](https://developer.microsoft.com/office/dev-program). For more information, see [setup your development environment](~/concepts/build-and-test/prepare-your-o365-tenant.md).
platform Team Chat Member Api Changes https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/resources/team-chat-member-api-changes.md
Following are the upcoming API changes:
> `objectId` is changed to `aadObjectId` to match what is called in the `Activity` object of a Bot Framework message. The new API is available with version 4.8 or later of the Bot Framework SDK. It is also available in the Teams SDK extension Bot Framework 3.x. Meanwhile, you can use the [REST](/microsoftteams/platform/bots/how-to/get-teams-context?tabs=json#get-single-member-details) endpoint. * `TeamsInfo.GetMembersAsync` in C# and `TeamsInfo.getMembers` in TypeScript or Node.js is formally deprecated. Once the new API is available, you must update your bots to use it. This also applies to the [underlying REST API that these APIs use](/microsoftteams/platform/bots/how-to/get-teams-context?tabs=json#tabpanel_CeZOj-G++Q_json).
-* By late 2021, bots cannot proactively retrieve the `userPrincipalName` or `email` properties for members of a chat or team. Bots must use Graph to retrieve them. The `userPrincipalName` and `email` properties are not returned from the new `GetConversationPagedMembers` API starting in late 2021. Bots have to use Graph with an access token to retrieve information. It must be made easier for bots to get an access token and streamline and simplify the end-user consent process.
+* By late 2022, bots cannot proactively retrieve the `userPrincipalName` or `email` properties for members of a chat or team. Bots must use Graph to retrieve them. The `userPrincipalName` and `email` properties are not returned from the new `GetConversationPagedMembers` API starting in late 2022. Bots have to use Graph with an access token to retrieve information. It must be made easier for bots to get an access token and streamline and simplify the end-user consent process.
platform App Templates https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/samples/app-templates.md
The Visitor Management app enables your organization and employees to easily and
:::column-end::: :::row-end:::
+## Water Cooler &#9734;
+
+Water Cooler is a custom Teams app that enables corporate teams to create, invite, and join casual conversations among teammates, such as those that take place by the Water Cooler or break room. Use this template for multiple scenarios, such as new non project related announcements, topics of interest, current events, or conversations about hobbies.
+The app provides an easy interface for anyone to find an existing conversation or start a new one. It is a foundation for building custom targeted communication capabilities, promoting interaction amongst coworkers who may otherwise not get a chance to socialize during breaks.
+
+[Get it on GitHub](https://github.com/microsoft/csapps-msteams-watercooler)
+
+![Water Cooler appscreens](../assets/images/appScreens.gif)
+
+### Key features
+
+**Water Cooler Home Page**: You can browse existing rooms where team members are interacting in existing conversations with certain people or topics of interest. Active conversations on the **Home Page** show a room name, short description, call duration, and room image.
+
+![Water Cooler Home Page](../assets/images/home-page.png)
+
+**Join room**: Use the **Join room** feature to join an ongoing conversation immediately. Select **Join** from active conversations to join the room.
+
+![Join room](../assets/images/joinRoom.gif)
+
+**Room creation**: Use the **Room creation** feature to create a Teams call or chat for all attendees to interact. Create rooms easily by specifying the room name, short description, up to five colleagues as an initial group and selecting from the provided set of room images.
+
+![Room Creation](../assets/images/createRoom.gif)
+
+**Find room**: Use the **Find room** feature to search keyword which matches with the topic or short descriptions of ongoing conversations.
+
+![Find conversation](../assets/images/findConversation.gif)
+
+**Attendee invitation**: Use the **Attendee invitation** feature to invite additional users after room creation. This is similar to Teams call.
+
+![Attendee invitation](../assets/images/attendeeInvitation.gif)
+
+**App badge**: The **Water Cooler** icon on the left menu shows a badge with the number of active conversations visible from Teams while using any app.
+
+![App badge](../assets/images/badge.gif)
+ ## Workplace Awards Workplace Awards is a Teams app template that provides a positive framework to foster recognition and encourage the culture of employee appreciation in the modern workplace. The app enables you to setup and manage an employee rewards and recognition, called R&R program where employees can easily nominate and endorse colleagues and your R&R leader can view submitted nominations, grant awards, and announce recipients.
platform Code Samples https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/tutorials/code-samples.md
localization_priority: Normal
keywords: Microsoft Teams developer samples
-# Tutorials for the Microsoft Teams developer platform
+# Overview
-Here you will find a list of tutorials that demonstrate how you can extend the Teams developer platform capabilities by creating custom apps.
+In this tutorial, you will learn how to create an app using C# or .NET, Node.js, and Yeoman Generator. This tutorial will also give you multiple Code Samples for Tabs, Bots, Messaging Extensions, Webhooks and Connectors, and Graph APIs to customize and configure your apps. In addition, you can also refer to the Microsoft Learn sections where you can extend the Teams developer platform capabilities by creating custom apps.
## Getting started with Microsoft Learn | **Capability**| **Learn module**| |--|-|
-| Tabs ΓÇö embedded web experiences | [Create embedded web experiences with tabs for Microsoft Teams](https://docs.microsoft.com/learn/modules/embedded-web-experiences/) |
-| Webhooks and connectors | [Connect web services to Microsoft Teams with webhooks and Office 365 Connectors](https://docs.microsoft.com/learn/modules/msteams-webhooks-connectors/) |
-|Messaging extensions | [Task-oriented interactions in Microsoft Teams with messaging extensions](https://docs.microsoft.com/learn/modules/msteams-messaging-extensions/) |
-| Task modules | [Collect input in Microsoft Teams with Task Modules](https://docs.microsoft.com/learn/modules/msteams-task-modules/) |
-| Conversational bots | [Create interactive conversational bots for Microsoft Teams](https://docs.microsoft.com/learn/modules/msteams-conversation-bots/) |
+| Tabs ΓÇö embedded web experiences | [Create embedded web experiences with tabs for Microsoft Teams](/learn/modules/embedded-web-experiences/) |
+| Webhooks and connectors | [Connect web services to Microsoft Teams with webhooks and Office 365 Connectors](/learn/modules/msteams-webhooks-connectors/) |
+|Messaging extensions | [Task-oriented interactions in Microsoft Teams with messaging extensions](/learn/modules/msteams-messaging-extensions/) |
+| Task modules | [Collect input in Microsoft Teams with Task Modules](/learn/modules/msteams-task-modules/) |
+| Conversational bots | [Create interactive conversational bots for Microsoft Teams](/learn/modules/msteams-conversation-bots/) |
+## See also
+* [Create an app using C# or .NET](get-started-dotnet-app-studio.md)
+* [Create an app using Node.js](get-started-nodejs-app-studio.md)
+* [Create an app using Yeoman generator](get-started-yeoman.md)
+* [Code Samples](https://github.com/OfficeDev/Microsoft-Teams-Samples)
platform Get Started Dotnet App Studio https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/tutorials/get-started-dotnet-app-studio.md
Last updated 11/09/2018
-# Create your first Teams app using C#
+# Build your first Teams app using C#
-This tutorial helps you to create a Microsoft Teams app using C#. To do this, you must:
+In this tutorial, you will learn how to build your very first Microsoft Teams app using .NET or C#. It also walks you through the steps to:
-* Prepare your environment
-* Get prerequisites
-* Download the sample
-* Build and run the sample
-* Host the sample app
-* Update the credentials for your hosted app
-* Configure the app tab
+1. [Prepare your environment](#prepare-your-environment)
+1. [Get prerequisites](#GetPrerequisites)
+1. [Download the sample](#DownloadSample)
+1. [Build and run the sample](#BuildRun)
+1. [Host the sample app](#hostsample)
+1. [Update the credentials for your hosted app](#updatecredentials)
+1. [Configure the app tab](#configureapptab)
+<a name="prepare-your-environment"></a>
[!include [prepare your environment](~/includes/prepare-environment.md)] <a name="GetPrerequisites"></a>
git clone https://github.com/OfficeDev/Microsoft-Teams-Samples.git
## Build and run the sample
-After the repo is cloned, use Visual Studio to open the solution file **Microsoft.Teams.Samples.HelloWorld.sln** from the **Microsoft-Teams-Samples/samples/app-hello-world/csharp** directory of the sample. Then, select **Build Solution** from the **Build** menu. To run the sample, press **F5** or select **Start Debugging** from the **Debug** menu.
+You can build and run the smaple after it is cloned.
+
+**To build and run the cloned sample**
+
+1. Open the solution file **Microsoft.Teams.Samples.HelloWorld.sln** from the **Microsoft-Teams-Samples/samples/app-hello-world/csharp** directory of the sample.
+1. Select **Build Solution** from the **Build** menu.
+1. Select the **F5** key, or select **Start Debugging** from the **Debug** menu to run the sample.
When the app starts, a browser window opens with the root of the app launched. You can go to the following URLs to verify that all the app URLs are loading:
When the app starts, a browser window opens with the root of the app launched. Y
- `https://localhost:44327/first` - `https://localhost:44327/second`
-<a name="HostSample"></a>
- > [!Note] > If you receive an error `Could not find a part of the path … bin\roslyn\csc.exe`, update the package with the command `Update-Package Microsoft.CodeDom.Providers.DotNetCompilerPlatform -r`. For more information, see [this question on Stack Overflow](https://stackoverflow.com/questions/32780315).
-## Host the sample app
+<a name="hostsample"></a>
+## Deploy your sample app
-Apps in Microsoft Teams are web applications that provide one or more capabilities. For the Teams platform to load your app, your app must be available on the internet. To do this, you need to host your app. You can either host it in Microsoft Azure for free or create a tunnel to the local process on your computer using `ngrok`. After you host your app, note its root URL, such as `https://yourteamsapp.ngrok.io` or `https://yourteamsapp.azurewebsites.net`.
+Apps in Microsoft Teams are web applications that provide one or more capabilities. For the Teams platform to load your app, your app must be available on the internet. To do this, you need to host your app. You can either host it in Microsoft Azure for free or create a tunnel to the local process on your computer using `ngrok`. After you host your app, make a note of its root URL, such as `https://yourteamsapp.ngrok.io` or `https://yourteamsapp.azurewebsites.net`.
### Tunnel using ngrok
After you install `ngrok`, open a new terminal window and run the following comm
ngrok http 44327 -host-header=localhost:44327 ```
-`Ngrok` listens to requests from the internet and routes them to your app running on port 44327. To verify, open your browser and go to `https://d0ac14a5.ngrok.io/hello` to load your app's hello page. Instead of this URL, use the forwarding address displayed by `ngrok` in your console session.
+`Ngrok` responds to requests from the internet and routes them to your app running on port 44327.
-> [!NOTE]
-> If you have used a different port in the [build and run](#build-and-run-the-sample) step, ensure you use the same port number to setup the `ngrok` tunnel.
+**To verify the response**
-> [!TIP]
-> It is a good idea to run `ngrok` in a different terminal window. This is done to keep `ngrok` from running without interfering with the app. You have to stop, rebuild, and rerun the app. The `ngrok` session provides useful debugging information in this window.
+1. Open your browser and go to `https://d0ac14a5.ngrok.io/hello`. This will load your app's Hello page.
+1. Instead of the URL mentioned in Step 1, use the forwarding address displayed by `ngrok` in your console session.
+ > [!NOTE]
+ > If you have used a different port in the [build and run](#build-and-run-the-sample) step, ensure you use the same port number to setup the `ngrok` tunnel.
+ > [!TIP]
+ > It is a good idea to run `ngrok` in a different terminal window. This is done to keep `ngrok` from running without interfering with the app. You have to stop, rebuild, and rerun the app. The `ngrok` session provides useful debugging information in this window.
-The app is only available during the current session on your computer. If the machine is shut down or goes to sleep, the service is no longer available. Remember this when you share the app for testing to other users. If you have to restart the service, the app returns a new address and you must update every location that uses that address. The paid version of `ngrok` does not have this limitation.
+ The app is only available during the current session on your computer. If the machine is shut down or goes to sleep, the service is no longer available. Remember this when you share the app for testing to other users. If you have to restart the service, the app returns a new address and you must update every location that uses that address. The paid version of `ngrok` does not have this limitation.
### Host in Azure
Visual Studio has built-in support for app deployment to different providers, in
<img width="530px" alt="Visual Studio" src="~/assets/images/get-started/publishtoazure1.png"/>
+**Update the app package**
+
+# [App Studio](#tab/AS)
+ [!include [Use App Studio to configure the app package](~/includes/get-started/get-started-use-app-studio.md)]
+# [Developer Portal](#tab/DP)
+
+**To install Developer Portal (preview) in Teams**
++
+1. Select the **Apps** icon at the bottom of the left-hand bar, and search for **Developer Portal**.
+
+ <img width="430px" alt="Screenshot of TDP" src="~/assets/images/Screen1.png"/>
+
+1. Select **Developer Portal** and select **Open**.
+
+ <img width="430px" alt="Screenshot of TDP Open" src="~/assets/images/screen2.png"/>
+
+1. Select the Apps tab and select **Import an existing app**.
+
+ <img width="430px" alt="Screenshot of import app in tdp" src="~/assets/images/screen3.png"/>
+
+1. Select **Hello World** and select **Import**. The **Hello World** app is imported in Developer Portal.
+
+ You can configure your app using the Teams Developer Portal. The Manifest is found under Distribute. You can use the Manifest to configure capabilities, required resources, and other important attributes for your app. For more details on how to configure your app using Developer Portal, see [Teams Developer Portal](../concepts/build-and-test/teams-developer-portal.md).
+
+ <img width="430px" alt="Screenshot of configure tdp" src="~/assets/images/Screen4.png"/>
++
+<a name="updatecredentials"></a>
## Update the credentials for your hosted app The sample app requires the environment variables to be set to the values that you saved in the text file.
-Open the `appsettings.json` file. Update the **MicrosoftAppId** value with your bot ID that you saved in the text file. Update the **MicrosoftAppPassword** with the bot password you saved.
+**To update the credentials for your hosted app**
+
+1. Open the `appsettings.json` file.
+1. Update the **MicrosoftAppId** value with your bot ID that you saved in the text file.
+1. Update the **MicrosoftAppPassword** with the bot password that you saved.
-<img width="560px" alt="Setting the keys" src="~/assets/images/get-started/get-started-net-azure-add-keys.png"/>
+ <img width="560px" alt="Setting the keys" src="~/assets/images/get-started/get-started-net-azure-add-keys.png"/>
-After these changes are made, rebuild the app. If you are using ngrok, run the app locally, and if you are hosting in Azure, redeploy the app.
+ After these changes are made, rebuild the app. If you are using ngrok, run the app locally, and if you are hosting in Azure, redeploy the app.
+<a name="configureapptab"></a>
## Configure the app tab
-Once you install the app into a team, you must configure it to show content. Go to a channel in the team where you installed the sample app and select the **'+'** button to add a new tab. Choose **Hello World** from the **Add a tab** list. A configuration dialog box is displayed that enables you to choose the tab to display in this channel. After you select the tab and select **Save** the `Hello World` tab is loaded with the tab.
+After you have installed the app into teams, you must configure it to display the content.
-<img width="530px" alt="Screenshot of configure" src="~/assets/images/samples-hello-world-tab-configure.png" />
+**To configure the app tab**
+
+1. Go to a channel in the team where you installed the sample app and select the **'+'** button to add a new tab.
+1. Select **Hello World** from the **Add a tab** list. A configuration dialog box is displayed that enables you to select the tab to display in this channel.
+1. Select **Save**. The `Hello World` tab is loaded with the tab.
+
+ <img width="530px" alt="Screenshot of configure" src="~/assets/images/samples-hello-world-tab-configure.png" />
### Test your bot in Teams
-Now you can test the bot in Teams. Select a channel in the team where you registered your app and type `@your-bot-name`. This is called an **\@mention**. The bot replies to any message that you send.
+You can now test the bot in Teams.
+
+**To test your bot**
-<img width="450px" alt="Bot responses" src="~/assets/images/samples-hello-world-bot.png" />
+* Select a channel in the team where you registered your app and type `@your-bot-name`. This is called an **\@mention**. The bot replies to any message that you send.
+
+ <img width="450px" alt="Bot responses" src="~/assets/images/samples-hello-world-bot.png" />
### Test your messaging extension
-To test your messaging extension, you can select **...** below the input box in your conversation view. A menu with the **'Hello World'** app is displayed. When you select it, a set of random texts is displayed. You can select one of the random text and that is inserted into your conversation.
+To test your messaging extension, select **...** below the input box in your conversation view. A menu with the **'Hello World'** app is displayed. When you select it, a set of random texts is displayed. You can select one of the random text and that is inserted into your conversation.
-<img width="530px" alt="Messaging extension menu" src="~/assets/images/samples-hello-world-messaging-extensions-menu.png" />
+<img width="530px" alt="Messaging extension menu" src="~/assets/images/samples-hello-world-messaging-extensions-menu1.png" />
-<img width="530px" alt="Messaging extension result" src="~/assets/images/samples-hello-world-messaging-extensions-result.png" />
+<img width="530px" alt="Messaging extension result" src="~/assets/images/samples-hello-world-messaging-extensions-result1.png" />
Select one of the random text. A card formatted and ready to send with your own message is shown. <img width="530px" alt="Messaging extension send" src="~/assets/images/samples-hello-world-messaging-extensions-send.png" />+
+## See also
+
+* [Tutorials Overview](code-samples.md)
+* [Code Samples](https://github.com/OfficeDev/Microsoft-Teams-Samples)
platform Get Started Nodejs App Studio https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/tutorials/get-started-nodejs-app-studio.md
localization_priority: Normal
-# Create your first Microsoft Teams app using Node.js
+# Build your first Microsoft Teams app using Node.js
-This tutorial helps you get started creating a Microsoft Teams app using Node.js.
+In this tutorial, you will learn how to build your very first Microsoft Teams app using Node.js. It also walks you through the steps to:
+
+1. [Prepare your environment](#prepare-environment)
+1. [Get prerequisites](#GetPrerequisites)
+1. [Download the sample](#DownloadSample)
+1. [Build and run the sample](#BuildRun)
+1. [Host the sample app](#HostSample)
+1. [Update the credentials for your hosted app](#updatecredentials)
+1. [Configure the app tab](#ConfigureTheAppTab)
+
+<a name="prepare-environment"></a>
[!include [prepare your environment](~/includes/prepare-environment.md)]
-<a name="DownloadAndHost"></a>
+<a name="GetPrerequisites"></a>
-## Download and host your app
+### Download and host your app
Follow these steps to download and host a simple "hello world" app in Teams. <a name="GetPrerequisites"></a>
-### Get prerequisites
+## Get prerequisites
To complete this tutorial, you need the following tools. If you don't already have them you can install them from these links.
To complete this tutorial, you need the following tools. If you don't already ha
- [Node.js and NPM](https://nodejs.org/) - Get any text editor or IDE. You can install and use [Visual Studio Code](https://code.visualstudio.com/download) for free.
-If you see options to add `git`, `node`, `npm`, and `code` to the PATH during installation, choose to do so. It will be handy.
+If you see options to add `git`, `node`, `npm`, and `code` to the PATH during installation, select the options.
Verify that the tools are available by running the following in a terminal window:
You can continue to use this terminal window to run the commands that follow in
<a name="DownloadSample"></a>
-### Download the sample
+## Download the sample
We have provided a simple [Hello, World!](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/app-hello-world/nodejs) sample to get you started. In a terminal window, run the following command to clone the sample repository to your local machine:
git clone https://github.com/OfficeDev/Microsoft-Teams-Samples.git
<a name="BuildRun"></a>
-### Build and run the sample
+## Build and run the sample
-Once the repo is cloned, change to the directory that holds the sample:
+After the repository is cloned, run the change directory command in terminal to change the directory to the sample:
```bash cd Microsoft-Teams-Samples/samples/app-hello-world/nodejs/
In order to build the sample, you need to install all its dependencies. Run the
npm install ```
-You should see a bunch of dependencies getting installed. Once they are finished, you can run the app:
+You should see a bunch of dependencies getting installed. After installation you can run the app with the following command:
```bash npm start
At this point, you can open a browser window and navigate to the following URLs
<a name="HostSample"></a>
-### Host the sample app
+## Deploy your sample app
Remember that apps in Microsoft Teams are web applications exposing one or more capabilities. For the Teams platform to load your app, your app must be reachable from the internet. To make your app reachable from the internet, you need to *host* your app. For local testing you can run the app on your local machine and create a tunnel to it with a web endpoint. [ngrok](https://ngrok.com) is a free tool that lets you do just that. With *ngrok* you can get a web address such as `https://d0ac14a5.ngrok.io` (this URL is just an example). You can [download and install](https://ngrok.com/download) *ngrok* for your environment. Make sure you add it to a location in your `PATH`.
-Once you install it, you can open a new terminal window and run the following command to create a tunnel. The sample uses port 3333, so be sure to specify it here:
+After you install it, you can open a new terminal window and run the following command to create a tunnel. The sample uses port 3333, so be sure to specify it here:
```bash ngrok http 3333 -host-header=localhost:3333
ngrok http 3333 -host-header=localhost:3333
There is a paid version of *ngrok* that allows persistent names. If you use the free version your app will only be available during the current session on your development machine. If the machine is shut down or goes to sleep the service will no longer be available. Remember this when sharing the app for testing by other users. If you have to restart the service it will return a new address and you will have to update every place that uses that address.
-Remember, make a note of the URL of your app because you will need this later when you register the app with Teams using App studio. Notepad works fine for this purpose.
+Make a note of the URL of your app. You will need this later when you register the app with Teams using App studio or Developer Portal.
<a name="DeployToTeams"></a> ## Deploy your app to Microsoft Teams
-At this point you have an app hosted on the internet, but you have no way yet of telling Teams where to look for it, or even what your app is called. To do this you now have to create an app package. This is little more than a text file that contains the app manifest and some icons that the Teams client will use to properly display and brand your app. You can manually create this app package, or you can use App Studio, a tool that runs in Teams that will simplify the process of registering the app. App Studio is the recommended way of creating and updating the app package.
+At this point you have an app hosted on the internet, but you have no way yet of telling Teams where to look for it, or even what your app is called. To do this you now have to create an app package. This is little more than a text file that contains the app manifest and some icons that the Teams client will use to properly display and brand your app. You can manually create this app package, or you can use App Studio or Developer Portal, tools that run in Teams, that will simplify the process of registering the app. App Studio and Developer Portal are the recommended ways of creating and updating the app package.
For either method you will need the following: - The URL where your app can be found on the internet. - Icons that Teams will use to brand your app. The sample comes with placeholder icons located in "src\static\images. App Studio also will provide default icons if needed.
+**Update the app package**
+
+# [App Studio](#tab/AS)
++
+# [Developer Portal](#tab/DP)
+
+**To install Developer Portal (preview) in Teams**
+
+1. Select the **Apps** icon at the bottom of the left-hand bar, and search for **Developer Portal**.
+
+ <img width="430px" alt="Screenshot of TDP" src="~/assets/images/Screen1.png"/>
+
+1. Select **Developer Portal** and select **Open**.
-## Update your hosted app
+ <img width="430px" alt="Screenshot of TDP Open" src="~/assets/images/screen2.png"/>
+
+1. Select the Apps tab and select **Import an existing app**.
+
+ <img width="430px" alt="Screenshot of import app in tdp" src="~/assets/images/screen3.png"/>
+
+1. Select **Hello World** and select **Import**. The **Hello World** app is imported in Developer Portal.
+
+ You can configure your app using the Teams Developer Portal. The Manifest is found under Distribute. You can use the Manifest to configure capabilities, required resources, and other important attributes for your app. For more details on how to configure your app using Developer Portal, see [Teams Developer Portal](../concepts/build-and-test/teams-developer-portal.md).
+
+ <img width="430px" alt="Screenshot of configure tdp" src="~/assets/images/Screen4.png"/>
++
+<a name="updatecredentials"></a>
+
+## Update the credentials for your hosted app
The sample app requires the following environment variables to be set to the values you made a note of earlier:
NODE_CONFIG_DIR points to the directory at the root of the repository (by defaul
## Configure the app tab
-Once you install the app into a team, you will need to configure it to show content. Go to a channel in the team and click on the **'+'** button to add a new tab. You can then choose `Hello World` from the **Add a tab** list. You will then be presented with a configuration dialog. This dialog will let you choose which tab to display in this channel. Once you select the tab and click on `Save` you can see the `Hello World` tab loaded with the tab you chose:
+After you install the app into a team, you will need to configure it to show content. Go to a channel in the team and click on the **'+'** button to add a new tab. You can then choose `Hello World` from the **Add a tab** list. You will then be presented with a configuration dialog. This dialog will let you choose which tab to display in this channel. After you select the tab and click **Save** you can see the `Hello World` tab loaded with the tab you chose:
<img width="430px" alt="Screenshot of configure" src="~/assets/images/samples-hello-world-tab-configure.png"/>
You can now interact with the bot in Teams. Choose a channel in the team where y
To test your messaging extension, you can click on the three dots below the input box in your conversation view. A menu will pop up with the **'Hello World'** app in it. When you click it, you will see a number of random texts. You can choose any one of them and it will be inserted it into your conversation:
-<img width="430px" alt="Messaging extension menu" src="~/assets/images/samples-hello-world-messaging-extensions-menu.png" />
+<img width="430px" alt="Messaging extension menu" src="~/assets/images/samples-hello-world-messaging-extensions-menu1.png" />
-<img width="430px" alt="Messaging extension result" src="~/assets/images/samples-hello-world-messaging-extensions-result.png" />
+<img width="430px" alt="Messaging extension result" src="~/assets/images/samples-hello-world-messaging-extensions-result1.png" />
-Choose one of the random texts, and you will see a card formatted and ready to send with your own message at the bottom:
+Select one of the random texts, and you will see a card formatted and ready to send with your own message at the bottom:
<img width="430px" alt="Messaging extension send" src="~/assets/images/samples-hello-world-messaging-extensions-send.png" />+
+ ## See also
+
+* [Tutorials Overview](code-samples.md)
+* [Code Samples](https://github.com/OfficeDev/Microsoft-Teams-Samples)
platform Get Started Yeoman https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/tutorials/get-started-yeoman.md
-# Create your first Microsoft Teams app using the Yeoman generator
+# Build your first Microsoft Teams app using the Yeoman generator
> [!Note] > This tutorial comes from the [Yeoman generator for Teams wiki](https://github.com/OfficeDev/generator-teams/wiki/Build-Your-First-Microsoft-Teams-App).
-In this tutorial, we will walk through creating your very first Microsoft Teams app using the Microsoft Teams Yeoman generator. It also walks you through the process of upgrading your Teams using the Yeoman generator. The prerequisite to start with this tutorial is that you have a Teams account that allows [app sideloading](~/concepts/build-and-test/prepare-your-o365-tenant.md).
+In this tutorial, you will learn how to build your very first Microsoft Teams app using the Microsoft Teams Yeoman generator. It also walks you through the process of upgrading your Teams using the Yeoman generator. Before you begin, you must have a Teams account that allows [app sideloading](~/concepts/build-and-test/prepare-your-o365-tenant.md).
![yeoman generator git](~/assets/yeoman-demo.gif)
-## Setup and prepare your machine
-You need to install the following on your machine before starting to use the Yeoman generator.
+<a name="GetPrerequisites"></a>
-### Install Node.js
+## Get Prerequisites
-You need to have Node.js installed on your machine. You should use the latest [LTS version](https://nodejs.org).
+You need to install the following on your machine before starting to use the Yeoman generator:
-### Install a code editor
+* Node.js
-You need a code editor. Most of this documentation and images refer to using [Visual Studio Code](https://code.visualstudio.com). However, feel free to use whatever text editor you prefer.
+ You need to have Node.js installed on your machine. You should use the latest [LTS version](https://nodejs.org).
-### Install Yeoman and Gulp CLI
+* A code editor
-To scaffold projects using the generator, you must install the Yeoman tool and Gulp CLI task manager.
+ You need a code editor. Most of this documentation and images refer to using [Visual Studio Code](https://code.visualstudio.com). However, feel free to use whatever text editor you prefer.
-Open up a command prompt and type the following:
+* Yeoman and Gulp CLI
-```bash
-npm install yo gulp-cli --global
-```
+ To scaffold projects using the generator, you must install the Yeoman tool and Gulp CLI task manager.
+
+ Open up a command prompt and type the following:
+
+ ```bash
+ npm install yo gulp-cli --global
+ ```
## Install the generator Install the Teams Yeoman generator with the following command: ```bash
-npm install generator-teams --global
+npm init yo teams
``` Install the preview version of the generator with the following command: ```bash
-npm install generator-teams@preview --global
+npm init yo teams@preview
``` ## Generate your project
-This section walks you through the steps for generating your project.
+This section walks you through the steps to generate your project.
**To generate your project**
-1. Open up a command prompt and create a new directory where you want to create your project, and in that directory run the command `yo teams`. The generator starts.
+1. Open a command prompt and create a new directory where you want to create your project.
+1. Go to the directory, and run the command `yo teams`. The generator starts.
1. Respond to the set of questions prompted by the generator: ![yo teams](~/assets/yeoman-images/teams-first-app-1.png)
- 1. The first question is about your project name, you can leave it as is by pressing enter.
- 1. Next question asks you if you want to create a new directory or use the current one. As you are already in the directory you want, just press enter.
- 1. In the next question, type the title of your project. This title will be used in the manifest and description of your app.
- 1. Next, you will be asked for a company name, which also will be used in the manifest.
- 1. The fifth question asks you about what version of the manifest you want to use. For this tutorial select `v1.5`, which is the current general available schema.
- 1. Next, the generator will ask you for what items you want to add to your project. You can select a single one or any combination of items. For this tutorials, just select *a Tab*:
+ 1. Enter a name for your project. You can leave it as is by pressing Enter.
+ 1. Enter a path for the new directory if you want to create a new directory. As you are already in the directory you want, just press Enter.
+ 1. Enter the title of your project. This title will be used in the manifest and description of your app.
+ 1. Enter a company name which also will be used in the manifest.
+ 1. Enter the version of the manifest you want to use. For this tutorial select `v1.5`, which is the current general available schema.
+ 1. Select the items you want to add to your project. You can select a single one or any combination of items. For this tutorials, just select *a Tab*:
![item selection](~/assets/yeoman-images/teams-first-app-2.png)
-1. Respond to the next set of follow-up questions that appear based on the items you selected in step 2.
-1. Enter a URL of where you will host your solution.
+1. Respond to the next set of follow-up questions that appear based on the items you selected in Step 2.
+1. Enter a URL for the location where you will host your solution.
> [!NOTE] > The URL can be any URL, but by default the generator suggests an Azure web site URL.
-1. In the next question, confirm if you want to include unit-testing for your solution. The default response is *yes*. If you choose to include unit-testing, the generated project will have a unit testing framework and some default unit tests for the different items being scaffolded.
+1. Confirm if you want to include unit-testing for your solution. The default response is **Yes**. If you opt to include unit-testing, the generated project will have a unit testing framework and some default unit tests for the different items being scaffolded.
> [!NOTE] > * For this tutorial choose not to include a test framework. > * The generator has a lot of built-in advanced features that you can opt-in or opt-out of.
-1. In order to make signing-in easy for you, you will also be asked if you want to use Azure Application Insights for signing-in. If you choose *Yes*, you will need to provide an Azure Application Insights key.
+1. In order to make signing-in easy for you, you will also be asked if you want to use Azure Application Insights for signing-in. If you select **Yes**, you will need to provide an Azure Application Insights key.
> [!NOTE] > For this tutorial opt-out of using Application Insights.
-The next set of questions will be based on the previously selected items. For a tab you only need to provide a name and optionally choose if you want to be able to use this app as a SharePoint Online web part. After you provide the name the generator will generate the project and install all dependencies. This will take a minute or two.
+ The next set of questions will be based on the previously selected items. For a tab you only need to provide a name and optionally choose if you want to be able to use this app as a SharePoint Online web part. After you provide the name the generator will generate the project and install all dependencies. This will take a minute or two.
-## Add some code to your tab
+## Add code to your tab
After the generator is done you can open up the solution in your favorite code editor. Take a minute or two and familiarize yourself with how the code is organized. For more information, see [Project Structure](https://github.com/OfficeDev/generator-teams/wiki/Project-Structure) documentation.
-Your tab is in the `./src/app/scripts/myFirstAppTab/MyFirstAppTab.tsx` file. This is the TypeScript React-based class for your tab. Locate the `render()` method and add a line of code inside the `<PanelBody>` control so it looks like this:
+Your tab is in the `./src/app/scripts/myFirstAppTab/MyFirstAppTab.tsx` file. This is the TypeScript React-based class for your tab.
-``` TypeScript
-<PanelBody>
- <div style={styles.section}>
- Hello World! Yo Teams rocks!
- </div>
-</PanelBody>
-```
+1. Locate the `render()` method and add a line of code inside the `<PanelBody>` control so it looks like this:
-Save the file and return to the command prompt.
+ ``` TypeScript
+ <PanelBody>
+ <div style={styles.section}>
+ Hello World! Yo Teams rocks!
+ </div>
+ </PanelBody>
+ ```
+1. Save the file and return to the command prompt.
## Build your app
-You can now build your project. This is done in two steps (or one step, see below).
+You can now build your project. This is done in two steps.
-First you need to create the Teams App manifest file, that you upload/sideload into Microsoft Teams. This is done by the Gulp task `gulp manifest`. This will validate the manifest and create a zip file in the `./package` directory.
-
-To build your solution you use the `gulp build` command. This will transpile your solution into the `./dist` folder.
+1. Create the Teams App manifest file for the app that you uploaded into Microsoft Teams. This is done by the Gulp task `gulp manifest`. This will validate the manifest and create a zip file in the `./package` directory.
+1. Run the `gulp build` command to build the solution. This will transpile your solution into the `./dist` folder.
## Run your app
-To run your app you use the `gulp serve` command. This will build and start a local web server for you to test your app. The command will also rebuild the application whenever you save a file in your project.
-
-You should now be able to browse to `http://localhost:3007/myFirstAppTab/` to ensure that your tab is rendering. However, not in Microsoft Teams yet:
-
-![view your site in a browser](~/assets/yeoman-images/teams-first-app-3.png)
+To run your app, use the `gulp serve` command. This will build and start a local web server for you to test your app. The command will also rebuild the application whenever you save a file in your project.
-## Run your app in Microsoft Teams
+You should now be go to `http://localhost:3007/myFirstAppTab/` and ensure that your tab is rendering. However, it is not in Microsoft Teams yet.
-Microsoft Teams does not allow you to have your app hosted on localhost, so you need to either publish it to a public URL or use a proxy such as ngrok.
+**To render your tab in Microsoft Teams**
-Good news is that the scaffolded project has this built-in. When you run `gulp ngrok-serve` the ngrok service will be started in the background, with a unique and public DNS entry and it will also package the manifest with that unique URL and then do the exact same thing as `gulp serve`.
+![view your site in a browser](~/assets/yeoman-images/teams-first-app-3.png)
-After running `gulp ngrok-serve`, create a new Microsoft Teams team and when it is created click on the Team name, to go to the teams settings and then select *Apps*. In the lower right corner you should see a link *Upload a custom app*, select it and then browse to your project folder and the subfolder called `package`. Select the zip file in that folder and choose open. Your App is now sideloaded into Microsoft Teams:
+### Run your app in Microsoft Teams
-![sideloaded app](~/assets/yeoman-images/teams-first-app-4.png)
+Microsoft Teams does not allow you to have your app hosted on localhost, so you need to either publish it to a public URL or use a proxy such as ngrok. Good news is that the scaffolded project has this built-in.
-Go back to the *General* channel and select *+* to add a new Tab. You should see your tab in the list of tabs:
+**To run your app in Teams**
-![configure tab](~/assets/yeoman-images/teams-first-app-5.png)
+1. Run `gulp ngrok-serve` in Terminal. When you run `gulp ngrok-serve` the ngrok service will be started in the background, with a unique and public DNS entry and it will also package the manifest with that unique URL and then do the exact same thing as `gulp serve`.
+1. Create a new Microsoft Teams team.
+1. Select the Team name > Teams Settings > Apps.
+1. From the lower right corner, select **Upload a custom app**.
+1. Go to the `package` folder under your project folder.
+1. Select the zip file in that folder and select open.
+ Your App is now sideloaded into Microsoft Teams:
-Choose your tab and follow the instructions to add it. Notice that you have a custom configuration dialog, for which you can edit the source. Select *Save* to add your tab to the channel. Once done your tab should be loaded inside Microsoft Teams!
+ ![sideloaded app](~/assets/yeoman-images/teams-first-app-4.png)
+1. Go back to the **General** channel and select **+** to add a new Tab. You should see your tab in the list of tabs:
+ ![configure tab](~/assets/yeoman-images/teams-first-app-5.png)
+1. Select your tab and follow the instructions to add it. Notice that you have a custom configuration dialog, for which you can edit the source. Select *Save* to add your tab to the channel. Your tab is now loaded inside Microsoft Teams!
-![running tab in teams](~/assets/yeoman-images/teams-first-app-6.png)
+ ![running tab in teams](~/assets/yeoman-images/teams-first-app-6.png)
-## Upgrade Microsoft Teams
+### Upgrade Microsoft Teams
You can also upgrade your current Microsoft Teams version to the latest version using the Microsoft Teams Yeoman generator.
You can also upgrade your current Microsoft Teams version to the latest version
```PowerShell yo teams --version ```
-2. Use the following command to select update your generator:
+2. Use the following command to select and update your generator:
```PowerShell yo ```
-3. Use the arrow keys to choose **Update your Generators**:
+3. Use the arrow keys to select **Update your Generators**:
![image of YoSelectUpdatGen](~/assets/images/Update-Teams/YoSelectUpdateGen.png)
You can also upgrade your current Microsoft Teams version to the latest version
```PowerShell yo teams --version ```
-
-**Congrats! You built and deployed your first Microsoft Teams app. You also upgraded Microsoft Teams.**
+ Congrats! You built and deployed your first Microsoft Teams app. You also upgraded Microsoft Teams.
+
+ ## See also
+
+* [Tutorials Overview](code-samples.md)
+* [Code Samples](https://github.com/OfficeDev/Microsoft-Teams-Samples)