How to Set Up and Configure an Azure Bot Resource

This guide will walk you through the process of setting up and configuring an Azure Bot for integration with Microsoft Teams. Follow these steps carefully to ensure a successful setup. Creating the Azure Bot Resource

1. Log in to the Azure Portal

Open your web browser and navigate to Azure Portal as an administrator and log in using your organization's credentials.

2. Create the Azure Bot Resource

  1. Click the Create a Resource button.

  1. In the search box at the top, enter Azure Bot and press enter.

  2. Click on the Azure Bot option from the search results.

  1. Click the Create button.

  1. Enter the Bot handle. The Bot Handle is a unique identifier for your bot. You can choose a different Display Name for your bot in the Settings blade after bot creation.

  2. Choose the resource group with which to associate the Bot. A resource group is a collection of resources that share the same lifecycle, permissions, and policies.

  3. To further define boundaries for your data, specify an option for data residency. This limits the regions where data is stored and processed and the channels available for your bot.

  1. Select a pricing tier for your Azure Bot resource. You can change your selection later in the Azure portal's resource management.

Note that the free/standard plan should suffice. 

  1. Click the change plan option, select the free tier, and click the Select button.

  1. Choose the type of App as single-tenant. This determines whether your bot will access resources only in its home tenant.

  2. A Microsoft App ID is required to create an Azure Bot resource. Choose the option to create a new Microsoft App ID. 

image.png

  1. Click the "Review + Create" button.

  2. Click the Create button to finish the process.

  1. Once you've finished setting up the resource, you can proceed from the deployment overview to the actual Azure Bot resource itself.

Follow the instructions provided in the Azure Bot Service Quickstart Registration to create a new Azure Bot resource.

3. Configuring the Azure Bot

In the Azure Bot resource, navigate to Settings > Configuration.
This section contains several settings you need to modify. Refer to the visual guidance provided in the Azure Portal for assistance.

  1. Locate the "Messaging Endpoint" field.

  2. Update the "Messaging Endpoint" to redirect to https://<yourdomain>/api/messages. For example, if your domain is teams-installation.example.com, the URL should be https://teams-installation.example.com/api/messages.

  1. Ensure you save the Microsoft App ID displayed in the configuration settings. This ID will be necessary when setting up your docker container.

  2. Within the Settings section, switch to the Channels tab.

  1. Locate and click the Microsoft Teams and read and agree to the terms of service to proceed.

  1. Ensure that the option 'Microsoft Teams Commercial' is chosen and click the Apply button.

4. Modify bot framework as App Registration

Creating the Azure Bot also created an app registration with the same Microsoft App ID. All of section 4 happens in this app registration, not in the Azure Bot resource.

To open it, do one of the following:

  1. In the Azure Bot resource, go to Settings → Configuration and click Manage Password next to Microsoft App ID.

    Group 1.png

  2. Alternatively, go to Microsoft Entra ID → App registrations → All applications and search for the Microsoft App ID.

    Group 4.png

The app registration's Overview page shows two values you'll need later: Application (client) ID and Directory (tenant) ID. 

Group 2.png

4.1. API Permissions

The add-in needs two Microsoft Graph permissions, both delegated. It doesn't need any application permissions.

Name

Type

Description

Chat.ReadBasic

Delegated

Read names and members of user chat threads.

TeamMember.Read.All

Delegated

Read the members of teams.

  1. In the left menu, go to Manage → API permissions.

  2. Click + Add a permission → Microsoft Graph → Delegated permissions.

  3. Search for and select Chat.ReadBasic and TeamMember.Read.All, then click Add permissions.

  4. Click Grant admin consent for your tenant and confirm. Both permissions should now show a green Granted status.

Group 3.png

4.2. Expose an API

In the left menu, go to Manage → Expose an API. Set up the three parts below in order.

a. Application ID URI

  1. Next to Application ID URI at the top, click Add (or Edit).

  2. Enter api://<your-domain>/<app-id>:

    • <your-domain> is the host from the add-in's BASE_URL, without https://, for example msteams.example.com.

    • <app-id> is the Application (client) ID.

Example: api://msteams.example.com/6f57d69d-cc65-439c-9bcf-…

  1. Click Save.

The domain must match BASE_URL exactly. Otherwise Teams can't sign users in to the add-in.

Group 5.png

b. Scope

  1. Under Scopes defined by this API, click + Add a scope.

  2. Fill in:

    • Scope name: access_as_user

    • Who can consent: Admins and users

    • Display names and descriptions: any text, for example "Access Nextcloud for MS Teams as the user". These fields are required.

    • State: Enabled

  3. Click Add Scope.

Group 6.png

c. Authorized client applications

This lets Teams sign users in to the add-in without asking them for consent.

  1. Under Authorized client applications, click + Add a client application.

  2. Enter 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams desktop and mobile), select the access_as_user scope and click Add application.

  3. Repeat for 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web).

Group 7.png

4.3. Client secret

The add-in's server uses a client secret to sign in as the app.

  1. In the left menu, go to Manage → Certificates & secrets → Client secrets.

  2. Click + New client secret, enter a description, choose an expiry and click Add.

  3. Copy the Value column right away. Azure only shows it once. Don't copy the Secret ID.

Group 8.png

The secret stops working on its expiry date. Before then, create a new one, update MSAPP_PASSWORD and restart the container.

The bot registration is now complete. The last step is to update the container’s environmental variables.

5. Docker Container Values

Set these in the container's .env, then restart the container:

Variable

Value

MSAPP_TYPE

SingleTenant

MSAPP_ID

Application (client) ID

MSAPP_PASSWORD

The client secret Value from 4.3

MSAPP_TENANT_ID

Directory (tenant) ID

The Teams app package contains the Microsoft App ID. If MSAPP_ID changes, for example because the bot was recreated, upload a new Teams app package and remove the old app from Teams.

Troubleshooting: “Unable to reach app”

If you get an “Unable to reach app” error when trying to use the add-in, check the container logs for an AADSTS error code:

Error

Cause

Fix

AADSTS7000215
Invalid client secret

MSAPP_PASSWORD is the secret ID, or a secret from another app registration, or an invalid secret

Create a secret (4.3), copy its Value, restart the container

AADSTS7000222
Client secret expired

The secret is past its expiration date

Create a new secret, update .env, restart the container

AADSTS500131
Assertion audience does not match

The teams package was built for a different app id than MSAPP_ID

Upload a new Teams app package and remove the old app

Last updated November 6, 2026
Was this article helpful?