Updates from: 02/13/2021 04:20:21
Service Microsoft Docs article Related commit history on GitHub Change details
platform https://docs.microsoft.com/en-us/microsoftteams/platform/concepts/build-and-test/deep-links https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/concepts/build-and-test/deep-links.md
@@ -7,9 +7,9 @@ keywords: teams deep link deeplink
# Create deep links to content and features in Microsoft Teams
-You can create links to information and features within Teams. Examples of where this may be useful:
+You can create links to information and features within Teams. Examples where creating deep links are useful are as follows:
-* Navigating the user to content within one of your app's tabs. For instance, your app may have a bot that sends messages notifying the user of an important activity. When the user taps on the notification, the deep link navigates to the tab so the user can view more details about the activity.
+* Navigating the user to content within one of your app's tabs. For instance, your app can have a bot that sends messages notifying the user of an important activity. When the user taps on the notification, the deep link navigates to the tab so the user can view more details about the activity.
* Your app automates or simplifies certain user tasks, such as creating a chat or scheduling a meeting, by pre-populating the deep links with required parameters. This avoids the need for users to manually enter information. > [!NOTE]
@@ -30,12 +30,12 @@ You can create links to information and features within Teams. Examples of where
## Deep linking to your tab
-You can create deep links to entities in Teams. Typically, this is used to create links that navigate to content and information within your tab. For example, if your tab contains a task list team members may create and share links to individual tasks. When clicked, the link navigates to your tab which focuses on the specific item. To implement this, you add a "copy link" action to each item, in whatever way best suits your UI. When the user takes this action, you call `shareDeepLink()` to display a dialog box containing a link that the user can copy to the clipboard. When you make this call, you also pass an ID for your item, which you get back in the [context](~/tabs/how-to/access-teams-context.md) when the link is followed and your tab is reloaded.
+You can create deep links to entities in Teams. Typically, this is used to create links that navigate to content and information within your tab. For example, if your tab contains a task list team members can create and share links to individual tasks. When you select the link, it navigates to your tab which focuses on the specific item. To implement this, you add a "copy link" action to each item, in whatever way best suits your UI. When the user takes this action, you call `shareDeepLink()` to display a dialog box containing a link that the user can copy to the clipboard. When you make this call, you also pass an ID for your item, which you get back in the [context](~/tabs/how-to/access-teams-context.md) when the link is followed and your tab is reloaded.
-Alternatively, you can also generate deep links programmatically, using the format specified later in this topic. You might want to use these in [bot](~/bots/what-are-bots.md) and [connector](~/webhooks-and-connectors/what-are-webhooks-and-connectors.md) messages that inform users about changes to your tab, or to items within it.
+Alternatively, you can also generate deep links programmatically, using the format specified later in this topic. You can use these in [bot](~/bots/what-are-bots.md) and [connector](~/webhooks-and-connectors/what-are-webhooks-and-connectors.md) messages that inform users about changes to your tab, or to items within it.
> [!NOTE]
-> This is different from the links provided by the **Copy link to tab** menu item, which just generates a deep link that points to this tab.
+> This deep link is different from the links provided by the **Copy link to tab** menu item, which just generates a deep link that points to this tab.
>[!NOTE] > Currently, shareDeepLink does not work on mobile platforms.
@@ -56,15 +56,15 @@ Provide these fields:
> Personal tabs have a `personal` scope, while channel and group tabs use `team` or `group` scopes. The two tab types have a slightly different syntax since only the configurable tab has a `channel` property associated with its context object. See the [manifest](~/resources/schem) reference for more information on tab scopes. > [!NOTE]
-> Deep links work properly only if the tab was configured using the v0.4 or later library and because of that has an entity ID. Deep links to tabs without entity IDs still navigate to the tab but can't provide the sub-entity ID to the tab.
+> Deep links work properly only if the tab was configured using the v0.4 or later library and because of that has an entity ID. Deep links to tabs without entity IDs still navigate to the tab but can not provide the sub-entity ID to the tab.
-Use this format for a deep link that you can use in a bot, connector, or messaging extension card:
+Use the following format for a deep link that you can use in a bot, connector, or messaging extension card:
`https://teams.microsoft.com/l/entity/<appId>/<entityId>?webUrl=<entityWebUrl>&label=<entityLabel>&context=<context>` > [!NOTE] > If the bot sends a message containing a `TextBlock` with a deep link, then a new browser tab is opened when the user selects the link. This happens in Chrome and in the Microsoft Teams desktop app, both running on Linux.
-> If the bot sends the same deep link URL into an `Action.OpenUrl`, then the Teams tab is opened in the current browser tab when the user clicks on the link. No new browser tab is opened.
+> If the bot sends the same deep link URL into an `Action.OpenUrl`, then the Teams tab is opened in the current browser tab when the user selects the link. No new browser tab is opened.
The query parameters are:
@@ -74,7 +74,7 @@ The query parameters are:
* `entityLabel` or `subEntityLabel`&emsp;A label for the item in your tab, to use when displaying the deep link; for example, "Task List 123" or "Task 456" * `context`&emsp;A JSON object containing the following fields: * `subEntityId`&emsp;An ID for the item _within_ the tab; for example, "task456"
- * `channelId`&emsp;The Microsoft Teams channel ID (available from the tab [context](~/tabs/how-to/access-teams-context.md); for example, "19:cbe3683f25094106b826c9cada3afbe0@thread.skype". This property is only available in configurable tabs with a scope of "team". It is not available in static tabs, which have a scope of "personal".
+ * `channelId`&emsp;The Microsoft Teams channel ID that is available from the tab [context](~/tabs/how-to/access-teams-context.md); for example, "19:cbe3683f25094106b826c9cada3afbe0@thread.skype". This property is only available in configurable tabs with a scope of "team". It is not available in static tabs, which have a scope of "personal".
Examples:
@@ -84,7 +84,7 @@ Examples:
* Link to a task item within the static tab: `https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123/456&label=Task 456&context={"subEntityId": "task456"}` > [!IMPORTANT]
-> Ensure that all query parameters are properly URI encoded. For the sake of readability, the above examples are not, but you should. Using the last example:
+> Ensure that all query parameters are properly URI encoded. You must follow the preceeding examples using the last example:
> ```javascript > var encodedWebUrl = encodeURI('https://tasklist.example.com/123/456&label=Task 456'); > var encodedContext = encodeURI('{"subEntityId": "task456"}');
@@ -93,19 +93,19 @@ Examples:
### Consuming a deep link from a tab
-When navigating to a deep link, Microsoft Teams simply navigates to the tab and provides a mechanism via the Microsoft Teams JavaScript library to retrieve the sub-entity ID (if it exists).
+When navigating to a deep link, Microsoft Teams simply navigates to the tab and provides a mechanism through the Microsoft Teams JavaScript library to retrieve the sub-entity ID if it exists.
-The [`microsoftTeams.getContext`](/javascript/api/@microsoft/teams-js#getcontext--context--context--void-) call returns a context that includes the `subEntityId` field if the tab was navigated to via a deep link.
+The [`microsoftTeams.getContext`](/javascript/api/@microsoft/teams-js#getcontext--context--context--void-) call returns a context that includes the `subEntityId` field if the tab is navigated through a deep link.
## Deep linking from your tab
-You can deeplink to content in Teams from your tab. This is useful if your tab needs to link to other content in Teams such as to a channel, message, another tab or even to open a scheduling dialog. To trigger a deeplink from your tab you should call:
+You can deeplink to content in Teams from your tab. This is useful if your tab needs to link to other content in Teams, such as to a channel, message, another tab or even to open a scheduling dialog. To trigger a deeplink from your tab you should call:
```Javascript microsoftTeams.executeDeepLink(/*deepLink*/); ```
-This will navigate you to the correct URL, or trigger a client action such as opening a scheduling or app install dialog. Example:
+This call navigates you to the correct URL, or trigger a client action, such as opening a scheduling or app install dialog. See the following example:
```Javascript // Open a scheduling dialog from your tab
@@ -117,7 +117,7 @@ microsoftTeams.executeDeepLink("https://teams.microsoft.com/l/app/f46ad259-0fe5-
## Deep linking to a chat
-You can create deep links to private chats between users by specifying the set of participants. If a chat doesn't exist with the specified participants, the link will navigate the user to an empty new chat. New chats will be created in draft state until the user sends the first message. Optionally, you can specify the name of the chat (if it doesn't already exist), along with text that should be inserted into the user's compose box. You can think of this feature as a shortcut for the user taking the manual action of navigating to or creating the chat, and then typing out the message.
+You can create deep links to private chats between users by specifying the set of participants. If a chat does not exist with the specified participants, the link navigates the user to an empty new chat. New chats are created in draft state until the user sends the first message. Otherwise, you can specify the name of the chat if it does not already exist, along with text that should be inserted into the user's compose box. You can think of this feature as a shortcut for the user taking the manual action of navigating to or creating the chat, and then typing out the message.
As an example use case, if you are returning an Office 365 user profile from your bot as a card, this deep link can allow the user to easily chat with that person.
@@ -131,12 +131,24 @@ Example: `https://teams.microsoft.com/l/chat/0/0?users=joe@contoso.com,bob@conto
The query parameters are:
-* `users`: The comma-separated list of user IDs representing the participants of the chat. The user performing the action is always included as a participant. The User ID field currently only supports the Azure AD UserPrincipalName (typically an email address).
-* `topicName`: An optional field for chat's display name, in the case of a chat with 3 or more users. If this field is not specified, the chat's display name will be based on the names of the participants.
+* `users`: The comma-separated list of user IDs representing the participants of the chat. The user that performs the action is always included as a participant. Currently, the User ID field supports the Azure AD UserPrincipalName, typically an email address only.
+* `topicName`: An optional field for chat's display name, in the case of a chat with 3 or more users. If this field is not specified, the chat's display name is based on the names of the participants.
* `message`: An optional field for the message text that you want to insert into the current user's compose box while the chat is in a draft state. To use this deep link with your bot, you can specify this as the URL target in your card's button or tap action through the `openUrl` action type.
+### Generating a deep link to a call
+
+Use this format for a deep link that you can use in a bot, connector, or messaging extension card:
+
+`https://teams.microsoft.com/l/call/0/0?users=<user1>,<user2>`
+
+Example: `https://teams.microsoft.com/l/call/0/0?users=joe@contoso.com,bob@contoso.com&topicName=Prep%20For%20Meeting%20Tomorrow&message=Hi%20folks%2C%20kicking%20off%20a%20chat%20about%20our%20meeting%20tomorrow`
+
+The query parameters are:
+
+* `users`: The comma-separated list of user IDs representing the participants of the call. The user that performs the action is always included as a participant. Currently, the User ID field supports the Azure AD UserPrincipalName, typically an email address only.
+ ## Linking to the scheduling dialog > [!Note]
@@ -146,19 +158,19 @@ You can create deep links to the Teams built-in scheduling dialog. This is espec
### Generating a deep link to the scheduling dialog
-Use this format for a deep link that you can use in a bot, Connector, or messaging extension card:
+Use the following format for a deep link that you can use in a bot, Connector, or messaging extension card:
`https://teams.microsoft.com/l/meeting/new?subject=<meeting subject>&startTime=<date>&endTime=<date>&content=<content>&attendees=<user1>,<user2>,<user3>,...` Example: `https://teams.microsoft.com/l/meeting/new?subject=test%20subject&attendees=joe@contoso.com,bob@contoso.com&startTime=10%2F24%2F2018%2010%3A30%3A00&endTime=10%2F24%2F2018%2010%3A30%3A00&content=ΓÇïΓÇïΓÇïΓÇïΓÇïΓÇïΓÇïtest%3AcontentΓÇïΓÇïΓÇïΓÇïΓÇïΓÇïΓÇïΓÇïΓÇïΓÇïΓÇïΓÇïΓÇïΓÇï` The query parameters are:
-* `attendees`: The optional comma-separated list of user IDs representing the attendees of the meeting. The user performing the action is the meeting organizer. The User ID field currently only supports the Azure AD UserPrincipalName (typically an email address).
+* `attendees`: The optional comma-separated list of user IDs representing the attendees of the meeting. The user performing the action is the meeting organizer. The User ID field currently only supports the Azure AD UserPrincipalName, typically an email address.
* `startTime`: The optional start time of the event. This should be in [long ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601), for example ΓÇ£2018-03-12T23:55:25+02:00ΓÇ¥. * `endTime`: The optional end time of the event, also in ISO 8601 format. * `subject`: An optional field for the meeting subject. * `content`: An optional field for the meeting details field.
-Currently, specifying the location is not supported. When generating your start and end times be sure to specify the UTC offset (time zones).
+Currently, specifying the location is not supported. You must specify the UTC offset, it means time zones when generating your start and end times.
To use this deep link with your bot, you can specify this as the URL target in your card's button or tap action through the `openUrl` action type.
platform https://docs.microsoft.com/en-us/microsoftteams/platform/includes/get-started/get-started-use-app-studio https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/includes/get-started/get-started-use-app-studio.md
@@ -2,19 +2,19 @@
App Studio is a Teams app that you can install from the Teams store. It simplifies the creation and registration of an app.
-To install App Studio in Teams, click on the app store icon at the bottom of the left hand bar, and search for App Studio.
+To install App Studio in Teams, select the **Apps** icon at the bottom of the left-hand bar, and search for **App Studio**.
<img width="450px" alt="Finding App Studio in the Store View" src="~/assets/images/get-started/searchforAppStudio.png"/>
-Once you find the tile for App Studio, click on it and choose *install* in the dialog that pops up.
+Select the **App Studio** tile and choose **Install**. The App Studio is installed.
<img width="450px" alt="Installing App Studio" src="~/assets/images/get-started/InstallingAppStudio.png"/>
-Once App Studio is installed click on the Manifest editor tab to begin creating the app package for your Teams app.
+Select the **Manifest editor** tab to create the app package for your Teams app.
<img width="450px" alt="App Studio" src="~/assets/images/get-started/AppStudio.png"/>
-The sample comes with its own pre-made manifest, and is designed to build an app package when the project is built. On .NET this is done in Visual Studio, and on Node JS this is done by typing `gulp` at the command line in the root directory of the project.
+The sample comes with its own pre-made manifest and is designed to build an app package when the project is built. On .NET this is done in Visual Studio, and on Node JS this is done by typing `gulp` at the command line in the root directory of the project.
```bash $ gulp
@@ -28,21 +28,21 @@ Build completed. Output in manifest folder
[13:39:27] Finished 'default' after 62 ╬╝s ```
-The name of the generated app package is *helloworldapp.zip*. You can search for this file if the location is not clear in the tool you are using.
+The name of the generated app package is **helloworldapp.zip**. You can search for this file if the location is not clear in the tool you are using.
-In the next part of this walkthrough you are going to modify this app package by selecting the *Import an existing app* tile in the Manifest Editor.
+Now to modify this app package, select the **Import an existing app** tile in the **Manifest editor**.
<img width="450px" alt="Importing an existing app" src="~/assets/images/get-started/Importinganapp.png"/>
-Once the app package has been imported App Studio should look like this:
+Click the **Hello World** tile for your newly imported app.
-<img width="450px" alt="Importing the app package" src="~/assets/images/get-started/Importinganapp2.png"/>
+<img width="450px" alt="Newly imported app view" src="~/assets/images/get-started/HelloWorldappdetails.png"/>
-Click on the tile for your newly imported app, *Hello World*.
+The following image shows the imported app package in App Studio:
-<img width="450px" alt="Newly imported app view" src="~/assets/images/get-started/HelloWorldappdetails.png"/>
+<img width="450px" alt="Importing the app package" src="~/assets/images/get-started/Importinganapp2.png"/>
-There is a list of steps in the left-hand side of the Manifest editor, and on the right a list of properties that need to be filled in for each of those steps. Since you started with a sample app, much of the information is already filled out. The next steps will walk you through changing the parts that still need to be updated.
+There is a list of steps on the left-hand side of the Manifest editor and on the right-hand side, a list of properties that need to be filled in for each of those steps. Since you started with a sample app, much of the information is already filled out. The next steps will walk you through changing the parts that still need to be updated.
#### App details
@@ -50,7 +50,7 @@ Click on the *App details* entry under *Details*. Click the *Generate* button to
Your new app id should look something like: `2322041b-72bf-459d-b107-f4f335bc35bd`.
-Look through the rest of the App details in the right hand pane, and familiarize yourself with some of the entries such as *Developer information* and *Branding*. These sections are important if you are writing a new app for distribution.
+Look through the rest of the App details in the right-hand pane, and familiarize yourself with some of the entries such as *Developer information* and *Branding*. These sections are important if you are writing a new app for distribution.
#### Capabilities: Tabs
@@ -85,7 +85,7 @@ Bots are the most common way to add functionality to your app. The hello world s
<img width="450px" alt="Adding a bot" src="~/assets/images/get-started/Bots.png"/>
-The bot that was imported from the sample does not have an App ID associated with it yet. You will have to create a new bot so that App Studio can create a new App ID and register it with Microsoft. Note that this is the App ID for the bot, which is different from the App ID that we created for the app in a earlier step. Each bot in an app requires its own App ID.
+The bot that was imported from the sample does not have an App ID associated with it yet. You will have to create a new bot so that App Studio can create a new App ID and register it with Microsoft. Note that this is the App ID for the bot, which is different from the App ID created for the app. Each bot in an app requires its own App ID.
Click the *delete* button next to the *Imported bot* in the bot list.
@@ -93,9 +93,9 @@ Now there are no bots left to show. Click *Setup*. This will display the *Set up
<img width="450px" alt="Adding a bot dialog" src="~/assets/images/get-started/Setupbot.png"/>
-Add a bot name such as `Contoso bot`, and select all three buttons under *scope*.
+Add a bot name such as `Contoso bot`, and select all three buttons under **Scope**.
-Choose *Create bot* to exit the dialog. App Studio will spend a moment registering your bot with Microsoft, and then should display your new bot in the bot list. Now would be a good time to open a text file in notepad and copy and paste your new bot id into it. You will need this id later.
+Choose *Create bot* to exit the dialog. App Studio registers your bot with Microsoft and displays your new bot in the bot list. Now would be a good time to open a text file in notepad and copy and paste your new bot id into it. You will need this id later.
Click *Generate New Password*, and make a note of the password in the same text file you noted your Bot app ID in. This is the only time your password will be shown, so be sure to do this now.
@@ -107,17 +107,17 @@ Now would be a good time to save your text file if you have not done so already.
Messaging extensions let users ask for information from your service and post that information, in the form of cards, right into the channel conversation. Messaging extensions appear along the bottom of the compose box.
-Click on *Messaging extensions* under *Capabilities* in the left hand column of App Studio to begin configuring the messaging extension.
+Select **Messaging extensions** under **Capabilities** in the left-hand column of App Studio to configure the messaging extension.
<img width="450px" alt="Adding a messaging extension" src="~/assets/images/get-started/Messagingextensions.png"/>
-The sample messaging extension is listed in the right hand pane under *Messaging Extensions*. Click *Delete* again to remove this entry, and then click the *Set up* button following the same steps as you followed for bots. This will display the *Messaging Extension* dialog.
+The sample messaging extension is listed in the right-hand pane under **Messaging Extensions**. Select **Delete** again to remove this entry, and then click the *Set up* button following the same steps as you followed for bots. This will display the *Messaging Extension* dialog.
Select the *Use existing bot* tab, then *Select from one of my existing bots*. In the drop-down menu, select the bot you created in the section above. Add a *Bot name* and click *Save* to close the dialog. Under the *Command* section, click *Add*. We're adding a search-based command, so choose the *Allow users to query your service...* option.
-In the *New command* dialog enter the following values.
+In the **New command** dialog, enter the following values.
Under *New command*:
@@ -135,9 +135,11 @@ Once you're entered the information, click *Save* to close the dialog.
#### Register your app in Teams
-You have now completed entering the details of your app, but two steps remain. First you must use the Test and Distribute section of App Studio to install your app in Teams, and second you must update your hosted application with the App ID and password for your bot. Remember that the sample expects to use the same App ID and password for both the bot and the messaging extension.
+You have now completed entering the details of your app, but the following two steps remain:
+1. Use the Test and Distribute section of App Studio to install your app in Teams.
+1. Update your hosted application with the App ID and password for your bot. Remember that the sample expects to use the same App ID and password for both the bot and the messaging extension.
-Click on the *Test and distribute* item under *Finish* in the left hand column of App Studio.
+Select the **Test and distribute** item under **Finish** in the left-hand column of App Studio.
<img width="450px" alt="Testing your app" src="~/assets/images/get-started/Testanddistribute.png"/>
@@ -145,10 +147,10 @@ In order to upload your app to Teams, click the *Install* button under *Test and
<img width="450px" alt="Adding a messaging extension dialog" src="~/assets/images/get-started/InstallingHelloWorld.png"/>
-Click on the *Search* box in the *Add to a team* section and select a team to add the sample app to. Usually you will want to set up a special team for testing.
+Select the **Search** box in the **Add to a team** section and select a team to add the sample app to. Usually, you can set up a special team for testing.
-Click the *Install* button at the bottom of the dialog.
+Select the **Install** button at the bottom of the dialog.
-This finishes the App Studio portion of this walkthrough. You should now see your app running in Teams, however the bot and the messaging extension will not work until you update the hosted applications environment to know what the App IDs and passwords are.
+This finishes the App Studio portion of this walkthrough. You should now see your app running in Teams, however, the bot and the messaging extension will not work until you update the hosted applications environment to know what the App IDs and passwords are.
<img width="450px" alt="The finished app" src="~/assets/images/get-started/Finishedhelloworld.png"/>
platform https://docs.microsoft.com/en-us/microsoftteams/platform/includes/prepare-environment https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/includes/prepare-environment.md
@@ -1,3 +1,3 @@
## Prepare your development environment
-The first thing you'll need to do is prepare your development environment. You'll need to make sure custom app uploading is enabled for the Office 365 organization you want to build your app in. 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 additional information see [Setup your development environment](~/concepts/build-and-test/prepare-your-o365-tenant.md).
+The first thing to do is to prepare your development environment. Make sure custom app uploading is 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 https://docs.microsoft.com/en-us/microsoftteams/platform/messaging-extensions/how-to/action-commands/respond-to-task-module-submit https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/messaging-extensions/how-to/action-commands/respond-to-task-module-submit.md
@@ -9,9 +9,9 @@
[!include[v4-to-v3-SDK-pointer](~/includes/v4-to-v3-pointer-me.md)]
-Once a user submits the task module, your web service will receive a `composeExtension/submitAction` invoke message with the command id and parameter values set. Your app will have five seconds to respond to the invoke, otherwise the user will receive an "Unable to reach the app" error message, and any reply to the invoke will be ignored by the Teams client.
+After a user submits the task module, your web service receives a `composeExtension/submitAction` invoke message with the command ID and parameter values. Your app has five seconds to respond to the invoke, otherwise the user receives an error message *Unable to reach the app*, and any reply to the invoke is ignored by the Teams client.
-You have the following options for responding.
+You have the following options for responding:
* No response - You can choose to use the submit action to trigger a process in an external system, and not provide any feedback to the user. This can be useful for long-running processes, and you may choose to provide feedback in another manner (for example, with a [proactive message](~/bots/how-to/conversations/send-proactive-messages.md). * [Another task module](#respond-with-another-task-module) - You can respond with an additional task module as part of a multi-step interaction.
@@ -20,7 +20,7 @@ You have the following options for responding.
* [Request the user authenticate](~/messaging-extensions/how-to/add-authentication.md) * [Request the user provide additional configuration](~/messaging-extensions/how-to/add-configuration-page.md)
-The table below shows which types of responses are available based on the invoke location (`commandContext`) of the messaging extension. For authentication or configuration, once the user completes the flow the original invoke will be re-sent to your web service.
+For authentication or configuration, after the user completes the flow the original invoke is re-sent to your web service. The following table shows which types of responses are available based on the invoke location `commandContext` of the messaging extension:
|Response Type | compose | command bar | message | |--|:-:|:-:|::|
@@ -31,7 +31,7 @@ The table below shows which types of responses are available based on the invoke
## The submitAction invoke event
-Below are examples of receiving the invoke message.
+Examples of receiving the invoke message are as follows:
# [C#/.NET](#tab/dotnet)
@@ -57,7 +57,7 @@ class TeamsMessagingExtensionsActionPreview extends TeamsActivityHandler {
# [JSON](#tab/json)
-This is an example of the JSON object you will receive. The `commandContext` parameter indicates where your messaging extension was triggered from. The `data` object contains the fields on the form as parameters, and the values the user submitted. The JSON object here is shortened to highlight the most relevant fields.
+This is an example of the JSON object you receive. The `commandContext` parameter indicates where your messaging extension was triggered from. The `data` object contains the fields on the form as parameters, and the values the user submitted. The JSON object here is shortened to highlight the most relevant fields.
```json {
@@ -95,7 +95,6 @@ The most common way to respond to the `composeExtension/submitAction` request is
protected override async Task<MessagingExtensionActionResponse> OnTeamsMessagingExtensionSubmitActionAsync( ITurnContext<IInvokeActivity> turnContext, MessagingExtensionAction action, CancellationToken cancellationToken) {
- dynamic Data = JObject.Parse(action.Data.ToString());
var response = new MessagingExtensionActionResponse { ComposeExtension = new MessagingExtensionResult
@@ -104,13 +103,13 @@ protected override async Task<MessagingExtensionActionResponse> OnTeamsMessaging
Type = "result", }, };
- var card = new HeroCard
- {
- Title = Data["formField1"] as string,
- Subtitle = Data["formField2"] as string,
- Text = Data["formField3"] as string,
- };
-
+ var createCardData = ((JObject)action.Data).ToObject<CreateCardData>();
+var card = new HeroCard
+{
+ Title = createCardData.Title,
+ Subtitle = createCardData.Subtitle,
+ Text = createCardData.Text,
+};
var attachments = new List<MessagingExtensionAttachment>(); attachments.Add(new MessagingExtensionAttachment {
@@ -118,11 +117,8 @@ protected override async Task<MessagingExtensionActionResponse> OnTeamsMessaging
ContentType = HeroCard.ContentType, Preview = card.ToAttachment(), });- response.ComposeExtension.Attachments = attachments;- return response;- } ```
@@ -185,29 +181,29 @@ class TeamsMessagingExtensionsActionPreview extends TeamsActivityHandler {
You can choose to respond to the `submitAction` event with an additional task module. This can be useful when: * You need to collect large amounts of information.
-* If you need to dynamically change what information you're collecting based on user input
+* If you need to dynamically change what information you are collecting based on user input
* If you need to validate the information submitted by the user and potentially resend the form with an error message if something is wrong.
-The method for response is the same as [responding to the initial `fetchTask` event](~/messaging-extensions/how-to/action-commands/create-task-module.md). If you're using the Bot Framework SDK the same event will trigger for both submit actions. This mean you need to be sure to add logic which determines the correct response.
+The method for response is the same as [responding to the initial `fetchTask` event](~/messaging-extensions/how-to/action-commands/create-task-module.md). If you are using the Bot Framework SDK the same event triggers for both submit actions. This means you must add logic which determines the correct response.
## Bot response with Adaptive Card >[!Note]
->This flow requires that you add the `bot` object to your app manifest, and that you have the necessary scope defined for the bot. Use the same Id as your messaging extension for your bot.
+>This flow requires that you add the `bot` object to your app manifest, and that you have the necessary scope defined for the bot. Use the same ID as your messaging extension for your bot.
-You can also respond to the submit action by inserting a message with an Adaptive Card into the channel with a bot. Your user will be able to preview the message before submitting it, and potentially edit/interact with it as well. This can be very useful in scenarios where you need to gather information from your users before creating an adaptive card response, or when you're going to need to update the card after someone interacts with it. The following scenario shows how the app Polly uses this flow to configure a poll without including the configuration steps in the channel conversation.
+You can also respond to the submit action by inserting a message with an Adaptive Card into the channel with a bot. Your user can preview the message before submitting it, and potentially edit or interact with it as well. This can be very useful in scenarios where you gather information from your users before creating an adaptive card response, or when you update the card after someone interacts with it. The following scenario shows how the app Polly uses this flow to configure a poll without including the configuration steps in the channel conversation:
-1. The user clicks the messaging extension to trigger the task module.
+1. The user selects the messaging extension to trigger the task module.
2. The user configures the poll with the task module. 3. After submitting the task module the app uses the information provided to build the poll as an Adaptive Card and sends it as a `botMessagePreview` response to the client.
-4. The user can then preview the adaptive card message before the bot inserts it into the channel. If the app is not already a member of the channel, clicking `Send` will add the it.
- 1. The user can also chose to `Edit` the message, which returns them to the original task module.
+4. The user can then preview the adaptive card message before the bot inserts it into the channel. If the app is not already a member of the channel, selecting `Send` adds it.
+ 1. The user can also choose to `Edit` the message, which returns them to the original task module.
5. Interacting with the adaptive card changes the message before sending it.
-6. Once the user clicks `Send` the bot posts the message to the channel.
+6. After the user selects `Send` the bot posts the message to the channel.
### Respond to initial submit action
-To enable this flow your task module should respond to the initial `composeExtension/submitAction` message with a preview of the card that the bot will send to the channel. This gives the user the opportunity to verify the card before sending, and also will attempt to install your bot in the conversation if it is not already installed.
+To enable this flow your task module should respond to the initial `composeExtension/submitAction` message with a preview of the card that the bot send to the channel. This gives the user the opportunity to verify the card before sending, and also attempt to install your bot in the conversation if it is not already installed.
# [C#/.NET](#tab/dotnet)
@@ -215,7 +211,7 @@ To enable this flow your task module should respond to the initial `composeExten
protected override async Task<MessagingExtensionActionResponse> OnTeamsMessagingExtensionSubmitActionAsync( ITurnContext<IInvokeActivity> turnContext, MessagingExtensionAction action, CancellationToken cancellationToken) {
- dynamic Data = JObject.Parse(action.Data.ToString());
+ dynamic createCardData = ((JObject) action.Data).ToObject(typeof(JObject));
var response = new MessagingExtensionActionResponse { ComposeExtension = new MessagingExtensionResult
@@ -315,7 +311,7 @@ class TeamsMessagingExtensionsActionPreview extends TeamsActivityHandler {
### The botMessagePreview send and edit events
-Your message extension will now need to respond to two new varieties of the `composeExtension/submitAction` invoke, where `value.botMessagePreviewAction = "send"`and `value.botMessagePreviewAction = "edit"`.
+Your message extension must respond now to two new varieties of the `composeExtension/submitAction` invoke, where `value.botMessagePreviewAction = "send"`and `value.botMessagePreviewAction = "edit"`.
# [C#/.NET](#tab/dotnet)
@@ -386,13 +382,13 @@ class TeamsMessagingExtensionsActionPreview extends TeamsActivityHandler {
### Respond to botMessagePreview edit
-If the user decides to edit the card before sending by clicking the **Edit** button, you will receive a `composeExtension/submitAction` invoke with `value.botMessagePreviewAction = edit`. You should typically respond by returning the task module you sent in response to the initial `composeExtension/fetchTask` invoke that began the interaction. This allows the user to start the process over by re-entering the original information. You should also consider using the information you now have available to pre-populate the task module so the user doesn't have fill out all of the information from scratch.
+If the user edits the card before sending by selecting the **Edit** button, you receive a `composeExtension/submitAction` invoke with `value.botMessagePreviewAction = edit`. You should typically respond by returning the task module you sent in response to the initial `composeExtension/fetchTask` invoke that began the interaction. This allows the user to start the process over by re-entering the original information. Use the available information to pre-populate the task module so the user does not have to fill out all of the information from scratch.
See [responding to the initial `fetchTask` event](~/messaging-extensions/how-to/action-commands/create-task-module.md). ### Respond to botMessagePreview send
-Once the user clicks the **Send** button, you will receive a `composeExtension/submitAction` invoke with `value.botMessagePreviewAction = send`. Your web service will need to create and send a proactive message with the Adaptive Card to the conversation, and also reply to the invoke.
+After the user selects the **Send** button, you receive a `composeExtension/submitAction` invoke with `value.botMessagePreviewAction = send`. Your web service has to create and send a proactive message with the Adaptive Card to the conversation, and also reply to the invoke.
# [C#/.NET](#tab/dotnet)
@@ -490,7 +486,7 @@ class TeamsMessagingExtensionsActionPreview extends TeamsActivityHandler {
# [JSON](#tab/json)
-You will receive a new `composeExtension/submitAction` message similar to the one below.
+You receive a new `composeExtension/submitAction` message similar to the following:
```json {
@@ -527,11 +523,11 @@ You will receive a new `composeExtension/submitAction` message similar to the on
In scenarios where a bot sends messages on behalf of a user, attributing the message to that user can help with engagement and showcase a more natural interaction flow. This feature allows you to attribute a message from your bot to a user on whose behalf it was sent.
-In the image below, on the left is a card message sent by a bot *without* user attribution and on the right is a card sent by a bot *with* user attribution.
+In the following image, on the left is a card message sent by a bot *without* user attribution and on the right is a card sent by a bot *with* user attribution.
![Screenshot](../../../assets/images/messaging-extension/user-attribution-bots.png)
-To use user attribution in teams, you need to add the `OnBehalfOf` mention entity to `ChannelData` in your `Activity` payload that is sent to Teams.
+To use the user attribution in teams, you must add the `OnBehalfOf` mention entity to `ChannelData` in your `Activity` payload that is sent to Teams.
# [C#/.NET](#tab/dotnet-1)
@@ -567,7 +563,7 @@ To use user attribution in teams, you need to add the `OnBehalfOf` mention entit
* * *
-Below is a description of the entities in the `OnBehalfOf` of Array:
+The following section is a description of the entities in the `OnBehalfOf` of Array:
#### Details of `OnBehalfOf` entity schema
platform https://docs.microsoft.com/en-us/microsoftteams/platform/samples/app-templates https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/samples/app-templates.md
@@ -7,18 +7,21 @@
-# App Templates for Microsoft Teams
+# App templates for Microsoft Teams
-App templates are production-ready apps for Microsoft Teams that are community driven, open-source, and available on GitHub. Each contains detailed instructions for deploying and installing that app for your organization, providing a ready-to-use app that you can install and begin using immediately. The complete source code is available as well, so you can explore it in detail, or fork the code and alter it to meet your specific needs.
+App templates are examples of complete apps for Microsoft Teams that are open-source and available on GitHub. Each app template contains detailed instructions for deploying and installing that app for your organization. It also provides a sample app that you can install and begin using immediately. The complete source code is available too, which allows you to explore it in detail or fork the code and alter it to meet your specific requirements.
+All app templates are provided under the [MIT License](https://github.com/OfficeDev/microsoft-teams-apps-eprescription/blob/master/LICENSE) terms.
+>[!NOTE]
+>You, not Microsoft must license and support apps created from app templates for your users and organizations.
**&#9734; Indicates newly released app templates.** ### Key benefits
-* **Plug and play experience:** All app templates include deployments scripts that will allow you to host all necessary services in Microsoft Azure. No coding is required to deploy the apps.
-* **Production-ready code:** The app templates conform to recommended best practices around security and infrastructure, and all community submitted changes to them are reviewed to ensure continued conformance.
-* **Customizable and extensible:** While all app templates are ready to deploy as they are, we provide the entire code base and deployment scripts so that you can easily customize or extend them to fit your unique needs.
-* **Detailed documentation & support:** All app templates are accompanied by end-to-end documentation on solution architecture, deployment, and configuration steps. The repositories are monitored as well, so please report any issues you encounter by raising an Issue on GitHub.
+* **Deploy directly to the cloud:** All app templates include deployment scripts that allows you to host all required services in Microsoft Azure or the Power Platform.
+* **Recommended sample code:** The app templates conform to recommended best practices around security and infrastructure. All community submitted changes to the app templates are reviewed to ensure conformance.
+* **Customizable and extensible:** While all app templates can be deployed with minimal configuration, we provide the entire code base and deployment scripts so that you can easily customize or extend them to fit your unique needs.
+* **Detailed documentation:** All app templates are accompanied by end-to-end documentation on solution architecture, deployment, and configuration steps.
## Adoption Bot &#9734;
platform https://docs.microsoft.com/en-us/microsoftteams/platform/tutorials/get-started-dotnet-app-studio https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/tutorials/get-started-dotnet-app-studio.md
@@ -1,15 +1,15 @@
Title: Tutorial - Create your first app using C#
-description: Learn how to get started building Microsoft Teams apps with C#/.NET.
+description: Learn how to get started building Microsoft Teams apps with C# or .NET.
keywords: getting started .net c# csharp Last updated 11/09/2018
-# Create your first Microsoft Teams app using C#
+# Create your first Teams app using C# or .NET
-This tutorial helps you get started creating a Microsoft Teams app using C# on .NET.
+This tutorial helps you to create a Microsoft Teams app using C# or .NET.
[!include [prepare your environment](~/includes/prepare-environment.md)]
@@ -22,11 +22,9 @@ To complete this tutorial, you need to get the following tools:
- [Install Git](https://git-scm.com/downloads) - [Install Visual Studio](https://www.visualstudio.com/downloads/). You can install the free community edition.
-If you see an option to add `git` to the PATH during installation, choose to do so. It will be handy.
+During installation, if there is an option to add `git` to the PATH, choose it.
-Verify your `git` installation by running the following in a terminal window:
-> [!NOTE]
-> Use the terminal window that you are most comfortable with on your platform. These examples use Bash, but will run on most platforms.
+In a terminal window, run the following command to verify your `git` installation:
```bash $ git --version
@@ -34,67 +32,73 @@ git version 2.17.1.windows.2
```
-Make sure to launch the latest version of Visual Studio and install any updates if shown.
+> [!NOTE]
+> Use a suitable terminal window on your platform. These examples use Bash but run on most platforms.
+
+Make sure to launch the latest version of Visual Studio and install any updates.
-You can continue to use this terminal window to run the commands that follow in this tutorial.
+You can use the same terminal window to run the commands in this tutorial.
<a name="DownloadSample"></a> ## Download the sample
-We have provided a simple [Hello, World!](https://github.com/OfficeDev/msteams-samples-hello-world-csharp) sample in C# to get you started. In a terminal window, run the following command to clone the sample repository to your local machine:
+You can get started with a simple [Hello, World!](https://github.com/OfficeDev/msteams-samples-hello-world-csharp) sample in C#. In a terminal window, run the following command to clone the sample repository to your local machine:
```bash git clone https://github.com/OfficeDev/msteams-samples-hello-world-csharp.git ``` > [!TIP]
-> You can [fork](https://help.github.com/articles/fork-a-repo/) this [repo](https://github.com/OfficeDev/msteams-samples-hello-world-csharp) if you want to modify and check in your changes to GitHub for future reference.
+> You can [fork](https://help.github.com/articles/fork-a-repo/) this [repo](https://github.com/OfficeDev/msteams-samples-hello-world-csharp) to modify and save your changes to GitHub for reference.
<a name="BuildRun"></a> ## Build and run the sample
-Once the repo is cloned, use Visual Studio to open the solution file `Microsoft.Teams.Samples.HelloWorld.sln` from the root directory of the sample and click `Build Solution` from the `Build` menu. You can run the sample by pressing `F5` or choosing `Start Debugging` from the `Debug` menu.
+After the repo is cloned, use Visual Studio to open the solution file `Microsoft.Teams.Samples.HelloWorld.sln` from the root directory of the sample and select `Build Solution` from the `Build` menu. To run the sample press `F5` or choose `Start Debugging` from the `Debug` menu.
-When the app starts, you will see a browser window open with the root of the app launched. You can navigate 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. You can navigate to the following URLs to verify that all the app URLs are loading:
-- [http://localhost:3333](http://localhost:3333)-- [http://localhost:3333/hello](http://localhost:3333/hello)-- [http://localhost:3333/first](http://localhost:3333/first)-- [http://localhost:3333/second](http://localhost:3333/second)
+- [https://localhost:44327/](https://localhost:44327/)
+- [https://localhost:44327/hello](https://localhost:44327/hello)
+- [https://localhost:44327/first](https://localhost:44327/first)
+- [https://localhost:44327/second]https://localhost:44327/second)
<a name="HostSample"></a> > [!Note]
-> If you receive an error like `Could not find a part of the path … bin\roslyn\csc.exe`, try updating the package with the command `Update-Package Microsoft.CodeDom.Providers.DotNetCompilerPlatform -r`. See [this question on StackOverflow](https://stackoverflow.com/questions/32780315) for additional details.
+> 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 StackOverflow](https://stackoverflow.com/questions/32780315).
## Host the 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. You can either host it in Microsoft Azure for free or create a tunnel to the local process on your development machine using `ngrok`. When you finish hosting your app make a note of its root URL. It will look something like: `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 reachable from the internet. To make your app reachable from the internet, 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 development machine using `ngrok`. When you finish hosting your app, note its root URL. For example, `https://yourteamsapp.ngrok.io` or `https://yourteamsapp.azurewebsites.net`.
### Tunnel using ngrok
-For quick testing you can run the app on your local machine and create a tunnel to it through 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`.
+For quick testing, you can run the app on your local machine and create a tunnel to it through a web endpoint. [ngrok](https://ngrok.com) is a free tool with which you can get a web address such as `https://d0ac14a5.ngrok.io`. You can [download and install](https://ngrok.com/download) ngrok. 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 ngrok, open a new terminal window and run the following command to create a tunnel:
```bash
-ngrok http 3333 -host-header=localhost:3333
+ngrok http 44327 -host-header=localhost:44327
```
-Ngrok will listen to requests from the internet and will route them to your app running on port 3333. You can verify by opening your browser and going to `https://d0ac14a5.ngrok.io/hello` to load your app's hello page. Please be sure to use the forwarding address displayed by ngrok in your console session instead of this URL.
+The sample uses port 44327 be sure to specify it.
+
+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.
> [!NOTE]
-> If you have used a different port in the [build and run](#build-and-run-the-sample) step above, make sure you use the same port number to setup the `ngrok` tunnel.
+> If you have used a different port in the [build and run](#build-and-run-the-sample) step, make sure 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 to keep it running without interfering with the app which you might later have to stop, rebuild and rerun. The `ngrok` session will return useful debugging information in this window.
+> 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, which you have to stop, rebuild, and rerun. The `ngrok` session provides useful debugging information in this window.
-The 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. The paid version of Ngrok does not have this limitation.
+The app is only available during the current session on your development machine. 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
-Microsoft Azure lets you host your .NET application on a free tier using shared infrastructure. This will be sufficient to run this `Hello World` sample. See [creating a new free account](https://azure.microsoft.com/free/) for more information.
+Microsoft Azure hosts your .NET application on a free tier using shared infrastructure. This is sufficient to run the `Hello World` sample. For more information, see [creating a new free account](https://azure.microsoft.com/free/).
Visual Studio has built-in support for app deployment to different providers, including Azure.
@@ -120,13 +124,13 @@ Once you install the app into a team, you will need to configure it to show cont
### Test your bot in Teams
-You can now interact with the bot in Teams. Choose a channel in the team where you registered your app, and type `@your-bot-name`. This is called an **\@mention**. Whatever message you send to the bot will be sent back to you as a reply.
+You can now interact with the bot in Teams. Choose a channel in the team where you registered your app and type `@your-bot-name`. This is called an **\@mention**. Whatever message you send to the bot will be sent back to you as a reply.
<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 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 bunch of random texts showing up. You can choose any one of them and it will be inserted it into your conversation.
+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 bunch of random texts showing up. You can choose any one of them and it is inserted into your conversation.
<img width="530px" alt="Messaging extension menu" src="~/assets/images/samples-hello-world-messaging-extensions-menu.png" />