Just as you can add a Word tab or the Who bot in Teams, you can write your own tabs and bots. You can also write applications that run outside the Teams UI and use the Microsoft Graph API to access and curate Teams content. The best way to navigate the samples is to use the Sample Navigator. As part of our Cloud communications API set, this API is used to subscribe to the Teams presence information of other users. Use webhooks to receive notifications when a user's presence changes. This is an alternative to polling for presence by using the GET presence and POST getPresencesByUserId APIs.
-->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 Microsoft Teams JavaScript client SDK, that provides the tools necessary for your app to access a user's device permissions. 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.
Advantage of integrating media capabilities
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. Lyn th.
For effective integration, you must have a good understanding of 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 to handle the errors in your Teams app.
Note
Ms Teams Api
Currently, Microsoft Teams support for media capabilities is only available for mobile clients.
Teams Api Send Message
Update manifest
Update your Teams app manifest.json 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.
Note
The Request Permissions prompt is automatically displayed when a relevant Teams API is initiated. For more information, see Request device permissions.
Media capability APIs
The selectMedia, getMedia, and viewImages APIs enable you to use native media capabilities as follows:
- 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
, andviewImages
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. selectMedia
API has been extended to support microphone and audio properties.
You must use the following set of APIs to enable your device's media capabilities:
API | Description |
---|---|
selectMedia (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 configuration. |
selectMedia (Microphone) | Set the mediaType 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. 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 | 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 | 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
Web app experience for selectMedia API for microphone capability
Error handling
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 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 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 | 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. |
Code snippets
Calling selectMedia
API for capturing images using camera:
Calling getMedia
API to retrieve large media in chunks:
Teams Api Python
Calling viewImages
API by ID returned by selectMedia
API:
Calling viewImages
API by URL:
Calling selectMedia
and getMedia
APIs for recording audio through microphone:
See also
-->Microsoft Teams is the ultimate hub for teamwork and intelligent communications.Built on the strength and scale of Microsoft 365 with over 120 million users,Microsoft Teams delivers chat-based collaboration, meetings, calling, and enterprise voice features.
Why integrate with Microsoft Teams?
Automate team lifecycles
Use Microsoft Graph to create a new virtual team when a new business issue arises,add the right people to the team,and configure the team withchannels,tabs,and apps.If you want to get the new team together to discuss the business issue,add a new event to the team calendar.
When the business issue is resolved and you no longer need the team,use the Microsoft Teams API to archiveor delete the team.If you know the maximum duration of the team when you create it,set an Microsoft 365 group expiration policyfor the team that automatically removes the team according to the policy.
Get work done even when no one is around
Use application permissions to work withteams, channels, andtabswithout human intervention.Create a new channel when your customer files an order.Automatically create teams for classes at the beginning of the school year, and archive them at the end.
Create teams linked to your app
Let customers create new teams and channels.Install yourTeams app in the new teams.Pin your app to a tab in the new channel.Send messages to the channel linking back to your website.
Create and manage multiple teams and channels
Microsoft Graph makes it easy to create large numbers of teams and populate them with users and channels,by automate creating and managing teams, channels,tabs, and apps.Microsoft Graph also lets you findand archivethe teams you are no longer using.This is the same API that the Microsoft Teams Admin Centerand Teams PowerShell commandlets are built on.
Deploy apps to teams
List the teams in your tenant,and install apps to them.Create tabs in channels to give users easy access to apps.
Use Microsoft Graph in any kind of app
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. Lyn th.
For effective integration, you must have a good understanding of 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 to handle the errors in your Teams app.
Note
Ms Teams Api
Currently, Microsoft Teams support for media capabilities is only available for mobile clients.
Teams Api Send Message
Update manifest
Update your Teams app manifest.json 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.
Note
The Request Permissions prompt is automatically displayed when a relevant Teams API is initiated. For more information, see Request device permissions.
Media capability APIs
The selectMedia, getMedia, and viewImages APIs enable you to use native media capabilities as follows:
- 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
, andviewImages
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. selectMedia
API has been extended to support microphone and audio properties.
You must use the following set of APIs to enable your device's media capabilities:
API | Description |
---|---|
selectMedia (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 configuration. |
selectMedia (Microphone) | Set the mediaType 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. 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 | 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 | 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
Web app experience for selectMedia API for microphone capability
Error handling
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 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 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 | 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. |
Code snippets
Calling selectMedia
API for capturing images using camera:
Calling getMedia
API to retrieve large media in chunks:
Teams Api Python
Calling viewImages
API by ID returned by selectMedia
API:
Calling viewImages
API by URL:
Calling selectMedia
and getMedia
APIs for recording audio through microphone:
See also
-->Microsoft Teams is the ultimate hub for teamwork and intelligent communications.Built on the strength and scale of Microsoft 365 with over 120 million users,Microsoft Teams delivers chat-based collaboration, meetings, calling, and enterprise voice features.
Why integrate with Microsoft Teams?
Automate team lifecycles
Use Microsoft Graph to create a new virtual team when a new business issue arises,add the right people to the team,and configure the team withchannels,tabs,and apps.If you want to get the new team together to discuss the business issue,add a new event to the team calendar.
When the business issue is resolved and you no longer need the team,use the Microsoft Teams API to archiveor delete the team.If you know the maximum duration of the team when you create it,set an Microsoft 365 group expiration policyfor the team that automatically removes the team according to the policy.
Get work done even when no one is around
Use application permissions to work withteams, channels, andtabswithout human intervention.Create a new channel when your customer files an order.Automatically create teams for classes at the beginning of the school year, and archive them at the end.
Create teams linked to your app
Let customers create new teams and channels.Install yourTeams app in the new teams.Pin your app to a tab in the new channel.Send messages to the channel linking back to your website.
Create and manage multiple teams and channels
Microsoft Graph makes it easy to create large numbers of teams and populate them with users and channels,by automate creating and managing teams, channels,tabs, and apps.Microsoft Graph also lets you findand archivethe teams you are no longer using.This is the same API that the Microsoft Teams Admin Centerand Teams PowerShell commandlets are built on.
Deploy apps to teams
List the teams in your tenant,and install apps to them.Create tabs in channels to give users easy access to apps.
Use Microsoft Graph in any kind of app
Microsoft Teams apps give work groups a new tool to make collaboration a more productive and compelling experience. These apps let work group users share assets, interact through chat, and schedule events on the team calendar. These apps can also automate creating teams, channels, and conversations, enhancing the value of Microsoft Teams.
You can create web sites, services, and native platform applications that run outside the Microsoft Teams user experience, and call the Teams API to automate Teams scenarios.
Types of apps enabled for Microsoft Teams
These collaboration tools include Microsoft Graph-enabled tabs or bots running inside Microsoft Teams apps. You can also call Microsoft Graph outside of a Microsoft Teams app, such as from a website or a web service. If you've already enabled your website for Microsoft Graph, you can use that work for Microsoft Teams by using the Microsoft Teams developer platform to create a tab that uses the existing website code.
Microsoft Teams APIs can enhance apps inside and outside of Teams:
App type | Scenario description |
---|---|
Tabs | Surface your content in Microsoft Teams. |
Bots | Help users get tasks done in conversations. |
Connectors | Post updates from external services to channels. |
Actionable messaging | Add enhanced interaction to your connector cards. |
Messaging extensions | Allow users to query and share information in conversations. |
Websites | Surface enhanced content in your web pages. |
Services | Enhance your client applications with Microsoft Graph data via your web service. |
Activity feed | Engage users via feed notifications. |
Calling and online meetings (preview) | Create Microsoft Teams apps with bots that can initiate and participate in audio/video calls, route/transfer calls based on interactive voice response (IVR) flows, and participate in online meetings. |
Get notified about changes
Microsoft Teams supports subscribing to changes (create, update, and delete) to messages in channels and chats to allow apps to get near-instant updates. For details about how to subscribe to changes, see Get change notifications for messages in channels and chats.
API reference
Looking for the API reference for this service?
See the Teams API in Microsoft Graph.
Next steps
- Watch the overview video.
- Learn how to use the Microsoft Teams API.
- Drill down on the methods, properties, and relationships of the team, channel, and group resources.
- Try the API in the Graph Explorer.
- Read more about the Microsoft Teams programming model.
- Explore the cloud communications APIs.
- Get a jump-start with sample code: Contoso Airlines, C# mini-samples