Registering a calling bot for Microsoft Teams

A bot that participates in audio/video calls and online meetings is an ordinary Microsoft Teams bot with a few extra things:

  • There's a new version of the Teams app manifest with two extra settings, supportsCalling and supportsVideo. These settings are included in the Developer Preview version of the Microsoft Teams app manifest.
  • Microsoft Graph permissions must be configured for your bot's Microsoft App ID.
  • The Microsoft Graph calls and online meetings APIs permissions require tenant admin consent.

Let's discuss the above in more detail.

New manifest settings

Calling and online meetings bots have two extra settings in the manifest.json that enable audio/video for your bot in Teams.

  • bots[0].supportsCalling. If present and set to true, Teams will allow your bot to participate in calls and online meetings.
  • bots[0].supportsVideo. If present and set to true, Teams knows that your bot supports video.

If you want your IDE to properly validate the manifest.json schema for your calling and meeting bot for these values, you can change the $schema attribute to this:

"$schema": "https://raw.githubusercontent.com/OfficeDev/microsoft-teams-app-schema/preview/DevPreview/MicrosoftTeams.schema.json",

Creating a new bot or adding calling capabilities to an existing bot

Creating a bot for Microsoft Teams is covered in more detail in the Create a new bot topic, but we'll repeat some of it here:

  1. Use this link to create a new bot: https://dev.botframework.com/bots/new. If you click on the Create a bot button in the Bot Framework portal instead, you will create your bot in Microsoft Azure instead, for which you'll need an Azure account.
  2. Add the Microsoft Teams channel. Click on the "Calling" tab on the Microsoft Teams channel page and click on Enable calling, and then update Webhook (for calling) with your https URL where you will receive incoming notifications, e.g.https://contoso.com/teamsapp/api/calling. Refer to Configuring Channels for more information on how to configure channels. Configure Microsoft Teams channel information

Add Microsoft Graph permissions

Microsoft Graph exposes granular permissions controlling the access that apps have to resources. As a developer, you decide which permissions for Microsoft Graph your app requests. The Microsoft Graph Calling APIs support Application permissions, which are used by apps that run without a signed-in user present. A tenant administrator must grant consent to application permissions. Below is a list of those permissions:

Application permissions: calls

Permission Display String Description Admin Consent Required
Calls.Initiate.All Initiate outgoing 1:1 calls from the app (preview) Allows the app to place outbound calls to a single user and transfer calls to users in your organization’s directory, without a signed-in user. Yes
Calls.InitiateGroupCall.All Initiate outgoing group calls from the app (preview) Allows the app to place outbound calls to multiple users and add participants to meetings in your organization, without a signed-in user. Yes
Calls.JoinGroupCall.All Join Group Calls and Meetings as an app (preview) Allows the app to join group calls and scheduled meetings in your organization, without a signed-in user. The app will be joined with the privileges of a directory user to meetings in your tenant. Yes
Calls.JoinGroupCallasGuest.All Join Group Calls and Meetings as a guest (preview) Allows the app to anonymously join group calls and scheduled meetings in your organization, without a signed-in user. The app will be joined as a guest to meetings in your tenant. Yes
Calls.AccessMedia.All see below Access media streams in a call as an app (preview) Allows the app to get direct access to media streams in a call, without a signed-in user. Yes

Important: You may not use the Microsoft.Graph.Calls.Media API to record or otherwise persist media content from calls or meetings that your bot accesses.

Application permissions: online meetings

Permission Display String Description Admin Consent Required
OnlineMeetings.Read.All Read Online Meeting details from the app (preview) Allows the app to read Online Meeting details in your organization, without a signed-in user. Yes
OnlineMeetings.ReadWrite.All Read and Create Online Meetings from the app (preview) on behalf of a user Allows the app to create Online Meetings in your organization on behalf of a user, without a signed-in user. Yes

Assigning permissions

You must configure the application permissions your bot in advance. We recommend using the Microsoft App Registration Portal as described here because that's where your bot was configured, but you can still use the Azure portal if you prefer to use Azure AD v1 authorization.

For apps using Azure AD v1 authorization, a tenant administrator can consent to these permissions using the Azure portal when your app is installed in their organization, or you can provide a sign-up experience in your app through which administrators can consent to the permissions you configured. Once administrator consent is recorded by Azure AD, your app can request tokens without having to request consent again.

You can rely on an administrator to grant the permissions your app needs at the Azure portal; however, often, a better option is to provide a sign-up experience for administrators by using the Azure AD v2 /adminconsent endpoint. Please refer to the instructions on constructing an Admin Consent URL for more information.

Note

  • Constructing the Tenant Admin Consent URL requires a configured Redirect URI/Reply URL in the App Registration Portal. To add reply URLs for your bot, access your bot registration, choose Advanced Options > Edit Application Manifest. Add your Redirect URI to the replyUrls collection.
  • Important: Any time you make a change to your application's permissions, you must also repeat the Admin Consent process. Changes made in the app registration portal will not be reflected until consent has been reapplied by the tenant's administrator.