Updates from: 01/29/2021 04:13:01
Service Microsoft Docs article Related commit history on GitHub Change details
platform https://docs.microsoft.com/en-us/microsoftteams/platform/bots/how-to/bots-filesv4 https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/bots/how-to/bots-filesv4.md new file mode 100644 /dev/null
@@ -0,0 +1,294 @@
+
+ Title: Send and receive files through the bot
+description: Describes how to send and receive files through the bot
+keywords: teams bots files send receive
Last updated : 05/20/2019++
+# Send and receive files through the bot
+
+> [!IMPORTANT]
+> The articles in this document are based on the v4 Bot Framework SDK.
+
+There are two ways to send files to and receive files from a bot:
+
+* **Using the Microsoft Graph APIs:** This method works for bots in all Microsoft Teams scopes:
+ * `personal`
+ * `channel`
+ * `groupchat`
+
+* **Using the Teams bot APIs:** These only support files in `personal` context.
+
+## Using the Graph APIs
+
+Post messages with card attachments that refer to existing SharePoint files, using the Graph APIs for [OneDrive and SharePoint](/onedrive/developer/rest-api/). To use the Graph APIs, obtain access to either of the following through the standard OAuth 2.0 authorization flow:
+* A user's OneDrive folder for `personal` and `groupchat` files.
+* The files in a team's channel for `channel` files.
+
+Graph APIs work in all Teams scopes.
+
+## Using the Teams bot APIs
+
+> [!NOTE]
+> Teams bot APIs work only in the `personal` context. They do not work in the `channel` or `groupchat` context.
+
+Using Teams APIs, the bot can directly send and receive files with users in the `personal` context, also known as personal chats. Implement features, such as expense reporting, image recognition, file archival, and e-signatures involving the editing of file content. Files shared in Teams typically appear as cards and allow rich in-app viewing.
+
+The following sections describe how to send file content as a direct user interaction, like sending a message. This API is provided as part of the Teams bot platform.
+
+### Configuring the bot to support files
+
+To send and receive files in the bot, set the `supportsFiles` property in the manifest to `true`. This property is described in the [bots](~/resources/schem#bots) section of the Manifest reference.
+
+The definition looks like this, `"supportsFiles": true`. If the bot does not enable `supportsFiles`, the features listed in this section do not work.
+
+### Receiving files in personal chat
+
+When a user sends a file to the bot, the file is first uploaded to the user's OneDrive for Business storage. The bot then receives a message activity notifying the user about the user upload. The activity contains file metadata, such as its name and the content URL. The user can directly read from this URL to fetch its binary content.
+
+#### Message activity with file attachment example
+
+```json
+{
+ "attachments": [{
+ "contentType": "application/vnd.microsoft.teams.file.download.info",
+ "contentUrl": "https://contoso.sharepoint.com/personal/johnadams_contoso_com/Documents/Applications/file_example.txt",
+ "name": "file_example.txt",
+ "content": {
+ "downloadUrl" : "https://download.link",
+ "uniqueId": "1150D938-8870-4044-9F2C-5BBDEBA70C9D",
+ "fileType": "txt",
+ "etag": "123"
+ }
+ }]
+}
+```
+
+The following table describes the content properties of the attachment:
+
+| Property | Purpose |
+| | |
+| `downloadUrl` | OneDrive URL for fetching the content of the file. The user can issue an `HTTP GET` directly from this URL. |
+| `uniqueId` | Unique file ID. This is the OneDrive drive item ID, in case the user sends a file to the bot. |
+| `fileType` | Type of file, such as .pdf or .docx. |
+
+As a best practice, acknowledge the file upload by sending a message back to the user.
+
+### Uploading files to personal chat
+
+The following steps are required to upload a file to a user:
+
+1. Send a message to the user requesting permission to write the file. This message must contain a `FileConsentCard` attachment with the name of the file to be uploaded.
+2. If the user accepts the file download, the bot receives an invoke activity with a location URL.
+3. To transfer the file, the bot performs an `HTTP POST` directly into the provided location URL.
+4. Optionally, remove the original consent card if you do not want the user to accept further uploads of the same file.
+
+#### Message requesting permission to upload
+
+The following desktop message contains a simple attachment object requesting user permission to upload the file:
+
+![Consent card requesting user permission to upload file](../../assets/images/bots/bot-file-consent-card.png)
+
+The following mobile message contains an attachment object requesting user permission to upload the file:
+
+![Consent card requesting user permission to upload file on mobile](../../assets/images/bots/mobile-bot-file-consent-card.png)
+
+```json
+{
+ "attachments": [{
+ "contentType": "application/vnd.microsoft.teams.card.file.consent",
+ "name": "file_example.txt",
+ "content": {
+ "description": "<Purpose of the file, such as: this is your monthly expense report>",
+ "sizeInBytes": 1029393,
+ "acceptContext": {
+ },
+ "declineContext": {
+ }
+ }
+ }]
+}
+```
+
+The following table describes the content properties of the attachment:
+
+| Property | Purpose |
+| | |
+| `description` | Describes the purpose of the file or summarizes its content. |
+| `sizeInBytes` | Provides the user an estimate of the file size and the amount of space it takes in OneDrive. |
+| `acceptContext` | Additional context that is silently transmitted to the bot when the user accepts the file. |
+| `declineContext` | Additional context that is silently transmitted to the bot when the user declines the file. |
+
+#### Invoke activity when the user accepts the file
+
+An invoke activity is sent to the bot if and when the user accepts the file. It contains the OneDrive for Business placeholder URL that the bot can then issue a `PUT` into to transfer the file contents. For information on uploading to the OneDrive URL, see [Upload bytes to the upload session](/onedrive/developer/rest-api/api/driveitem_createuploadsession#upload-bytes-to-the-upload-session).
+
+The following example shows a concise version of the invoke activity that the bot receives:
+
+```json
+{
+ "name": "fileConsent/invoke",
+ "value": {
+ "type": "fileUpload",
+ "action": "accept",
+ "context": {
+ },
+ "uploadInfo": {
+ "contentUrl": "https://contoso.sharepoint.com/personal/johnadams_contoso_com/Documents/Applications/file_example.txt",
+ "name": "file_example.txt",
+ "uploadUrl": "https://upload.link",
+ "uniqueId": "1150D938-8870-4044-9F2C-5BBDEBA70C8C",
+ "fileType": "txt",
+ "etag": "123"
+ }
+ }
+}
+```
+
+Similarly, if the user declines the file, the bot receives the following event with the same overall activity name:
+
+```json
+{
+ "name": "fileConsent/invoke",
+ "value": {
+ "type": "fileUpload",
+ "action": "decline",
+ "context": {
+ }
+ }
+}
+```
+
+### Notifying the user about an uploaded file
+
+After uploading a file to the user's OneDrive, send a confirmation message to the user. The message must contain the following `FileCard` attachment that the user can select, either to preview or open it in OneDrive, or download locally:
+
+```json
+{
+ "attachments": [{
+ "contentType": "application/vnd.microsoft.teams.card.file.info",
+ "contentUrl": "https://contoso.sharepoint.com/personal/johnadams_contoso_com/Documents/Applications/file_example.txt",
+ "name": "file_example.txt",
+ "content": {
+ "uniqueId": "1150D938-8870-4044-9F2C-5BBDEBA70C8C",
+ "fileType": "txt",
+ }
+ }]
+}
+```
+
+The following table describes the content properties of the attachment:
+
+| Property | Purpose |
+| | |
+| `uniqueId` | OneDrive or SharePoint drive item ID. |
+| `fileType` | Type of file, such as .pdf or .docx. |
+
+### Basic example in C#
+
+The following sample shows how to handle file uploads and send file consent requests in the bot's dialog:
+
+```csharp
+
+protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
+{
+ string filename = "teams-logo.png";
+ string filePath = Path.Combine("Files", filename);
+ long fileSize = new FileInfo(filePath).Length;
+ await SendFileCardAsync(turnContext, filename, fileSize, cancellationToken);
+}
+
+private async Task SendFileCardAsync(ITurnContext turnContext, string filename, long filesize, CancellationToken cancellationToken)
+{
+ var consentContext = new Dictionary<string, string>
+ {
+ { "filename", filename
+ },
+ };
+
+ var fileCard = new FileConsentCard
+ {
+ Description = "This is the file I want to send you",
+ SizeInBytes = filesize,
+ AcceptContext = consentContext,
+ DeclineContext = consentContext,
+ };
+
+ var asAttachment = new Attachment
+ {
+ Content = fileCard,
+ ContentType = FileConsentCard.ContentType,
+ Name = filename,
+ };
+
+ var replyActivity = turnContext.Activity.CreateReply();
+ replyActivity.Attachments = new List<Attachment>() { asAttachment
+ };
+ await turnContext.SendActivityAsync(replyActivity, cancellationToken);
+}
+
+protected override async Task OnTeamsFileConsentAcceptAsync(ITurnContext<IInvokeActivity> turnContext, FileConsentCardResponse fileConsentCardResponse, CancellationToken cancellationToken)
+{
+ try
+ {
+ JToken context = JObject.FromObject(fileConsentCardResponse.Context);
+
+ string filePath = Path.Combine("Files", context["filename"].ToString());
+ long fileSize = new FileInfo(filePath).Length;
+ var client = _clientFactory.CreateClient();
+ using (var fileStream = File.OpenRead(filePath))
+ {
+ var fileContent = new StreamContent(fileStream);
+ fileContent.Headers.ContentLength = fileSize;
+ fileContent.Headers.ContentRange = new ContentRangeHeaderValue(0, fileSize - 1, fileSize);
+ await client.PutAsync(fileConsentCardResponse.UploadInfo.UploadUrl, fileContent, cancellationToken);
+ }
+
+ await FileUploadCompletedAsync(turnContext, fileConsentCardResponse, cancellationToken);
+ }
+ catch (Exception e)
+ {
+ await FileUploadFailedAsync(turnContext, e.ToString(), cancellationToken);
+ }
+}
+
+protected override async Task OnTeamsFileConsentDeclineAsync(ITurnContext<IInvokeActivity> turnContext, FileConsentCardResponse fileConsentCardResponse, CancellationToken cancellationToken)
+{
+ JToken context = JObject.FromObject(fileConsentCardResponse.Context);
+
+ var reply = MessageFactory.Text($"Declined. We won't upload file <b>{context["filename"]}</b>.");
+ reply.TextFormat = "xml";
+ await turnContext.SendActivityAsync(reply, cancellationToken);
+}
+
+private async Task FileUploadCompletedAsync(ITurnContext turnContext, FileConsentCardResponse fileConsentCardResponse, CancellationToken cancellationToken)
+{
+ var downloadCard = new FileInfoCard
+ {
+ UniqueId = fileConsentCardResponse.UploadInfo.UniqueId,
+ FileType = fileConsentCardResponse.UploadInfo.FileType,
+ };
+
+ var asAttachment = new Attachment
+ {
+ Content = downloadCard,
+ ContentType = FileInfoCard.ContentType,
+ Name = fileConsentCardResponse.UploadInfo.Name,
+ ContentUrl = fileConsentCardResponse.UploadInfo.ContentUrl,
+ };
+
+ var reply = MessageFactory.Text($"<b>File uploaded.</b> Your file <b>{fileConsentCardResponse.UploadInfo.Name}</b> is ready to download");
+ reply.TextFormat = "xml";
+ reply.Attachments = new List<Attachment> { asAttachment
+ };
+
+ await turnContext.SendActivityAsync(reply, cancellationToken);
+}
+
+private async Task FileUploadFailedAsync(ITurnContext turnContext, string error, CancellationToken cancellationToken)
+{
+ var reply = MessageFactory.Text($"<b>File upload failed.</b> Error: <pre>{error}</pre>");
+ reply.TextFormat = "xml";
+ await turnContext.SendActivityAsync(reply, cancellationToken);
+}
+```
platform https://docs.microsoft.com/en-us/microsoftteams/platform/concepts/deploy-and-publish/appsource/prepare/frequently-failed-cases https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/concepts/deploy-and-publish/appsource/prepare/frequently-failed-cases.md
@@ -1,14 +1,13 @@
Title: App submission tips and frequently failed cases
-description: Describes tips for a successful Teams store submission and common reasons submissions fail.
--
+description: describes tips for a successful Teams store submission and common reasons submissions fail
-keywords: Teams apps validation most failed test cases rapid approval appsource publish
+
+keywords: app submission tips frequently failed cases validation guidelines
# Tips for a successful Microsoft Teams app submission
-This article addresses common reasons submitted apps fail validation. While it's not intended to be an exhaustive list of all potential issues with your app, following this guide will increase the likelihood that your app submission will pass the first time. *See* [Commercial marketplace certification policies](/legal/marketplace/certification-policies) for an extensive list of validation policies.
+This article addresses common reasons submitted apps fail validation. While it's not intended to be an exhaustive list of all potential issues with your app, following this guide will increase the likelihood that your app submission will pass the first time. See [Commercial marketplace certification policies](/legal/marketplace/certification-policies) for an extensive list of validation policies.
>[!NOTE] >**[Section 1140](/legal/marketplace/certification-policies#1140-teams)** is specific to Microsoft Teams and **[sub-section 1140.4](https://docs.microsoft.com/legal/marketplace/certification-policies#11404-functionality)** addresses functionality requirements for Teams apps.
@@ -17,27 +16,45 @@ This article addresses common reasons submitted apps fail validation. While it's
### &#9989; General considerations
-*See also* [Section 100 ΓÇö General](/legal/marketplace/certification-policies#100-general)
+See also [Section 100 ΓÇö General](/legal/marketplace/certification-policies#100-general)
* Ensure you are using version 1.4.1 or later of the [Microsoft Teams SDK](https://www.npmjs.com/package/@microsoft/teams-js). * Don't make changes to your app while the validation process is in progress. Doing so will require a complete revalidation of your app.
-* Your app must not stop responding, end unexpectedly, or contain programming errors. If an issue is encountered, your app should fail gracefully and provide a valid-way-forward message to the user.
-* Your app must not automatically download, install, or launch any executable code in the user environment. All downloads should seek explicit permission from the user.
+* Your app must not stop responding, end unexpectedly, or contain programming errors. If an issue occurs, your app must fail and provide valid information for the way-forward to the user.
+* Your app must not automatically download, install, or launch any executable code in the user environment. All downloads must seek explicit permission from the user.
* Any material that you associate with your experience, such as descriptions and support documentation, must be accurate. Use correct spelling, capitalization, punctuation, and grammar in your descriptions and materials.
-* Provide help and support information. It's highly recommended that your app include a help/FAQ link for the first-run user experience. For all personal apps, we recommend providing your help page as a personal tab for a better user experience.
-* Apps must not take the user out of Teams for core user scenarios. Using task modules/tabs is recommended to display information to users within Teams.
+* Provide help and support information. It's highly recommended that your app include a help or FAQ link for the first-run user experience. For all personal apps, we recommend providing your help page as a personal tab for a better user experience.
+* All apps must have a visual tour, such as **Take a Tour** or an **App Guide** in its configuration screen that talks about the app features and necessary integration in the following places:
+ * The store listing page (Long Description).
+ * Tab configuration screen.
+ * Welcome message for a bot.
+ * App source metadata.
+ * Connector configuration screen.
+
+* The visual tour can be a video, screenshot, a link to a static tab with app details. All these references must be within the Teams environment.
+
+ ![Sample App 1](../../../../assets/images/faq/Sampleapp1.png)
+ ![Sample App 2](../../../../assets/images/faq/Sampleapp2.png)
+ * Increment your app version number in the manifest if you make any manifest changes to your submission.
-* App must not take users out of Teams for core user scenarios. Link targets in apps must not link to an external browser but should link to div elements contained within Teams e.g. inside Task Modules and tabs.
+* The app must not take users out of Teams for core user scenarios. Link targets in apps must not link to an external browser. Link targets must link to div elements contained within Teams, for example, task modules and tabs.
+* Using task modules or tabs is suggested to display information to users within Teams.
+* All core and non-core scenarios must be completed within the Teams environment except for:
+ * Privacy Policy
+ * Terms Of Use (TOU)
+ * Website link
+ * Sign-up process
+ * Personal apps enable users to share content from a personal app experience with other team members.
-### &#9989; Provide a clear and simple sign in/sign out and sign-up experience
+### &#9989; Provide a clear and simple sign-in, sign-out, and sign-up experience
-*See also* [Section 1100.5 ΓÇö Customer control](/legal/marketplace/certification-policies#11005-customer-control)
+See also [Section 1100.5 ΓÇö Customer control](/legal/marketplace/certification-policies#11005-customer-control)
-* If your app or add-in depends on external accounts or services, the sign in/sign out and sign-up experience must be apparent and reachable across all capabilities in your app.
+* If your app or add-in depends on external accounts or services, the sign-in, sign-out, and sign-up experience must be apparent and reachable across all capabilities in your app.
* If there is an explicit sign-in option provided to the user, there must be a corresponding sign-out option (even if the app is using [silent authentication](../../../../tabs/how-to/authentication/auth-silent-aad.md)). * The sign-out option must only sign the user out of your app's capability and not out of the Teams client.
-* At a minimum, the sign-out option must sign the user out of the same capabilities accessed with the sign-in option. For example, if the sign-in option includes both a messaging extension and tab, then the sign-out option must include both the messaging extension and tab.
+* At a minimum, the sign-out option must sign the user out of the same capabilities accessed with the sign-in option. For example, if the sign-in option includes both messaging extension and tab, then the sign-out option must include both messaging extension and tab.
* Make sure there is always a way to reverse the following (or similar) behaviors: * Sign-in => sign-out.
@@ -45,18 +62,18 @@ This article addresses common reasons submitted apps fail validation. While it's
* Connect an account/service => disconnect an account/service. * Authorize an account/service => deauthorize/deny an account/service. * Register an account/service => deregister/unsubscribe an account/service.
-* If your app requires an account or service, you must provide a way for the user to sign up or to create a sign-up request. An exception may be granted if your app requires a license to use. But such scenarios, a clear way forward for a new user sign up must be provided.
-* Make sure you provide clear-way-forward guidance to a new user on how to sign up to use your app services. If a ready sign-up link is not available, a clear way forward may be provided in the following areas
+* If your app requires an account or service, you must provide a way for the user to sign-up or create a sign-up request. An exception may be granted if your app requires a license to use. In such scenarios, provide clear instructions for a new user to sign-up.
+* Provide clear guidance on the way-forward to a new user on how to sign-up to use your app services. If a ready sign-up link is not available, provide precise guidance in the following areas:
> [!div class="checklist"] >
-> * within your app's description sections;
-> * in your app's welcome message;
-> * in your app's help message;
-> * in the window where you ask a user to sign in to your services;
+> * within your app's description section.
+> * in your app's welcome message.
+> * in your app's help message.
+> * in the window where you ask a user to sign-in to your services.
-* Apps that do not have an easy sign-up flow may also include a help tab or link to a web page where a new user can see detailed guidance on how to configure your app with Microsoft Teams. This is to ensure a new user is not blocked when trying your app for the first time.
-* Sign in/sign out functionality must work on mobile clients. Ensure you're using the [Microsoft Teams SDK](https://www.npmjs.com/package/@microsoft/teams-js) version 1.4.1 or later.
+* Apps without an easy sign-up flow must also include a help tab or link to a web page, where a new user can see detailed guidance on configuring your Teams app. Provide detailed information to ensure a new user is not blocked when trying your app for the first time.
+* Sign-in and sign-out functionality must work on mobile clients. Ensure to use the [Microsoft Teams SDK](https://www.npmjs.com/package/@microsoft/teams-js) version 1.4.1 or later.
For additional information on authentication see:
@@ -76,32 +93,32 @@ For additional information on authentication see:
### &#9989; Tab content must not have excessive chrome or layered navigation
-* Tabs should provide focused content and avoid needless UI elements. In general, this usually refers to unnecessary nested/layered navigation, an extraneous or irrelevant UI next to the content, or any links that take the user to unrelated content. For example, below is a tab view that omits navigation menus and only showcases the main content:
+* Tabs must provide focused content and avoid needless UI elements. This usually refers to unnecessary nested or layered navigation, an extraneous or irrelevant UI next to the content, or any links that take the user to unrelated content. For example, the following tab view omits navigation menus and only showcases the main content:
![SharePoint web view](../../../../assets/images/faq/web-sp.png) ![SharePoint tab view](../../../../assets/images/faq/tab-sp.png)
-* Tabs should be light in nature and not include complex navigation.
-* Channel tabs that have complex editing capabilities within the app should open the editor view in a multi-window rather than a tab.
+* Tabs must be light in nature and not include complex navigation.
+* Channel tabs that have complex editing capabilities within the app must open the editor view in a multi-window rather than a tab.
* Channel tabs must not provide an app bar with icons in the left rail that conflicts with the main Teams navigation. * Tabs must not present an app bar with icons in the left rail that conflict with the main Teams navigation.
-* Tabs that have complex editing capabilities within the app should open the editor view in a multi-window rather than in the tab.
+* Tabs that have complex editing capabilities within the app must open the editor view in a multi-window rather than in the tab.
* If there are multiple view options, consider having a tab config menu for the user to choose from. For example, instead of embedding a menu inside the tab, put the menu in the configuration page so the actual tab view is clean and focused.
-* Please include a *Help* tab as a static tab to advise users how to configure, sign up, and use your app.
+* Please include a *Help* tab as a static tab to advise users how to configure, sign-up, and use your app.
* Please include a *Settings* tab that is available from the app header. ![Wide idea configuration page](../../../../assets/images/faq/wideidea.png) ### &#9989; Tab configuration must happen in the configuration screen
-* The configuration screen should clearly explain the value of the experience and how to configure the tab.
-* The configuration process should always provide a way for users to continue not dead-end the user experience. For example, do not show an empty board after the user has configured the tab
-* The user sign-in process must be part of the configuration process and should complete in the Tab UI. After the user has completed configuration and loaded your tab, no further action should be required.
+* The configuration screen must clearly explain the value of the experience and how to configure the tab.
+* The configuration process must always provide a way for the users to continue and not end the user experience. For example, do not show an empty board after the user has configured the tab.
+* The user sign-in process must be a part of the configuration process. Ensure to complete it in the Tab UI. After the user has completed the configuration and loaded the tab, no further action is required.
* Don't show your entire webpage within the sign-in configuration pop-up window.
-* A user should always be able to finish the configuration experience, even if they canΓÇÖt immediately find the content theyΓÇÖre looking for.
-* The configuration experience should provide options for the user to find their content, pin a URL, or create new content if it doesnΓÇÖt exist.
+* A user must always be able to finish the configuration experience, even if they canΓÇÖt immediately find the content theyΓÇÖre looking for.
+* The configuration experience must provide options for the user to find their content, pin a URL, or create new content if it doesnΓÇÖt exist.
* The configuration experience must remain within the Teams context. The user shouldnΓÇÖt have to leave the configuration experience to create content and then return to Teams to pin it.
-* Use the available viewport area efficiently. Do not waste it on using huge logos inside the configuration pop up
+* Use the available viewport area efficiently. Do not waste it on using huge logos inside the configuration pop up.
![OneNote allows users to paste a OneNote link in case notes can not be found](../../../../assets/images/faq/tab-onenote-config.png)
@@ -109,9 +126,14 @@ For additional information on authentication see:
![SharePoint also allows user to directly paste a SharePoint link](../../../../assets/images/faq/tab-sp-config.png)
+### &#9989; Tabs in channel - Member access
+
+* A tab configured by a member in a channel scope must be accessible to the other members without having to seek permissions from the member who configured the tab.
+* The app must provide the permission management options upfront if the tab is for private or restricted use or requires any permissions from the member who configured the tab.
+ ### &#9989; Bots must always be responsive and fail gracefully
-Your bot should be responsive to any command and not dead-end the user. Here are some tips to help your bot intelligently respond to users:
+Your bot must be responsive to any command and not dead-end the user. Here are some tips to help your bot intelligently respond to users:
* **Use command lists**. Analyzing user input or predicting user intent is hard. Instead of letting users guess what your bot can do, provide a list of commands your bot understands.
@@ -121,23 +143,30 @@ Your bot should be responsive to any command and not dead-end the user. Here are
![Flow help command](../../../../assets/images/faq/flow-help.png)
-* **Include help content or guidance when your bot is lost**. When your bot can't understand the user input, it should suggest an alternative action. For example, *"I'm sorry, I don't understand. Type "help" for more information."* Don't respond with an error message or simply, *"I don't understand"*. Use this chance to teach your users.
+* **Include help content or guidance when your bot is lost**. When your bot cannot understand the user input, it must suggest an alternative action. For example, *"I'm sorry, I don't understand. Type "help" for more information."* Don't respond with an error message or simply, *"I don't understand"*.
+
+### &#9989; Help command response
+
+* Help Command must be precise and the app responses must be in an adaptive card format with an actionable content for at least six commands.
+* If an app has less than six commands, check if all the commands are present in the adaptive card.
+
+ ![Help command sample](../../../../assets/images/faq/helpcommand.png)
* **Use adaptive cards and task modules to make your bot response clear and actionable**
-[Adaptive cards with buttons invoking task modules](/task-modules-and-cards/task-modules/task-modules-bots) enhance the bot user experience. These cards and buttons are easier to use in a mobile device as opposed to your user typing the commands. Also bot responses should not be textual with long text. Bots must make use of Adaptive cards & task modules instead of conversational chat based user interface and lengthy text responses
+[Adaptive cards with buttons invoking task modules](/task-modules-and-cards/task-modules/task-modules-bots) enhance the bot user experience. These cards and buttons are easier to use in a mobile device as opposed to your user typing the commands. Also bot responses must not be textual with long text. Bots must make use of adaptive cards and task modules instead of conversational chat based user interface and lengthy text responses.
* **Think through all scopes**. Be sure that your bot provides appropriate responses when mentioned (`@*botname*`) in a channel and in personal conversations. If your bot does not provide meaningful context within the personal or teams scope, disable that scope via the manifest. (See the `bots` block in the [Microsoft Teams manifest schema reference](../../../../resources/schem#bots).)
-* **Include team, group chat, or 1:1 conversation**. Bot notifications should include a Team, a group chat, or a one-to-one conversation with relevant content for your audience.
+* **Include team, group chat, or 1:1 conversation**. Bot notifications must include a team, a group chat, or a one-to-one conversation with relevant content for your audience.
-* **Do not push sensitive data**. Bots must not push sensitive data to a Team, a group chat or a 1:1 conversation where there is an audience who should not be able to view that data
+* **Do not push sensitive data**. Bots must not push sensitive data to a team, a group chat, or a 1:1 conversation, where there is an audience who must not view that data.
* **Provide a welcome message**. Bot must provide an FRE welcome message that includes an interactive tutorial with carousel cards or "try it" buttons, to encourage engagement. ### &#9989; Personal bots must always send a welcome message on first launch
-A welcome messages is the best way to set the tone for your personal/chat bot. This is the first interaction a user has with the bot. A good welcome message can encourage the user to keep exploring the app. If the welcome or introductory message is confusing or unclear, users won't see the value of the app immediately and lose interests.
-Please see below section for Welcome message requirements.
+A welcome message is the best way to set the tone for your personal chat bot. This is the first interaction a user has with the bot. A good welcome message can encourage the user to keep exploring the app. If the welcome or introductory message is confusing or unclear, users won't see the value of the app immediately and lose interest.
+See the following section for welcome message requirements:
> [!Note] > A welcome message is optional for a channel bot.
@@ -146,14 +175,14 @@ Please see below section for Welcome message requirements.
* Include a value proposition with the welcome tour. * Provide way-forward guidance for using the app.
-* Include guidance on how to Sign up and configure your app
+* Include guidance on how to sign-up and configure your app.
* Present easy-to-read text and straightforward dialogue ΓÇö preferably a card with an actionable welcome tour button that loads a task module. * Keep it simple and usable with buttons and cards ΓÇö avoid long text, chatty dialogue. * Include adaptive cards and buttons to make the welcome message more usable. * Invoke the welcome message with one ping, not two or more simultaneous pings. * A welcome message must only be shown to the user who configured the app, preferably in a 1:1 personal chat. * Personal apps must always provide a welcome message to a user.
-* Never send a personal chat to every member in the team - this is considered spam.
+* Never send a personal chat to every member of the team; it is considered spam.
* Never send the welcome message more than once. Repeating the same welcome message over regular intervals is not allowed and is considered spamming. #### Avoid welcome message spamming
@@ -167,12 +196,12 @@ Notification-only bots must send a welcome message that includes a message conve
#### Welcome messages in the personal scope
-* **Make your message concise and informative**. Most likely, user experience with and knowledge of your app will vary. A user may have used your app on another platform or know nothing about your app. You want to tailor your message to all audiences and in a couple sentences explain what your bot does and the ways to interact with it. You should also explain the value of the app and how the users will benefit from using it.
+ * **Make your message concise and informative**. The user experience and the knowledge of your app will vary. A user may have used your app on another platform or know nothing about your app. You want to tailor your message to all audiences and in a couple sentences explain what your bot does and the ways to interact with it. You must also explain the value of the app and how the users will benefit from using it.
![Cafe and Dinning bot](../../../../assets/images/faq/cafe-bot.png)
-* **Make your message actionable**. Think about the first thing you want users to do after installing your app. Is there a cool command they should try? Is there another onboarding experience they should know about? Do they need to sign in? You can add actions on an adaptive card or provide specific examples such as *“Try asking….”*, *“This is what I can do…”*.
+* **Make your message actionable**. Think about the first thing you want users to do after installing your app. Is there a cool command they must try? Is there another onboarding experience they must know about? Do they need to sign-in? You can add actions on an adaptive card or provide specific examples such as *“Try asking….”*, *“This is what I can do…”*.
-#### Welcome messages in the team/channel scope
+#### Welcome messages in the team or channel scope
Things are a little bit different when the bot is first added to a channel. Normally, you shouldn't send a 1:1 message to everyone on the team, but the bot can send a welcome message in the channel.
@@ -186,22 +215,22 @@ Things are a little bit different when the bot is first added to a channel. Norm
### &#9989; Do not post sensitive data to an audience not intended to view the data
-Your Teams app must not post sensitive data such as credit card / financial payment instrument, Personal Identifiable Information (PIN), health, or contact tracing information to an audience not intended to view that data.
+Your Teams app must not post sensitive data such as credit card or financial payment instrument, Personal Identifiable Information (PIN), health, or contact tracing information to an audience not intended to view that data.
### &#9989; Do not transmit financial payment details or complete financial transactions via your Teams app
-* Your Teams app must not ask users to make a payment directly within Teams interface
+* Your Teams app must not ask users to make a payment directly within Teams interface.
* Apps may not transmit financial instrument details through the user on the app interface. Apps may only transmit links to secure payment services to users if this is disclosed in the app's Terms of Use, Privacy Policy, and any profile page or website for the app before a user agrees to use the app. ### &#9989; Clear warning before downloading any files or executable (`.exe`) into a userΓÇÖs environment Please warn users before your app downloads any files or executable (`.exe` )into the user's machine or environment.
-### &#9989; Messaging extensions should provide help text and be easy to read
+### &#9989; Messaging extensions must provide help text and be easy to read
-* The search-based messaging extension should provide help text on how to effectively search (e.g., show example input).
+* The search-based messaging extension must provide help text on how to effectively search (e.g., show example input).
* Task modules must include an icon and a short name that they are contained in or created from the app.
-* The message extension `@mention` executables should be clear, easy to understand, and easy to read.
+* The message extension `@mention` executables must be clear, easy to understand, and easy to read.
![Message extension](../../../../assets/images/faq/message-extension.png) ## M365 Publisher Attestation
platform https://docs.microsoft.com/en-us/microsoftteams/platform/tabs/how-to/using-teams-client-sdk https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/tabs/how-to/using-teams-client-sdk.md
@@ -1,22 +1,38 @@
Title: Using the Teams client SDK-
-description: How to use the Teams client SDK to add Teams-aware functionality to your custom tabs
+ Title: Building tabs and other hosted experiences with the JavaScript client SDK
++
+description: Overview of the Microsoft Teams JavaScript client SDK, which can help you build Teams app experiences hosted in an <iframe>.
keywords: teams tabs group channel configurable static SDK JavaScript personal
-# Using the Teams client SDK
+# Building tabs and other hosted experiences with the Microsoft Teams JavaScript client SDK
-The **Teams JavaScript client SDK** and **Teams JavaScript Library** are part of the [Microsoft Teams developer platform](/microsoftteams/platform/) and provide tools and processes to facilitate Teams application creation. The Teams client SDK is distributed as an npm package. The latest version can be found here:
-<https://www.npmjs.com/package/@microsoft/teams-js>. The Teams Library is located at <https://github.com/OfficeDev/microsoft-teams-library-js>.
+The Microsoft Teams JavaScript client SDK can help you create hosted experiences in Teams, which means displaying your app content in an iframe.
-The following table outlines the Teams Library functions typically used in tabs development:
+The SDK is helpful for developing apps with any of the following Teams capabilities:
-## Teams SDK public API
+* [Tabs](../../tabs/what-are-tabs.md)
+* [Task modules](../../task-modules-and-cards/what-are-task-modules.md)
+
+For example, the SDK can make your [tab react to theme changes](../../build-your-first-app/build-personal-tab.md#3-update-the-tab-theme) your users make in the Teams client.
+
+## Getting started
+
+Do one of the following depending on your development preferences:
+
+* [Install the SDK with npm or Yarn](https://docs.microsoft.com/javascript/api/overview/msteams-client?view=msteams-client-js-latest)
+* [Clone the SDK (GitHub)](https://github.com/OfficeDev/microsoft-teams-library-js)
+
+## Common SDK functions
+
+See the following tables to understand commonly used SDK functions. The [SDK reference documentation](https://docs.microsoft.com/javascript/api/@microsoft/teams-js/?view=msteams-client-js-latest) provides more comprehensive information.
+
+### Basic functions
| Function | Description | Documentation| | -- | -- | -- |
-| `microsoftTeams.initialize()` | Initializes the Teams library. This function must be called before any other SDK calls.|[function](https://docs.microsoft.com/javascript/api/@microsoft/teams-js/microsoftteams?view=msteams-client-js-latest#initialize-any-&preserve-view=true)|
+| `microsoftTeams.initialize()` | Initializes the SDK. This function must be called before any other SDK calls.|[function](https://docs.microsoft.com/javascript/api/@microsoft/teams-js/microsoftteams?view=msteams-client-js-latest#initialize-any-&preserve-view=true)|
|`microsoftTeams.getContext(callback: (context: Context)`| Gets the current state in which the page is running. The callback retrieves the **Context** object.|[function](https://docs.microsoft.com/javascript/api/@microsoft/teams-js/microsoftteams?view=msteams-client-js-latest#getcontext--context--context--void-&preserve-view=true)<br/>[context obj](https://docs.microsoft.com/javascript/api/@microsoft/teams-js/context?view=msteams-client-js-latest&preserve-view=true)| | `microsoftTeams.initializeWithContext({contentUrl: string, websiteUrl: string})` | Initializes the Teams library and sets the tab's [frame context](https://docs.microsoft.com/javascript/api/@microsoft/teams-js/microsoftteams.framecontext?view=msteams-client-js-latest&preserve-view=true) depending on the contentUrl and websiteUrl. This ensures the go-to-website/reload functionality operates on the correct URL.|[function](https://docs.microsoft.com/javascript/api/@microsoft/teams-js/microsoftteams?view=msteams-client-js-latest#initializewithframecontext-framecontext--void--string&preserve-view=true)| | `microsoftTeams.setFrameContext({contentUrl: string, websiteUrl: string})` | Sets the tab's [frame context](https://docs.microsoft.com/javascript/api/@microsoft/teams-js/microsoftteams.framecontext?view=msteams-client-js-latest&preserve-view=true) depending on the contentUrl and websiteUrl. This ensures the go-to-website/reload functionality operates on the correct URL.|[function](https://docs.microsoft.com/javascript/api/@microsoft/teams-js/microsoftteams?view=msteams-client-js-latest#setframecontext-framecontext-&preserve-view=true)|
@@ -28,7 +44,7 @@ The following table outlines the Teams Library functions typically used in tabs
|`microsoftTeams.executeDeepLink(deepLink: string, onComplete?: (status: boolean, reason?: string))`|Takes a required **deepLink** as input and navigates user to a URL or triggers a client actionΓÇösuch as opening or installingΓÇöan app *within Teams*.|[function](https://docs.microsoft.com/javascript/api/@microsoft/teams-js/microsoftteams?view=msteams-client-js-latest#executedeeplink-stringstatus--boolean--reasonstring--void-&preserve-view=true)| |`microsoftTeams.navigateToTab(tabInstance: TabInstance, onComplete?: (status: boolean, reason?: string))`|Takes the **TabInstance** object as input and navigates to a specified tab instance.|[function](https://docs.microsoft.com/javascript/api/@microsoft/teams-js/microsoftteams?view=msteams-client-js-latest#navigatetotab-tabinstance-&preserve-view=true)<br/>[tabInstance obj](https://docs.microsoft.com/javascript/api/@microsoft/teams-js/tabinstance?view=msteams-client-js-latest&preserve-view=true)|
-## Authentication namespace
+### Authentication namespace
| Function | Description | Documentation| | -- | -- | -- |
@@ -36,7 +52,7 @@ The following table outlines the Teams Library functions typically used in tabs
|`microsoftTeams.authentication.notifySuccess(result?: string, callbackUrl?: string)`|Notifies the frame that initiated the authentication request that the request was successful and closes the authentication window|[function](https://docs.microsoft.com/javascript/api/@microsoft/teams-js/authentication?view=msteams-client-js-latest&preserve-view=true)| |`microsoftTeams.authentication.notifyFailure(reason?: string, callbackUrl?: string)`|Notifies the frame that initiated the authentication request that the request failed and closes the authentication window.|[function](https://docs.microsoft.com/javascript/api/@microsoft/teams-js/authentication?view=msteams-client-js-latest&preserve-view=true)|
-## Settings namespace
+### Settings namespace
| Function | Description | Documentation| | -- | -- | -- |
@@ -46,7 +62,7 @@ The following table outlines the Teams Library functions typically used in tabs
|`microsoftTeams.settings.registerOnSaveHandler(handler: (evt: SaveEvent)`|The handler that is registered when the user selects the **Save** button. This handler should be used to create or update the underlying resource powering the content.|[function](https://docs.microsoft.com/javascript/api/@microsoft/teams-js/settings?view=msteams-client-js-latest&preserve-view=true)| |`microsoftTeams.settings.registerOnRemoveHandler(handler: (evt: RemoveEvent)`|The handler that is registered when the user selects the **Remove** button. This handler should be used to remove the underlying resource powering the content.|[function](https://docs.microsoft.com/javascript/api/@microsoft/teams-js/settings?view=msteams-client-js-latest&preserve-view=true)|
-## Tasks namespace
+### Task modules namespace
| Function | Description | Documentation| | -- | -- | -- |
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,19 +1,15 @@
Title: Get started with C#/.NET
-description: Get started building great apps in Microsoft Teams using C#/.NET
+ Title: Tutorial - Create your first app using C#
+description: Learn how to get started building Microsoft Teams apps with C#/.NET.
keywords: getting started .net c# csharp Last updated 11/09/2018
-# Get started on the Microsoft Teams platform with C#/.NET and App Studio
+# Create your first Microsoft Teams app using C#
-The [Microsoft Teams](/microsoftteams/) developer platform makes it easy for you to extend Teams and integrate your own applications and services seamlessly into the Teams workspace. These apps can then be distributed to your enterprise or for teams around the world.
-
-To extend Microsoft Teams, you will need to create a Microsoft Teams app. A Microsoft Teams app is a web application that you host. This app can then be integrated into the user's workspace in Teams.
-
-This tutorial helps you get started creating a Microsoft Teams app using C# on .NET. You can test the app by loading it into a Team that you have permissions for, or into a test tenant created using the Office Developer Program.
+This tutorial helps you get started creating a Microsoft Teams app using C# on .NET.
[!include [prepare your environment](~/includes/prepare-environment.md)]
platform https://docs.microsoft.com/en-us/microsoftteams/platform/tutorials/get-started-nodejs-app-studio https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/tutorials/get-started-nodejs-app-studio.md
@@ -1,16 +1,14 @@
Title: Get started with App Studio and Node.js
-description: Get started building great apps in Microsoft Teams using Node.js and App Studio
+ Title: Tutorial - Create your first app using Node.js
+description: Learn how to get started building Microsoft Teams apps with Node.js.
keywords: getting started node.js nodejs App Studio
-# Get started on the Microsoft Teams platform with Node.js and App Studio
+# Create your first Microsoft Teams app using Node.js
-The [Microsoft Teams](/microsoftteams/) developer platform makes it easy for you to extend Teams and integrate your own applications and services seamlessly into the Teams workspace. These apps can then be distributed to your enterprise or for teams around the world.
-
-To extend Microsoft Teams, you need to create a Microsoft Teams app. A Microsoft Teams app is a web application that you host. This app can then be integrated into the user's workspace in Teams.
+This tutorial helps you get started creating a Microsoft Teams app using Node.js.
[!include [prepare your environment](~/includes/prepare-environment.md)]
platform https://docs.microsoft.com/en-us/microsoftteams/platform/tutorials/get-started-yeoman https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/tutorials/get-started-yeoman.md
@@ -1,27 +1,27 @@
Title: Get started with the Yeoman generator for Microsoft Teams
-description: Get started building great apps with the Yeoman generator for Microsoft Teams
+ Title: Tutorial - Create your first app using the Yeoman generator
+description: Learn how to get started building Microsoft Teams apps with the Yeoman generator.
keywords: getting started node.js nodejs yeoman
-# Build your First Microsoft Teams App
+# Create 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)
+>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 assumes that you have [enabled side-loading of Microsoft Teams apps](~/concepts/build-and-test/prepare-your-o365-tenant.md).
+In this tutorial we will walk through creating your very first Microsoft Teams app using the Microsoft Teams Yeoman generator. It assumes that you 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 Teams Generator.
+You need to install the following on your machine before starting to use the Yeoman generator.
-### Install Node
+### Install Node.js
-You need to have NodeJS installed on your machine. You should use the latest [LTS version](https://nodejs.org).
+You need to have Node.js installed on your machine. You should use the latest [LTS version](https://nodejs.org).
### Install a code editor
@@ -37,17 +37,15 @@ Open up a command prompt and type the following:
npm install yo gulp-cli --global ```
-## Install the Microsoft Teams Apps generator - Yo Teams
+## Install the generator
-The Yeoman generator for Microsoft Teams apps are installed with the following command:
+Install the Teams Yeoman generator with the following command:
```bash npm install generator-teams --global ```
-#### Install preview versions
-
-If you want to install preview versions of the Teams generator with this command:
+To install preview versions of the generator, run this command:
```bash npm install generator-teams@preview --global
@@ -55,7 +53,9 @@ npm install generator-teams@preview --global
## Generate your project
-Open up a command prompt and create a new directory where you want to create your project and in that directory type the command `yo teams`. This will start the Teams Apps generator and you will be asked a set of questions.
+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`.
+
+This starts the generator, which prompts you with a set of questions.
![yo teams](~/assets/yeoman-images/teams-first-app-1.png)
@@ -129,4 +129,4 @@ Choose your tab and follow the instructions to add it. Notice that you have a cu
![running tab in teams](~/assets/yeoman-images/teams-first-app-6.png)
-**Congrats! You built and deployed your first Microsoft Teams App**
+**Congrats! You built and deployed your first Microsoft Teams app**