Registering a calling bot

In this topic you will learn how to register a new Calling Bot. The UI and terminologies may change in the future, henceforth screenshots in this writing can become obsolete. Please check for existing or open a new issue in the github repository if you find this writing is no longer accurate.

Registering an app registration

Complete the following steps:

  1. From the azure portal, go to App registrations.

    2. App registrations

  2. Select New registation, and fill out the form and click Register.
  3. After the resource creation, click Go to resource. Take note of Application (client) ID (1) and Directory (tenant) ID (2).

    4. App registrations information

  4. Go to Certificates & secrets, create new client secret and take notes of the value and secret Id.

Register your bot in the Azure Bot Service

Complete the following steps:

  1. Register a bot by creating a Azure Bot through Azure Bot Service. Before proceeding, there are a few custom steps we need here.

      2. When following the above document to create an Azure bot,
    • Manually create a User Managed Identity, and take note of the Id (3) under Properties blade.

    • Use existing app registration. Fill the App ID, App tenant ID, and MSI resource ID with (1), (2) and (3) respectively.
  2. Once you complete the registration, take a note of the registered config values (Bot Name, Application Id, and Application Secret). You will need these values later in the code samples.
  3. In the resource blade, click Channels.
  4. Enable the Microsoft Teams channel and enable calling on the Calling tab. Fill in the Webhook (for calling) where you will receive incoming notifications. E.g. https://{your domain}/api/calls. Refer to Connect a bot to channels for more information on how to configure channels.

Microsoft Teams Enable Calling

Permissions

Add Microsoft Graph permissions for calling to your bot

Microsoft Graph exposes granular permissions controlling the access apps have to resources. As a developer, you decide which permissions for Microsoft Graph your app requests. The Microsoft Graph Communications Calling APIs support Application permissions, which are used by apps that run without a signed-in user present; for example, apps that run as background services or bots. Application permissions can only be consented by a tenant administrator. Calling bots and applications have some capabilties that will need tenant administrator consent. Below is a list of those permissions:

Permission Display String Description Admin Consent Required
Calls.Initiate.All Initiate outgoing 1:1 calls from the app 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 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 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 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 Allows the app to get direct access to participant 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.

Assigning permissions

You pre-configure the application permissions your app needs when you register your app. To add permissions from the Azure Bot Registration Portal:

  • Go to the previously created app registration, click on API permissions and then click Add a permission in the right pane. Select Microsoft Graph, choose Application Permissions and then select the permissions your app requires in the Select Permissions dialog.

Add Graph Permissions

An administrator can either 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, but often a better option is to provide a sign-up experience for administrators by using the Azure AD v2.0 /adminconsent endpoint. Please refer to the instructions on constructing an Admin Consent URL for more detail.

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 field replyURLs.

Important: Any time you make a change to the configured 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.