Updates from: 02/11/2021 04:23:15
Service Microsoft Docs article Related commit history on GitHub Change details
platform https://docs.microsoft.com/en-us/microsoftteams/platform/concepts/device-capabilities/device-capabilities-overview https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/concepts/device-capabilities/device-capabilities-overview.md
@@ -0,0 +1,35 @@
+
+ Title: Overview of device capabilities
+description: Overview of native device capabilities.
+keywords: camera image media microphone capabilities native device permissions
+++
+# Device capabilities
+
+Microsoft Teams platform is continuously enhancing developer capabilities aligning with built-in first-party experiences. The enhanced Teams platform allows partners to integrate device capabilities, such as camera, photo gallery, microphone, and location, with their web apps. This integration reduces the barrier to app development, speeds-up development-cycle, and creates new scenarios or use-cases for the developer community.
+
+## Native device capabilities
+
+A mobile or desktop device has built-in devices, such as a camera and microphone, called capabilities. You can access the following device capabilities on mobile or desktop through dedicated APIs available in [Microsoft Teams JavaScript client SDK](/javascript/api/overview/msteams-client?view=msteams-client-js-latest&preserve-view=true):
+* Media capabilities, such as
+ * Camera
+ * Microphone
+ * Gallery
+* Location
+
+After getting access to the device capabilities, you can integrate them with Teams platform to enhance the collaborative experience.
+
+## Request device permissions
+
+Use the tools present in [Microsoft Teams JavaScript client SDK](/javascript/api/overview/msteams-client?view=msteams-client-js-latest&preserve-view=true) to request the required [permissions](native-device-permissions.md) for accessing the native device capabilities. While access to these capabilities is standard in modern web browsers, you must inform Teams about the capabilities that you are using by updating your app manifest. This update allows you to request permissions while your app runs on Teams mobile or desktop clients.
+
+ ## Integrate device capabilities
+
+After getting access to device capabilities,use **Teams media capability APIs** to [integrate the capabilities](mobile-camera-image-permissions.md) with Teams platform to enhance the user experience. These integrated capabilities allow your app to:
+
+* Capture and share images
+* Record audio through microphone
+* Share the location information
++
platform https://docs.microsoft.com/en-us/microsoftteams/platform/concepts/device-capabilities/mobile-camera-image-permissions https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/concepts/device-capabilities/mobile-camera-image-permissions.md
@@ -1,34 +1,32 @@
Title: Camera and image capabilities in Teams
-description: How to use Teams Javascript client SDK to enable native camera and image capabilities
-keywords: camera image capabilities native device permissions
+ Title: Integrate media capabilities
+description: How to use Teams JavaScript client SDK to enable media capabilities
+keywords: camera image microphone capabilities native device permissions media
-# Camera and image capabilities in Teams
+# Integrate media capabilities
->[!IMPORTANT]
->
-> * At present, Teams support for camera and image capabilities is only available for mobile clients.
->* The `selectMedia`, `getMedia`, and `viewImages` APIs can be invoked from multiple Teams surfaces such as task modules, tabs, and personal apps. For more details, _see_ [Entry points for Teams apps](../extensibility-points.md)
+This document guides you on how to integrate media capabilities. This integration combines the native device capabilities, such as the **camera** and **microphone** with the Teams platform.
-You can use the [Microsoft Teams JavaScript client SDK](/javascript/api/overview/msteams-client?view=msteams-client-js-latest&preserve-view=true), to easily integrate camera and image capabilities within your Microsoft Teams mobile app. The SDK provides the tools necessary for your app to access a userΓÇÖs [device permissions](native-device-permissions.md?tabs=desktop#device-permissions) and build a richer experience.
+You can use [Microsoft Teams JavaScript client SDK](/javascript/api/overview/msteams-client?view=msteams-client-js-latest&preserve-view=true), that provides the tools necessary for your app to access a userΓÇÖs [device permissions](native-device-permissions.md). Use suitable **media capability APIs** to integrate the native device capabilities, such as the **camera** and **microphone** with the Teams platform within your Microsoft Teams mobile app, and build a richer experience.
-The [selectMedia](/javascript/api/@microsoft/teams-js/media?view=msteams-client-js-latest#selectMedia_MediaInputs___error__SdkError__attachments__Media_______void_&preserve-view=true), [getMedia](/javascript/api/@microsoft/teams-js/_media?view=msteams-client-js-latest#getMedia__error__SdkError__blob__Blob_____void_&preserve-view=true), and [viewImages](/javascript/api/@microsoft/teams-js/media?view=msteams-client-js-latest#viewImages_ImageUri_____error___SdkError_____void_&preserve-view=true) APIs enable you to use native camera/image capabilities as follows:
+## Advantage of integrating media capabilities
-* Use native **camera control** to allow users to **capture and attach images** on the go.
-* Use native **gallery support** to allow users to **select device images** as attachments.
-* Use native **image viewer control** to **preview multiple images** at one time.
-* Support **large image transfer** (up to 50 MB) via the SDK bridge
-* Support **advanced image capabilities** allowing users to preview and edit images:
- * Scan document, whiteboard, business cards, etc., through the camera.
- * Crop and rotate the images.
- * Add text, ink, or freehand annotation to the image.
+The main advantage of integrating device capabilities in your Teams apps is it leverages native Teams controls to provide a rich and immersive experience to your users.
+To integrate media capabilities you must update the app manifest file and call the media capability APIs.
+
+For effective integration, you must have a good understanding of [code snippets](#code-snippets) for calling the respective APIs, which allow you to use native media capabilities.
+
+It is important to familiarize yourself with the [API response errors](#error-handling) to handle the errors in your Teams app.
-## Get started
+> [!NOTE]
+> Currently, Microsoft Teams support for media capabilities is only available for mobile clients.
-Update your Teams app [manifest.json](../../resources/schem#devicepermissions) file by adding the `devicePermissions` property and specifying `media`. This allows your app to ask for requisite permissions from end-users before they use the camera to capture the image or open the gallery to select an image to submit as an attachment.
+## Update manifest
+
+Update your Teams app [manifest.json](../../resources/schem#devicepermissions) file by adding the `devicePermissions` property and specifying `media`. It allows your app to ask for requisite permissions from users before they start using the **camera** to capture the image, open the gallery to select an image to submit as an attachment, or use the **microphone** to record the conversation.
``` json "devicePermissions": [
@@ -37,44 +35,64 @@ Update your Teams app [manifest.json](../../resources/schem#
``` > [!NOTE]
-> The _Request Permissions_ prompt is automatically displayed when a relevant Teams API is initiated. For more details, *see* [Request device permissions](native-device-permissions.md).
+> The **Request Permissions** prompt is automatically displayed when a relevant Teams API is initiated. For more information, see [Request device permissions](native-device-permissions.md).
+
+## Media capability APIs
+
+The [selectMedia](/javascript/api/@microsoft/teams-js/media?view=msteams-client-js-latest#selectMedia_MediaInputs___error__SdkError__attachments__Media_______void_&preserve-view=true), [getMedia](/javascript/api/@microsoft/teams-js/_media?view=msteams-client-js-latest#getMedia__error__SdkError__blob__Blob_____void_&preserve-view=true), and [viewImages](/javascript/api/@microsoft/teams-js/media?view=msteams-client-js-latest#viewImages_ImageUri_____error___SdkError_____void_&preserve-view=true) APIs enable you to use native media capabilities as follows:
-## Using camera and image capability APIs
+* Use the native **microphone** to allow users to **record audio** (record 10 minutes of conversation) from the device.
+* Use native **camera control** to allow users to **capture and attach images** on the go.
+* Use native **gallery support** to allow users to **select device images** as attachments.
+* Use native **image viewer control** to **preview multiple images** at one time.
+* Support **large image transfer** (from 1 MB to 50 MB) through the SDK bridge.
+* Support **advanced image capabilities** allowing users to preview and edit images:
+ * Scan document, whiteboard, and business cards through the camera.
+
+> [!IMPORTANT]
+>* The `selectMedia`, `getMedia`, and `viewImages` APIs can be invoked from multiple Teams surfaces such as task modules, tabs, and personal apps. For more details, see [Entry points for Teams apps](../extensibility-points.md).
+>* `selectMedia` API has been extended to support mic and audio properties.
-You can use the following set of APIs to enable camera and image device capabilities:
+You must use the following set of APIs to enable your device's media capabilities:
| API | Description | | | |
-| [**selectMedia**](/javascript/api/@microsoft/teams-js/media?view=msteams-client-js-latest&branch=master#selectMedia_MediaInputs___error__SdkError__attachments__Media_______void_&preserve-view=true)| This API allows users to **capture or select media from a native device** and return to the web-app. Users may choose to edit, crop, rotate, annotate, or draw over images before submission. In response to **selectMedia**, the web-app will receive media ids of selected images and may receive a thumbnail of the selected media. |
-| [**getMedia**](/javascript/api/@microsoft/teams-js/_media?view=msteams-client-js-latest&branch=master#getMedia__error__SdkError__blob__Blob_____void_&preserve-view=true)| This API retrieves the media in chunks irrespective of size. These chunks are assembled and sent back to the web app as a file/blob. With this API an image is broken into smaller chunks to facilitate large image transfer. |
-| [**viewImages**](/javascript/api/@microsoft/teams-js/media?view=msteams-client-js-latest#viewImages_ImageUri_____error___SdkError_____void_&preserve-view=true)| This API enables the user to view images full-screen mode as a scrollable list.|
+| [**selectMedia**](/javascript/api/@microsoft/teams-js/media?view=msteams-client-js-latest#selectMedia_MediaInputs___error__SdkError__attachments__Media_______void_&preserve-view=true) (**Camera)**| This API allows users to **capture or select media from the device camera** and return it to the web-app. The users can edit, crop, rotate, annotate, or draw over images before submission. In response to **selectMedia**, the web-app receives the media IDs of selected images and a thumbnail of the selected media. This API can be further configured through the [ImageProps](/javascript/api/@microsoft/teams-js/imageprops?view=msteams-client-js-latest&preserve-view=true) configuration. |
+| [**selectMedia**](/javascript/api/@microsoft/teams-js/media?view=msteams-client-js-latest#selectMedia_MediaInputs___error__SdkError__attachments__Media_______void_&preserve-view=true) (**Microphone**)| Set the [mediaType](/javascript/api/@microsoft/teams-js/mediatype?view=msteams-client-js-latest&preserve-view=true) to `4` in **selectMedia** API for accessing microphone capability. This API also allows users to record audio from the device microphone and return recorded clips to the web-app. The users can pause, re-record, and play recording preview before submission. In response to **selectMedia**, the web-app receives media IDs of the selected audio recording. <br/> Use `maxDuration`, if you require to configure a duration in minutes for recording the conversation. The current duration for recording is 10 minutes, after which the recording terminates. |
+| [**getMedia**](/javascript/api/@microsoft/teams-js/_media?view=msteams-client-js-latest#getMedia__error__SdkError__blob__Blob_____void_&preserve-view=true)| This API retrieves the media captured by **selectMedia** API in chunks, irrespective of the media size. These chunks are assembled and sent back to the web app as a file or blob. Breaking of media into smaller chunks facilitates large file transfer. |
+| [**viewImages**](/javascript/api/@microsoft/teams-js/media?view=msteams-client-js-latest#viewImages_ImageUri_____error___SdkError_____void_&preserve-view=true)| This API enables the user to view images in full-screen mode as a scrollable list.|
++
+**Web app experience for selectMedia API for image capability**
+![device camera and image experience in Teams](../../assets/images/tabs/image-capability.png)
-**Web app experience for selectMedia API**
-![device camera and image experience in Teams](../../assets/images/tabs/image-capability-screenshot.jpg)
+**Web app experience for selectMedia API for microphone capability**
+![web app experience for microphone capability](../../assets/images/tabs/microphone-capability.png)
## Error handling
-You should understand the API response error codes and handle them appropriately. Below is a list of error codes that may be returned by the platform:
+You must ensure to handle these errors appropriately in your Teams app. The following table lists the error codes and the conditions under which the errors are generated:
-|Error code | Error Name | Condition|
-| | | |
-| **100** | NOT_SUPPORTED_ON_PLATFORM | API not supported in the current platform.|
-| **404** | FILE_NOT_FOUND | The file specified was not found on the given location.|
-| **500** | INTERNAL_ERROR | Internal error encountered while performing the required operation.|
-| **1000** | PERMISSION_DENIED |Permissions denied by the user.|
+
+|Error code | Error name | Condition|
+| | | -- |
+| **100** | NOT_SUPPORTED_ON_PLATFORM | API is not supported on the current platform.|
+| **404** | FILE_NOT_FOUND | File specified is not found in the given location.|
+| **500** | INTERNAL_ERROR | Internal error is encountered while performing the required operation.|
+| **1000** | PERMISSION_DENIED |Permission is denied by the user.|
| **2000** |NETWORK_ERROR | Network issue.|
-| **3000** | NO_HW_SUPPORT | Underlying hardware doesn't support the capability.|
-| **4000**| INVALID_ARGUMENTS | One or more arguments is invalid.|
+| **3000** | NO_HW_SUPPORT | Underlying hardware does not support the capability.|
+| **4000**| INVALID_ARGUMENTS | One or more arguments are invalid.|
| **5000** | UNAUTHORIZED_USER_OPERATION | User is not authorized to complete this operation.|
-| **6000** |INSUFFICIENT_RESOURCES | The operation couldn't be completed due to insufficient resources.|
-|**7000** | THROTTLE | The platform throttled the request because the API was invoked too frequently.|
-| **8000** | USER_ABORT |User aborted the operation.|
-| **9000**| OLD_PLATFORM | The platform code is outdated and doesn't implement this API.|
-| **10000**| SIZE_EXCEEDED | The return value is too big and has exceeded the platform size boundaries.|
+| **6000** |INSUFFICIENT_RESOURCES | Operation could not be completed due to insufficient resources.|
+|**7000** | THROTTLE | Platform throttled the request as the API was invoked frequently.|
+| **8000** | USER_ABORT |User aborts the operation.|
+| **9000**| OLD_PLATFORM | Platform code is outdated and does not implement this API.|
+| **10000**| SIZE_EXCEEDED | Return value is too big and has exceeded the platform size boundaries.|
-## Sample code snippets
+## Code snippets
-**Calling `selectMedia` API**
+**Calling `selectMedia` API** for capturing images using camera:
```javascript let imageProp: microsoftTeams.media.ImageProps = {
@@ -105,7 +123,7 @@ microsoftTeams.media.selectMedia(mediaInput, (error: microsoftTeams.SdkError, at
}); ```
-**Calling `getMedia` API**
+**Calling `getMedia` API** to retrieve large media in chunks:
```javascript let media: microsoftTeams.media.Media = attachments[0]
@@ -125,11 +143,12 @@ media.getMedia((error: microsoftTeams.SdkError, blob: Blob) => {
}); ```
-**Calling `viewImages` API by ID**
+**Calling `viewImages` API by ID returned by `selectMedia` API**:
```javascript
-view images by id:
- assumption: attachmentArray = select Media API Outputlet uriList = [];
+// View images by id:
+// Assumption: attachmentArray = select Media API Output
+let uriList = [];
if (attachmentArray && attachmentArray.length > 0) { for (let i = 0; i < attachmentArray.length; i++) { let file = attachmentArray[i];
@@ -159,18 +178,19 @@ if (uriList.length > 0) {
} ```
-**Calling viewImages API by URL**
+**Calling `viewImages` API by URL**:
```javascript
-View Images by URL:
- // Assumption 2 urls, url1 and url2let uriList = [];
- if (URL1 != null && URL1.length > 0) {
- let imageUri = {
- value: URL1,
- type: 2,
- }
- uriList.push(imageUri);
+// View Images by URL:
+// Assumption 2 urls, url1 and url2
+let uriList = [];
+if (URL1 != null && URL1.length > 0) {
+ let imageUri = {
+ value: URL1,
+ type: 2,
}
+ uriList.push(imageUri);
+}
if (URL2 != null && URL2.length > 0) { let imageUri = { value: URL2,
@@ -191,5 +211,39 @@ if (uriList.length > 0) {
} else { output("Url list is empty"); }
-}
+```
+
+**Calling `selectMedia` and `getMedia` APIs for recording audio through microphone**:
+
+```javascript
+let mediaInput: microsoftTeams.media.MediaInputs = {
+ mediaType: microsoftTeams.media.MediaType.Audio,
+ maxMediaCount: 1,
+};
+microsoftTeams.media.selectMedia(mediaInput, (error: microsoftTeams.SdkError, attachments: microsoftTeams.media.Media[]) => {
+ if (error) {
+ if (error.message) {
+ alert(" ErrorCode: " + error.errorCode + error.message);
+ } else {
+ alert(" ErrorCode: " + error.errorCode);
+ }
+ }
+ // If you want to directly use the audio file (for smaller file sizes (~4MB)) if (attachments) {
+ let audioResult = attachments[0];
+ var videoElement = document.createElement("video");
+ videoElement.setAttribute("src", ("data:" + y.mimeType + ";base64," + y.preview));
+ //To use the audio file via get Media API for bigger audio file sizes greater than 4MB audioResult.getMedia((error: microsoftTeams.SdkError, blob: Blob) => {
+ if (blob) {
+ if (blob.type.includes("video")) {
+ videoElement.setAttribute("src", URL.createObjectURL(blob));
+ }
+ }
+ if (error) {
+ if (error.message) {
+ alert(" ErrorCode: " + error.errorCode + error.message);
+ } else {
+ alert(" ErrorCode: " + error.errorCode);
+ }
+ }
+});
```
platform https://docs.microsoft.com/en-us/microsoftteams/platform/concepts/device-capabilities/native-device-permissions https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/concepts/device-capabilities/native-device-permissions.md
@@ -1,65 +1,62 @@
Title: Request device permissions for your tab
+ Title: Request device permissions for your Microsoft Teams app
+keywords: teams apps capabilities permissions
description: How to update your app manifest in order to request access to native features that usually require user consent
-keywords: teams tabs development
-# Request device permissions for your Microsoft Teams tab
+# Request device permissions for your Microsoft Teams app
-You might want to enrich your tab with features that require access to native device functionality like:
-
-> [!div class="checklist"]
->
-> * Camera
-> * Microphone
-> * Location
-> * Notifications
+You can enrich your Teams app with native device capabilities, such as camera, microphone, and location. This document guides you on how to request user consent and access the native device permissions.
> [!NOTE]
-> To integrate camera and image capabilities within your Microsoft Teams mobile app, see [Camera and image capabilities in Teams.](../../concepts/device-capabilities/mobile-camera-image-permissions.md)
+> To integrate media capabilities within your Microsoft Teams mobile app, see [Integrate media capabilities](mobile-camera-image-permissions.md).
-> [!IMPORTANT]
->
-> * At present, Teams mobile client only supports access to `camera`, `gallery`, `mic`, and `location` through native device capabilities and is available on all app constructs including tabs. </br>
-> * Support for `camera`, `gallery`, and `mic` is enabled through [**selectMedia API**](/javascript/api/@microsoft/teams-js/media?view=msteams-client-js-latest#selectMedia_MediaInputs___error__SdkError__attachments__Media_______void_&preserve-view=true). For single image capture you may use [**captureImage API**](/javascript/api/@microsoft/teams-js/microsoftteams?view=msteams-client-js-latest#captureimage--error--sdkerror--files--file-void-&preserve-view=true).
-> * Support for `location` is enabled through [**getLocation API**](/javascript/api/@microsoft/teams-js/location?view=msteams-client-js-latest#getLocation_LocationProps___error__SdkError__location__Location_____void_&preserve-view=true). It's recommended you use this API as [**geolocation API**](../../resources/schem#devicepermissions) is currently not fully supported on all desktop clients.
+## Native device permissions
+
+You must request the device permissions to access native device capabilities. The device permissions work similarly for all app constructs, such as tabs, task modules, or messaging extensions. The user must go to the permissions page in Teams settings to manage device permissions.
+By accessing the device capabilities, you can build richer experiences on the Teams platform, such as:
+* Capture and view images.
+* Record and share short videos.
+* Record audio memos and save them for later use.
+* Use the location information of the user to display relevant information.
-## Device permissions
+## Access device permissions
-Accessing a userΓÇÖs device permissions allows you to build much richer experiences, for example:
+The [Microsoft Teams JavaScript client SDK](/javascript/api/overview/msteams-client?view=msteams-client-js-latest&preserve-view=true) provides the tools necessary for your Teams mobile app to access the userΓÇÖs [device permissions](#manage-permissions) and build a richer experience.
-* Record and share short videos
-* Record short audio memos and save them for later
-* Use user location information to display relevant information
+While access to these features is standard in modern web browsers, you must inform Teams about the features you use by updating your app manifest. This update allows you to ask for permissions while your app runs on the Teams desktop client.
-While access to these features is standard in most modern web browsers, you need to let Teams know which features youΓÇÖd like to use by updating your app manifest. This will allow you to ask for permissions, the same way you would in a browser, while your app is running on the Teams desktop client.
+> [!NOTE]
+> Currently, Microsoft Teams support for media capabilities is only available for mobile clients.
## Manage permissions
+A user can manage device permissions in Teams settings by selecting **Allow** or **Deny** permissions to specific apps.
+
# [Desktop](#tab/desktop)
-1. Open Teams.
-1. In the upper right corner of the window, select your profile icon.
-1. Select **Settings** -> **Permissions** from the drop-down menu.
-1. Choose your desired settings.
+1. Open your Teams app.
+1. Select your profile icon in the upper right corner of the window.
+1. Select **Settings** > **Permissions** from the drop-down menu.
+1. Select your desired settings.
-![Device permissions desktop settings screen](../../assets/images/tabs/device-permissions.png)
+ ![Device permissions desktop settings screen](../../assets/images/tabs/device-permissions.png)
# [Mobile](#tab/mobile) 1. Open Teams.
-1. Go to **Settings** -> **App Permissions**.
-1. Select the app you need to choose settings for.
-1. Choose your desired settings.
+1. Go to **Settings** > **App Permissions**.
+1. Select the app for which you need to choose the settings.
+1. Select your desired settings.
-![Device permissions mobile settings screen](../../assets/images/tabs/MobilePermissions.png)
+ ![Device permissions mobile settings screen](../../assets/images/tabs/MobilePermissions.png)
-## Properties
+## Specify permissions
-Update your app's `manifest.json` by adding `devicePermissions` and specifying which of the five properties youΓÇÖd like to use in your application:
+Update your app's `manifest.json` by adding `devicePermissions` and specifying which of the five properties that you use in your application:
``` json "devicePermissions": [
@@ -70,23 +67,20 @@ Update your app's `manifest.json` by adding `devicePermissions` and specifying w
"openExternal" ], ```
-> [!Note]
->
-> Media is also used for camera permissions on mobile.
-Each property will allow you to prompt the user to ask for their consent:
+Each property allows you to prompt the user to ask for their consent:
| Property | Description | | | |
-| media | permission to use the camera, microphone, speakers, and access media gallery |
-| geolocation | permission to return the user's location |
-| notifications | permission to send the user notifications |
-| midi | permission to send and receive midi information from a digital musical instrument |
-| openExternal | permission to open links in external applications |
+| media | Permission to use the camera, microphone, speakers, and access media gallery. |
+| geolocation | Permission to return the user's location. |
+| notifications | Permission to send the user notifications. |
+| midi | Permission to send and receive Musical Instrument Digital Interface (MIDI) information from a digital musical instrument. |
+| openExternal | Permission to open links in external applications. |
-## Checking permissions from your tab
+## Check permissions from your app
-Once youΓÇÖve added `devicePermissions` to your app manifest, you can check permissions using the HTML5 ΓÇ£permissionsΓÇ¥ API without causing a prompt.
+After adding `devicePermissions` to your app manifest, check permissions using the **HTML5 permissions API** without causing a prompt:
``` Javascript // Different query options:
@@ -106,69 +100,85 @@ navigator.permissions.query({name:'geolocation'}).then(function(result) {
}); ```
-## Prompting the user
+## Use Teams APIs to get device permissions
-To show a prompt to get consent to access device permissions you need to leverage the appropriate HTML5 or Teams API.
+Leverage appropriate HTML5 or Teams API, to display a prompt for getting consent to access device permissions.
-For example, to prompt the user to access their location you need to call `getCurrentPosition`:
+> [!IMPORTANT]
+> * Support for `camera`, `gallery`, and `microphone` is enabled through [**selectMedia API**](/javascript/api/@microsoft/teams-js/media?view=msteams-client-js-latest#selectMedia_MediaInputs___error__SdkError__attachments__Media_______void_&preserve-view=true). Use [**captureImage API**](/javascript/api/@microsoft/teams-js/microsoftteams?view=msteams-client-js-latest#captureimage--error--sdkerror--files--file-void-&preserve-view=true) for a single image capture.
+> * Support for `location` is enabled through [**getLocation API**](/javascript/api/@microsoft/teams-js/location?view=msteams-client-js-latest#getLocation_LocationProps___error__SdkError__location__Location_____void_&preserve-view=true). You must use this `getLocation API` for location, as HTML5 geolocation API is currently not fully supported on Teams desktop client.
-```Javascript
-navigator.geolocation.getCurrentPosition(function (position) { /*... */ });
-```
+For example:
+ * To prompt the user to access their location you must call `getCurrentPosition()`:
-To use the camera on desktop or web, Teams will show a permission prompt when you call `getUserMedia`:
+ ```Javascript
+ navigator.geolocation.getCurrentPosition (function (position) { /*... */ });
+ ```
-```Javascript
-navigator.mediaDevices.getUserMedia({ audio: true, video: true });
-```
+ * To prompt the user to access their camera on desktop or web you must call `getUserMedia()`:
-To capture the image on mobile, Teams mobile will ask for permission when you call `captureImage()`:
+ ```Javascript
+ navigator.mediaDevices.getUserMedia({ audio: true, video: true });
+ ```
-```Javascript
-microsoftTeams.media.captureImage((error: microsoftTeams.SdkError, files: microsoftTeams.media.File[]) => {
- /* ... */
-});
-```
+ * To capture the image on mobile, Teams mobile asks for permission when you call `captureImage()`:
-Notifications will prompt the user when you call `requestPermission`:
+ ```Javascript
+ microsoftTeams.media.captureImage((error: microsoftTeams.SdkError, files: microsoftTeams.media.File[]) => {
+ /* ... */
+ });
+ ```
-```Javascript
-Notification.requestPermission(function(result) { /* ... */ });
-```
+ * Notifications will prompt the user when you call `requestPermission()`:
-To use camera or access photo gallery, Teams mobile will ask permission when you call `selectMedia()`:
+ ```Javascript
+ Notification.requestPermission(function(result) { /* ... */ });
+ ```
-```JavaScript
-microsoftTeams.media.selectMedia({ maxMediaCount: 10, mediaType: microsoftTeams.media.MediaType.Image }, (error: microsoftTeams.SdkError, attachments: microsoftTeams.media.Media[]) => {
- /* ... */
-});
-```
-To use mic, Teams mobile will ask permission when you call `selectMedia()`:
-```JavaScript
-microsoftTeams.media.selectMedia({ maxMediaCount: 1, mediaType: microsoftTeams.media.MediaType.Audio }, (error: microsoftTeams.SdkError, attachments: microsoftTeams.media.Media[]) => {
- /* ... */
-});
-```
-To prompt user to share location on map interface, Teams mobile will ask permission when you call `getLocation()`:
+* To use the camera or access photo gallery, Teams mobile asks permission when you call `selectMedia()`:
-```JavaScript
-microsoftTeams.location.getLocation({ allowChooseLocation: true, showMap: true }, (error: microsoftTeams.SdkError, location: microsoftTeams.location.Location) => {
- /* ... *
-/});
-```
+ ```JavaScript
+ microsoftTeams.media.selectMedia({ maxMediaCount: 10, mediaType: microsoftTeams.media.MediaType.Image }, (error: microsoftTeams.SdkError, attachments: microsoftTeams.media.Media[]) => {
+ /* ... */
+ );
+ ```
+
+* To use the microphone, Teams mobile asks permission when you call `selectMedia()`:
+
+ ```JavaScript
+ microsoftTeams.media.selectMedia({ maxMediaCount: 1, mediaType: microsoftTeams.media.MediaType.Audio }, (error: microsoftTeams.SdkError, attachments: microsoftTeams.media.Media[]) => {
+ /* ... */
+ });
+ ```
+* To prompt the user to share location on the map interface, Teams mobile asks permission when you call `getLocation()`:
+
+ ```JavaScript
+ microsoftTeams.location.getLocation({ allowChooseLocation: true, showMap: true }, (error: microsoftTeams.SdkError, location: microsoftTeams.location.Location) => {
+ /* ... *
+ /});
+ ```
# [Desktop](#tab/desktop)
-![Tabs desktop device permissions prompt](~/assets/images/tabs/device-permissions-prompt.png)
+ ![Tabs desktop device permissions prompt](~/assets/images/tabs/device-permissions-prompt.png)
# [Mobile](#tab/mobile)
-![Tabs mobile device permissions prompt](../../assets/images/tabs/MobileLocationPermission.png)
+ ![Tabs mobile device permissions prompt](../../assets/images/tabs/MobileLocationPermission.png)
+* * *
## Permission behavior across login sessions
-Native device permissions are stored for every login session. It means that if you log into another instance of Teams (ex: on another computer), your device permissions from your previous sessions will not be available. Instead, you will need to re-consent to device permissions for the new login session. It also means, if you log out of Teams (or switch tenants inside of Teams), your device permissions will be deleted for that previous login session. Please keep this in mind when developing native device permissions: the native capabilities you consent to are only for your _current_ login session.
+Device permissions are stored for every login session. It means that if you sign in to another instance of Teams, for example, on another computer, your device permissions from your previous sessions are not available. Therefore, you must re-consent to device permissions for the new session. It also means, if you sign out of Teams or switch tenants in Teams, your device permissions are deleted from the previous login session.
+
+> [!NOTE]
+> When you consent to the native device permissions, it is valid only for your _current_ login session.
+
+## Next step
+
+> [!div class="nextstepaction"]
+> [Integrate media capabilities in Teams](mobile-camera-image-permissions.md)
platform https://docs.microsoft.com/en-us/microsoftteams/platform/includes/v3-to-v4-pointer-bots https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/includes/v3-to-v4-pointer-bots.md
@@ -1,2 +1,2 @@
> [!Important]
-> The articles in this section are based on the v3 Bot Framework SDK. If you're looking for current documentation (version 4.6 or later of the SDK) see the [Conversational Bots](~/bots/what-are-bots.md) section.
+> This article is based on the v3 Bot Framework SDK. If you are looking for current documentation version 4.6 or later of the SDK, see the [conversational bots](~/bots/what-are-bots.md) section.
platform https://docs.microsoft.com/en-us/microsoftteams/platform/resources/bot-v3/bot-conversations/bots-conv-channel https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/resources/bot-v3/bot-conversations/bots-conv-channel.md
@@ -48,7 +48,7 @@ In a channel, replying to a message shows as a reply to the initiating reply cha
When your bot is first added to the group or team, it is generally useful to send a welcome message introducing the bot to all users. The welcome message should provide a description of the botΓÇÖs functionality and user benefits. Ideally the message should also include commands for the user to interact with the app. To do this, ensure that your bot responds to the `conversationUpdate` message, with the `teamsAddMembers` eventType in the `channelData` object. Be sure that the `memberAdded` ID is the bot's App ID itself, because the same event is sent when a user is added to a team. See [Team member or bot addition](~/resources/bot-v3/bots-notifications.md#team-member-or-bot-addition) for more details.
-You might also want to send a personal message to each member of the team when the bot is added. To do this, you could [fetch the team roster](~/resources/bot-v3/bots-context.md#fetching-the-team-roster) and send each user a [direct message](~/resources/bot-v3/bot-conversations/bots-conv-proactive.md).
+You might also want to send a personal message to each member of the team when the bot is added. To do this, you could [fetch the team roster](~/resources/bot-v3/bots-context.md#fetch-the-team-roster) and send each user a [direct message](~/resources/bot-v3/bot-conversations/bots-conv-proactive.md).
We recommend that your bot *not* send a welcome message in the following situations:
platform https://docs.microsoft.com/en-us/microsoftteams/platform/resources/bot-v3/bot-conversations/bots-conv-proactive https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/resources/bot-v3/bot-conversations/bots-conv-proactive.md
@@ -49,7 +49,7 @@ When using proactive messaging to send notifications you need to make sure your
Bots can create new conversations with an individual Microsoft Teams user by obtaining the user's *unique ID* and *tenant ID.* You can obtain these values using one of the following methods:
-* By [fetching the team roster](~/resources/bot-v3/bots-context.md#fetching-the-team-roster) from a channel your app is installed in.
+* By [fetching the team roster](~/resources/bot-v3/bots-context.md#fetch-the-team-roster) from a channel your app is installed in.
* By caching them when a user [interacts with your bot in a channel](~/resources/bot-v3/bot-conversations/bots-conv-channel.md). * When a users is [@mentioned in a channel conversation](~/resources/bot-v3/bot-conversations/bots-conv-channel.md#-mentions) the bot is a part of. * By caching them when you [receive the `conversationUpdate`](~/resources/bot-v3/bots-notifications.md#team-member-or-bot-addition) event when your app is installed in a personal scope, or new members are added to a channel or group chat that
platform https://docs.microsoft.com/en-us/microsoftteams/platform/resources/bot-v3/bots-context https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/resources/bot-v3/bots-context.md
@@ -1,5 +1,5 @@
Title: Get context for your bot
+ Title: Get context for your Microsoft Teams bot
description: Describes how to get context for bots in Microsoft Teams keywords: teams bots context Last updated 05/20/2019
@@ -11,23 +11,28 @@ Last updated 05/20/2019
Your bot can access additional context about the team or chat, such as user profile. This information can be used to enrich your bot's functionality and provide a more personalized experience. > [!NOTE]
-> These Microsoft Teams&ndash;specific bot APIs are best accessed through our extensions for the Bot Builder SDK. For C#/.NET, download our [Microsoft.Bot.Connector.Teams](https://www.nuget.org/packages/Microsoft.Bot.Connector.Teams) NuGet package. For Node.js development, the BotBuilder for Microsoft Teams functionality has been incorporated into the [Bot Framework SDK](https://github.com/microsoft/botframework-sdk) as of v4.6.
+>
+> * Microsoft Teams-specific bot APIs are best accessed through our extensions for the Bot Builder SDK.
+> * For C# or .NET, download our [Microsoft.Bot.Connector.Teams](https://www.nuget.org/packages/Microsoft.Bot.Connector.Teams) NuGet package.
+> * For Node.js development, the Bot Builder for Teams functionality is incorporated into the [Bot Framework SDK](https://github.com/microsoft/botframework-sdk) v4.6.
-## Fetching the team roster
+## Fetch the team roster
-Your bot can query for the list of team members and their basic profiles, which includes Teams user IDs and Azure Active Directory (Azure AD) information such as name and objectId. You can use this information to correlate user identities; for example, to check whether a user logged into a tab through Azure AD credentials is a member of the team.
+Your bot can query for the list of team members and their basic profiles. The basic profiles include Teams user IDs and Azure Active Directory (AAD) information such as name and object ID. You can use this information to correlate user identities. For example, check if a user logged into a tab through AAD credentials is a team member.
### REST API example
-You can directly issue a GET request on [`/conversations/{teamId}/members/`](/bot-framework/rest-api/bot-framework-rest-connector-api-reference#get-conversation-members), using the value of `serviceUrl` as the endpoint.
+Directly issue a GET request on [`/conversations/{teamId}/members/`](/bot-framework/rest-api/bot-framework-rest-connector-api-reference#get-conversation-members), using the `serviceUrl` value as the endpoint.
The `teamId` can be found in the `channeldata` object of the activity payload that your bot receives in the following scenarios:
-* When a user messages or interacts with your bot in a team context (see [Receiving Messages](~/resources/bot-v3/bot-conversations/bots-conversations.md#receiving-messages))
-* When a new user or bot is added to a team (see [Bot or user added to a team](~/resources/bot-v3/bots-notifications.md#bot-or-user-added-to-a-team))
+
+* When a user messages or interacts with your bot in a team context. For more information, see [receiving messages](~/resources/bot-v3/bot-conversations/bots-conversations.md#receiving-messages).
+* When a new user or bot is added to a team. For more information, see [bot or user added to a team](~/resources/bot-v3/bots-notifications.md#bot-or-user-added-to-a-team).
> [!NOTE]
->* Make sure to use the team id when calling the api
->* The value of `serviceUrl` tends to be stable but can change. When a new message arrives, your bot should verify its stored value of `serviceUrl`.
+>
+>* Always use the team ID when calling the API.
+>* The `serviceUrl` value tends to be stable but can change. When a new message arrives, your bot must verify its stored `serviceUrl` value.
```json GET /v3/conversations/19:ja0cu120i1jod12j@skype.net/members
@@ -82,7 +87,7 @@ foreach (var member in members.AsTeamsChannelAccounts())
await context.PostAsync($"People in this conversation: {sb.ToString()}"); ```
-### Node.js/TypeScript example
+### Node.js or TypeScript example
```typescript
@@ -105,15 +110,15 @@ connector.fetchMembers(
); ```
-*See also* [Bot Framework samples](https://github.com/Microsoft/BotBuilder-Samples/blob/master/README.md).
+Also, see [Bot Framework samples](https://github.com/Microsoft/BotBuilder-Samples/blob/master/README.md).
-## Fetching user profile or roster in personal or group chat
+## Fetch user profile or roster in personal or group chat
-You can also make the same API call for any personal chat to obtain the profile information of the user chatting with your bot.
+You can make the API call for any personal chat to obtain the profile information of the user chatting with your bot.
-The API call and SDK methods are identical to fetching the team roster, as is the response object. The only difference is you pass the `conversationId` instead of the `teamId`.
+The API call, SDK methods, and the response object are identical to fetching the team roster. The only difference is you pass the `conversationId` instead of the `teamId`.
-## Fetching the list of channels in a team
+## Fetch the list of channels in a team
Your bot can query the list of channels in a team.
@@ -124,12 +129,12 @@ Your bot can query the list of channels in a team.
### REST API example
-You can directly issue a GET request on `/teams/{teamId}/conversations/`, using the value of `serviceUrl` as the endpoint.
+Directly issue a GET request on `/teams/{teamId}/conversations/`, using the `serviceUrl` value as the endpoint.
-The only source for `teamId` is a message from the team context - either a message from a user or the message that your bot receives when it is added to a team (see [Bot or user added to a team](~/resources/bot-v3/bots-notifications.md#team-member-or-bot-addition)).
+The only source for `teamId` is a message from the team context. The message is either a message from a user or the message that your bot receives when it is added to a team. For more information, see [bot or user added to a team](~/resources/bot-v3/bots-notifications.md#team-member-or-bot-addition).
> [!NOTE]
-> The value of `serviceUrl` tends to be stable but can change. When a new message arrives, your bot should verify its stored value of `serviceUrl`.
+> The `serviceUrl` value tends to be stable but can change. When a new message arrives, your bot must verify its stored `serviceUrl` value.
```json GET /v3/teams/19%3A033451497ea84fcc83d17ed7fb08a1b6%40thread.skype/conversations
@@ -154,7 +159,7 @@ Response body
#### .NET example
-The following example uses the `FetchChannelList` call from the [Microsoft Teams extensions for the Bot Builder SDK for .NET](https://www.nuget.org/packages/Microsoft.Bot.Connector.Teams):
+The following example uses the `FetchChannelList` call from the [Teams extensions for the Bot Builder SDK for .NET](https://www.nuget.org/packages/Microsoft.Bot.Connector.Teams):
```csharp ConversationList channels = client.GetTeamsConnectorClient().Teams.FetchChannelList(activity.GetChannelData<TeamsChannelData>().Team.Id);
@@ -162,7 +167,7 @@ ConversationList channels = client.GetTeamsConnectorClient().Teams.FetchChannelL
#### Node.js example
-The following example uses `fetchChannelList` call from the [Microsoft Teams extensions for the Bot Builder SDK for Node.js](https://www.npmjs.com/package/botbuilder-teams).
+The following example uses `fetchChannelList` call from the [Teams extensions for the Bot Builder SDK for Node.js](https://www.npmjs.com/package/botbuilder-teams):
```javascript var teamId = session.message.sourceEvent.team.id;
@@ -179,3 +184,37 @@ connector.fetchChannelList(
} ); ```+
+## Get clientInfo in your bot context
+
+You can fetch the clientInfo within your bot's activity. The clientInfo contains the following properties:
+
+* Locale
+* Country
+* Platform
+* Timezone
+
+### JSON example
+
+```json
+[
+ {
+ "type": "clientInfo",
+ "locale": "en-US",
+ "country": "US",
+ "platform": "Windows",
+ "timezone": "Asia/Calcutta"
+ }
+]
+```
+
+### C# example
+
+```csharp
+var connector = new ConnectorClient(new Uri(context.Activity.ServiceUrl));
+
+{
+ var clientinfo = context.Activity.Entities[0];
+ await context.PostAsync($"ClientInfo: clientinfo ");
+}
+```
platform https://docs.microsoft.com/en-us/microsoftteams/platform/tabs/what-are-tabs https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/tabs/what-are-tabs.md
@@ -67,4 +67,4 @@ Apps that are [distributed through Appsource](~/concepts/deploy-and-publish/apps
> [Learn more: Request device permissions](../concepts/device-capabilities/native-device-permissions.md) > [!div class="nextstepaction"]
->[Learn more: Camera and image gallery permissions](../concepts/device-capabilities/mobile-camera-image-permissions.md)
+> [Learn more: Integrate media capabilities](../concepts/device-capabilities/mobile-camera-image-permissions.md)
platform https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/what-are-task-modules https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/task-modules-and-cards/what-are-task-modules.md
@@ -236,7 +236,7 @@ Microsoft Teams will ensure that keyboard navigation works properly from the tas
* [C#/.NET sample](https://github.com/OfficeDev/microsoft-teams-sample-task-module-csharp) > [!div class="nextstepaction"]
-> [Learn more: Request device permissions](/concepts/device-capabilities/native-device-permissions.md)
+> [Learn more: Request device permissions](../concepts/device-capabilities/native-device-permissions.md)
> [!div class="nextstepaction"]
->[Learn more: Camera and image gallery permissions](/concepts/device-capabilities/mobile-camera-image-permissions.md)
+> [Learn more: Integrate media capabilities](../concepts/device-capabilities/mobile-camera-image-permissions.md)
platform https://docs.microsoft.com/en-us/microsoftteams/platform/whats-new https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/whats-new.md
@@ -15,6 +15,7 @@ The change log lists changes to the Microsoft Teams platform and this document s
| **Date** | **Notes** | **Changed topics** | | -- | | |
+|02/09/2021|New: Added device capabilities overview. <br/> Update: Microphone capability information is added in the native device permissions and integrate media capabilities files.|[Overview](concepts/device-capabilities/device-capabilities-overview.md), [Request device permissions](concepts/device-capabilities/native-device-permissions.md), [Integrate media capabilities](concepts/device-capabilities/mobile-camera-image-permissions.md)|
|11/30/2020|New: Identity platform integration with Teams Toolkit and Visual Studio Code for tabs|[Single sign-on authentication with Teams Toolkit and Visual Studio Code for tabs](toolkit/visual-studio-code-tab-sso.md)| |11/16/2020|Teams app manifest updated to version 1.8|[Reference: Manifest schema for Microsoft Teams](resources/schem)| |11/10/2020|Teams bot design guidelines|[Bot design guidelines](bots/design/bots.md)|