Bot channels registration

APPLIES TO: SDK v4

This article shows how to register a bot with the Azure Bot Service. If the bot is hosted elsewhere, you can also make it available in Azure and connect it to the supported channels. There are 2 ways to register a bot with Azure:

  1. Following the steps in the article Create a bot with Azure Bot Service, the bot is created on and registered with Azure and a Web application is created to host the bot. You use this approach if you develop and host a bot in Azure.
  2. To create and develop your bot locally, follow the steps in this article. When you register your bot, you supply the web address where your bot is hosted. You can still host it in Azure.

Important

You only need to register a bot if it is not hosted in Azure. Bots created using the Azure portal or the Command Line Interface (CLI) are already registered with the Azure Bot Service. For more information, see Deploy your bot and Create a bot with Azure Bot Service.

Create a registration application

  1. In your browser, navigate to the Azure portal. If you do not have a subscription, you can register for a free account.

  2. In the left panel, click Create a resource.

  3. In the right panel selection box enter bot. From the drop-down list select Bot Channels Registration.

  4. Click the Create button.

  5. In the Bot Channels Registration form, provide the requested information about your bot as specified in the table below.

    Setting Suggested value Description
    Bot name <Your bot display name> Assign the display name for the bot that appears in channels and directories. You can change this name at anytime.
    Subscription <Your subscription> Select the Azure subscription you want to use.
    Resource Group <Your resource group name> Create a new resource group or select an existing one.
    Location West US Choose the geographic location for your resource group. It's usually best to choose a location close to you. The location cannot be changed once the resource group is created.
    Pricing tier F0 Select a pricing tier. You may update the pricing tier at any time. For more information, see Bot Service pricing.
    Messaging endpoint https://<your bot name>.azurewebsites.net/api/messages Enter the URL for your bot's messaging endpoint. You can leave this field empty since you will enter the required URL after deploying the bot.
    Application Insights On Decide if you want to turn Application Insights On or Off. If you select On, you must also specify a regional location.
    App ID and password Create App ID and password Use this option if you need to manually enter a Microsoft App ID and password. See the next section Manual app registration. Otherwise, a new Microsoft app ID will be created in the registration process.
  6. Leave the Messaging endpoint box empty for now. You'll enter the required URL after deploying the bot.

  7. Click Microsoft App ID and password, highlighted in the screenshot below. The next steps allow you to create the registration application password and application ID to be used in your bot configuration files appsettings.json (.NET), .env (Javascript) and config.py (Python).

    bot registration settings

  8. Click Create New.

  9. Click the Create App ID in the App Registration Portal link.

  10. In the displayed App registration window, click the New registration tab in the upper left.

  11. Enter the name of the bot application you are registering.

  12. For the supported account types, select the type based on your requirements. See also Use bot credentials.

  13. Click the Register button. Once completed, Azure displays the overview page for the application.

  14. Copy the Application (client) ID value and save it in a file.

  15. In the left panel, click Certificate and secrets.

  16. Under Client secrets, click New client secret.

  17. Add a description to identify this secret from others you might need to create for this app.

  18. Set Expires to your choosing.

  19. Click Add.

  20. Copy the client secret and save it to a file. Make sure to keep the file in a secure place.

  21. Go back to the Bot Channel Registration window and copy the App ID and the Client secret in the Microsoft App ID and Password boxes, respectively.

  22. Click OK.

  23. Click the Create button and wait for the resource to be created. It will show in your resources list.

Note

The registration application will show the Global region even though you selected a different one. This is expected.

Manual app registration

A manual registration is necessary for situations like:

  • You are unable to make the registrations in your organization and need another party to create the App ID for the bot you're building.
  • You need to manually create your own app ID and password.

Important

In the section Supports account types, choose one of the two multi-tenant types, Accounts in any organizational directory (Any Azure AD - Multitenant) or Accounts in any organizational directory (Any Azure AD - Multitenant) and personal Microsoft accounts (e.g. Xbox, Outlook.com), when creating the app. Not setting this value correctly will result in a non-functional bot. For more information, see Register a new application using the Azure portal and Register an application with the Microsoft identity platform.

Update the bot

  1. Bot Framework SDK for .NET. Set the following key values in the appsettings.json file:

    • MicrosoftAppId = <appId>
    • MicrosoftAppPassword = <appSecret>
  2. Bot Framework SDK for Node.js. Set the following environment variables in the .env file:

    • MICROSOFT_APP_ID = <appId>
    • MICROSOFT_APP_PASSWORD = <appSecret>
  3. Bot Framework SDK for Python. Set the following environment variables in the config.py file:

    • APP_ID = os.environ.get("MicrosoftAppId", <appId>)
    • APP_PASSWORD = os.environ.get("MicrosoftAppPassword", <appSecret>)

Test the bot

Now that your bot service is created, test it in Web Chat.

Next steps

In this topic, you learned how to register your hosted bot with the Bot Service. The next step is to learn how to manage your Bot Service.