Register a bot with the Bot Framework

Before others can use your bot, you must register it with the Bot Framework. Registration is a simple process. You are prompted to provide some information about your bot and then the portal generates the app ID and password that your bot will use to authenticate with the Bot Framework.

Note

Bots created with the Azure Bot Service are automatically registered as part of the creation process.

Register your bot

To register your bot, you must sign in to the Bot Framework Portal. After you sign in, click My bots, then click Create a bot, then select Register an existing bot built using Bot Builder SDK., and finally, click Ok. Then complete the following steps.

Complete the Bot profile section of the form.

  1. Upload an icon that will represent your bot in the conversation.
  2. Provide your bot's Display Name. When users search for this bot, this is the name that will appear in the search results.
  3. Provide your bot's Handle. This value will be used in the URL for your bot and cannot be changed after registration.
  4. Provide a Description of your bot. This is the description that will appear in search results, so it should accurately describe what the bot does.

Complete the Configuration section of the form.

  1. Provide your bot's HTTPS messaging endpoint. This is the endpoint where your bot will receive HTTP POST messages from Bot Connector. If you built your bot by using the Bot Builder SDK, the endpoint should end with /api/messages.

    • If you have already deployed your bot to the cloud, specify the endpoint generated from that deployment.
    • If you have not yet deployed your bot to the cloud, leave the endpoint blank for now. You will return to the Bot Framework Portal later and specify the endpoint after you've deployed your bot.
  2. Click Create Microsoft App ID and password.

    • On the next page, click Generate an app password to continue.
    • Copy and securely store the password that is shown, and then click Ok.
    • Click Finish and go back to Bot Framework.
    • Back in the Bot Framework Portal, the App ID field is now populated.

Complete the Analytics section of the form.

To enable analytics for your bot, provide the AppInsights Instrumentation key, AppInsights API key, and AppInsights Application ID from the corresponding Azure Application Insights resource that you've created to monitor your bot.

Note

If you have not yet created an Azure Application Insights resource to monitor your bot, leave these fields blank. To enable analytics for your bot in the future, return to the Bot Framework Portal and populate these fields at that time.

Complete the Admin section of the form.

  1. Specify the email address(es) for the Owner(s) of the bot.

  2. Check to indicate that you have read and agree to the Terms of Use, Privacy Statement, and Code of Conduct.

  3. Click Register to complete the registration process.

Update application configuration settings

After you've registered your bot, update the Microsoft App Id and Microsoft App Password values in your application's configuration settings to specify the app ID and password values that were generated for your bot during the registration process.

Tip

If you're using the Bot Builder SDK for Node.js, set the following environment variables:

  • MICROSOFT_APP_ID
  • MICROSOFT_APP_PASSWORD
If you're using the Bot Builder SDK for .NET, set the following key values in the web.config file:
  • MicrosoftAppId
  • MicrosoftAppPassword

Update or delete registration

To update or delete the bot's registration data:

  1. Sign in to the Bot Framework Portal.
  2. Click My Bots.
  3. Select the bot that you want to configure and click Settings.
    • To generate a new password, scroll down to the Configuration section and click Manage Microsoft App ID and password.
    • To update a bot's settings, change field value(s) as desired, then scroll down to the Admin section and click Save changes.
    • To delete a bot, scroll down to the Admin section and click click Delete bot.

Next steps

After you have registered your bot with the Bot Framework, the next step in the bot publication process will depend upon whether or not you've already deployed your bot to the cloud.

If you have not yet deployed your bot to the cloud:

  1. Deploy your bot to the cloud by following the instructions found in Deploy a bot to the cloud.

  2. Return to the Bot Framework Portal and update your bot's registration data to specify the HTTPS endpoint for the bot.

  3. Configure the bot to run on one or more channels.

If you have already deployed your bot to the cloud:

  1. Update the Microsoft App Id and Microsoft App Password values in your deployed application's configuration settings to specify the app ID and password values that were generated for your bot during the registration process, as described here.

  2. Configure the bot to run on one or more channels.