Use Azure CLI to create or update an Azure Bot resource

  • Article

APPLIES TO: SDK v4

This article describes how to create or update an Azure Bot resource with the Azure CLI and an Azure Resource Manager template (ARM template).

This is part of the larger process to provision and publish a bot.

Note

The Bot Framework JavaScript, C#, and Python SDKs will continue to be supported, however, the Java SDK is being retired with final long-term support ending in November 2023.

Existing bots built with the Java SDK will continue to function.

For new bot building, consider using Microsoft Copilot Studio and read about choosing the right copilot solution.

For more information, see The future of bot building.

Prerequisites

To use the Azure CLI to provision and publish bots, you need:

  • An Azure account that has an active subscription. Create a trial subscription.

  • An install of the Azure CLI.

    For your programming language, use the following version of the Azure CLI. Some steps won't work with later versions of the CLI.

    Language CLI version
    C# and JavaScript 2.39.0 or later
    Python 2.55.0 or later
    Java 2.29.2

  • This process uses an Azure Resource Manager template (ARM template) to create an Azure Bot resource for your bot.

    If you don't have the current templates, create a copy in your bot project of the deploymentTemplates folder: C#, JavaScript, Python, or Java.

Tip

This is part of the larger process to provision and publish a bot. See how to Provision and publish a bot for a complete list of prerequisites.

Edit parameters file

Edit the parameters file for the ARM template to contain the values you want to use.

Important

You must use the same appType and appId values when you create your App Service and Azure Bot resources.

If your project doesn't yet contain the most recent ARM template and parameters files, you can copy them from the Bot Framework SDK repo for your language: C#, JavaScript, Python, or Java.

This table describes the deployment parameters in the parameters file, for use with the parameters command option. By default, the name of the parameters file is parameters-for-template-AzureBot-with-rg.json.

Parameter Type Description
azureBotId String Required. The globally unique and immutable handle for your bot, such as ContosoCustomerService.
azureBotSku String Optional. The SKU of the Azure Bot resource. Allowed values: "F0" (free) and "S1" (standard). Default is "S1".
azureBotRegion String Optional. The location of the Azure Bot. Allowed values: "global", "westeurope", "westus" and "centralindia". Default is "global".
botEndpoint String Optional. The messaging endpoint for your bot, such as https://<appServiceName>.chinacloudsites.cn/api/messages.
appType String Required. How the identities of your bot resources are managed. Allowed values are: "MultiTenant", "SingleTenant", and "UserAssignedMSI". Default is "MultiTenant".
appId String Required. The client ID or app ID from the identity resource you created earlier. This is the Microsoft app ID of the app service.
UMSIName String Optional. For user-assigned managed identity app types, the name of the identity resource.
UMSIResourceGroupName String Optional. For user-assigned managed identity app types, the resource group for the identity resource.
tenantId String Optional. For user-assigned managed identity and single-tenant app types, The Microsoft Entra ID tenant ID for the identity resource.

Tip

The bot's messaging endpoint must be set before a published bot can receive messages.

Not all parameters apply to all app types.

Provide values for UMSIName, UMSIResourceGroupName, and tenantId.

Create the Azure Bot resource

To create the Azure Bot resource for your bot, use the following command.

az deployment group create --resource-group <resource-group> --template-file <template-file-path> --parameters "@<parameters-file-path>"
Option Description
resource-group Name of the Azure resource group in which to create the App Service.
template-file The path to the ARM template for the App Service. The path can be relative or absolute.
parameters The path to the parameters file to use with the ARM template. The path can be relative or absolute.

For projects created with the latest generators, the ARM template and parameter files are located in the DeploymentTemplates\DeployUseExistResourceGroup folder within the project. The default file names are template-AzureBot-with-rg.json and parameters-for-template-AzureBot-with-rg.json.

To update your Azure Bot resource

To add or update the messaging endpoint for your Azure Bot, use the following command.

az bot update --resource-group <resource group> --name <azureBotId> --endpoint <messaging-endpoint>
Option Description
resource-group Name of the Azure resource group that contains the App Service.
name The globally unique and immutable handle for your bot.
endpoint The messaging endpoint for your bot, such as https://<appServiceName>.chinacloudsites.cn/api/messages.

Additional information

For more information about ARM templates, see What are ARM templates? and How to use Azure Resource Manager (ARM) deployment templates with Azure CLI.

Next steps

If you created the App Service as part of a bot deployment, see Create resources with ARM templates to continue the process.