Use Azure CLI to create or update an Azure Bot resource

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.

• For information on the complete process, see Provision and publish a bot.
• For information on how to create an App Service resource, see Use Azure CLI to create an App Service resource.
• For instructions for how to use the Azure portal, see the Create an Azure Bot resource quickstart.

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 free account.

• 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>.azurewebsites.net/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.

User-assigned managed identity

Provide values for UMSIName, UMSIResourceGroupName, and tenantId.

Single-tenant

• Provide a value for tenantId.
• Leave UMSIName and UMSIResourceGroupName blank.

Multi-tenant

Leave UMSIName, UMSIResourceGroupName, and tenantId blank.

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>.azurewebsites.net/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.