Use the Azure portal to Create an Azure Bot resource

APPLIES TO: SDK v4

The Azure Bot resource (bot resource) allows you to register your bot with Azure AI Bot Service and to connect your bot to channels. You can build, connect, and manage bots to interact with your users wherever they are, from your app or website to Teams, Messenger and many other channels.

This article describes how to create a bot resource through the Azure portal.

Managing resources

When you create a bot resource, Azure creates associated resources. Some of the resources created depend on how you decide to manage your bot's identity.

Your bot identity can be managed in Azure in a few different ways.

  • As a user-assigned managed identity, so that you don't need to manage the bot's credentials yourself.
  • As a single-tenant app.
  • As a multi-tenant app.

Support for the user-assigned managed identity and single-tenant app types was added to the Bot Framework SDK for C#, JavaScript, and Python. These app types aren't supported in the other languages or in Bot Framework Composer, Bot Framework Emulator, or Dev Tunnels.

App type Support
User-assigned managed identity Azure AI Bot Service and the C#, JavaScript, and Python SDKs
Single-tenant Azure AI Bot Service and the C#, JavaScript, and Python SDKs
Multi-tenant Azure AI Bot Service, all Bot Framework SDK languages, Composer, the Emulator, and Dev Tunnels

Prerequisites

  • If you don't have an Azure subscription, create a free account before you begin.
  • The Bot Framework SDK for C# or JavaScript version 4.15.0 or later, for user-assigned managed identity and single-tenant bots.

Create the resource

Create the Azure Bot resource, which will allow you to register your bot with the Azure AI Bot Service.

Tip

New Web App Bot and Bot Channels Registration resources can't be created; however, any such existing resources that are configured and deployed will continue to work. Bots created from a VSIX or Yeoman template from SDK version 4.14.1.2 or later contain ARM templates that will generate an Azure Bot resource.

  1. Go to the Azure portal.

  2. In the right pane, select Create a resource.

  3. In the search box enter bot, then press Enter.

  4. Select the Azure Bot card.

    Select Azure bot resource

  5. Select Create.

  6. Enter values in the required fields and review and update settings.

    1. Provide information under Project details. Select whether your bot will have global or local data residency. Currently, the local data residency feature is available for resources in the "westeurope" and "centralindia" region. For more information, see Regionalization in Azure AI Bot Service.

      The project details settings for an Azure Bot resource

    2. Provide information under Microsoft App ID. Select how your bot identity will be managed in Azure and whether to create a new identity or use an existing one.

      The Microsoft app ID settings for an Azure Bot resource

  7. Select Review + create.

  8. If the validation passes, select Create.

  9. Once the deployment completes, select Go to resource. You should see the bot and related resources listed in the resource group you selected.

  10. If you don't already have the Bot Framework SDK, select Download from GitHub to learn how to consume the packages for your preferred language.

    Create bot in SDK

You're now ready to build your bot with the Bot Framework SDK.

Tip

When Azure creates a new single-tenant or multi-tenant Azure Bot resource with a new app ID, it also generates a password.

Bot identity information

Follow these steps to add identity information to your bot's configuration file. The file differs depending on the programming language you use to create the bot.

Important

The Java version of the Bot Framework SDK only supports multi-tenant bots. The C#, JavaScript, and Python versions support all three application types for managing the bot's identity.

Language File name Notes
C# appsettings.json Supports all three application types for managing your bot's identity.
JavaScript .env Supports all three application types for managing your bot's identity.
Java application.properties Only supports multi-tenant bots.
Python config.py Supports all three application types for managing your bot's identity.

The identity information you need to add depends on the bot's application type. Provide the following values in your configuration file.

Available for C#, JavaScript, and Python bots.

Property Value
MicrosoftAppType UserAssignedMSI
MicrosoftAppId The client ID of the user-assigned managed identity.
MicrosoftAppPassword Not applicable. Leave this blank for a user-assigned managed identity bot.
MicrosoftAppTenantId The tenant ID of the user-assigned managed identity.

To update your app service

If you have an existing App Service resource (web app) for your bot and your bot is a user-assigned managed identity application, you may need to update your bot's app service:

  1. Go to the App Service blade for your bot's web app.
  2. Under Settings, select Identity.
  3. On the Identity blade, select the User assigned tab and Add (+).
  4. On the Add user assigned managed identity blade:
    1. Select your subscription.

    2. For User assigned managed identities, select the managed identity for your bot. If the managed identity was auto-generated for you, it will have the same name as your bot.

    3. Select Add to use this identity for your bot.

      The App Service Identity blade with the managed identity for the bot selected.

To get your app or tenant ID

To get your bot's app or tenant ID:

  1. Go to the Azure Bot resource blade for your bot.
  2. Go to the bot's Configuration blade. From this blade, you can copy the bot's Microsoft App ID or App Tenant ID.

To generate a new password

Single-tenant and multi-tenant bots have an app secret or password that you need for some operations. Azure AI Bot Service hides your bot secret. However, the owner of the bot's App Service resource can generate a new password:

  1. Go to the Azure Bot resource blade for your bot.
  2. Go to the bot's Configuration blade.
  3. Select Manage, next to Microsoft App ID, to go to the Certificates + secrets blade for the app service.
  4. Follow the instructions on the blade to create a new client secret and record the value in a safe place.

Additional information

Note

The Bot Framework Composer and Bot Framework Emulator currently only support multi-tenant bots. The Bot Framework SDK for C# or JavaScript version 4.15.0 or later is required for user-assigned managed identity and single-tenant bots.

Skill support

Some types of skill consumers are not able to use some types of skill bots. The following table describes which combinations are supported.

  Multi-tenant skill Single-tenant skill User-assigned managed identity skill
Multi-tenant consumer Supported Not supported Not supported
Single-tenant consumer Not supported Supported if both apps belong to same tenant Supported if both apps belong to same tenant
User-assigned managed identity consumer Not supported Supported if both apps belong to same tenant Supported if both apps belong to same tenant

For information on how to configure a skill or skill consumer, see Implement a skill or Implement a skill consumer.

Next steps