Microsoft Bot Framework SDK for Node.js allows developers to build text and voice based chatbots and connect them to a variety of channels including Skype, MS Teams, Slack, Facebook, Telegram, SMS, email, and more.
As a Node.js bot developer you may have asked yourself - “Can I deploy my bot to Azure on Linux?” - and yes, it is now possible using the Azure App Service for Linux (Preview). This article will help you get started with Azure bot deployments on Linux using the Node.js SDK for Bot Framework. I will walk you though the steps to setup your bot with Continuous Deployment via GitHub, register your new bot in the Bot Framework Portal, configure required app settings, as well as test your bot connection via WebChat.
Setting up the development environment
In order to follow along with this tutorial you will need the following apps and accounts:
- Microsoft Account (MSA) - Use your existing account, or click here to create a new account.
- GitHub Account - Use your existing account, or sign up now.
- Visual Studio Code IDE - Available for free download here
- Azure Account - Use your MSA Account to sign-in to the Azure Portal
- GitHub Desktop - Download here
- Chocolatey, The Package Manager for Windows - Install instructions
- Node Version Manager (NVM) - Install via Chocolatey:
C:\> choco install nvm- instructions
- Node.js LTS 6.x.x + npm - Install via NVM:
C:\> nvm install 6.10.3
After installing and configuring all of the above listed software and accounts, continue to Step 1.
Step 1 - Sign in to GitHub and create a new project repository
Sign into GitHub and create a new repository for your Bot Framework project code. Upload your existing Node.js bot code, or copy any sample from the Microsoft/BotBuilder-Samples/Node project and upload the relevant files to your new GitHub repository. We will use this repository to configure Continuous Deployment for the Azure App Service. Once you have your bot code uploaded to GitHub, continue to the next step.
Step 2 - Create new app via the Azure Portal
Login to the Azure Portal with your MSA account and take a look at the left side menu. At the top click on the “+ New” button and a blade menu will slide out to the right. From there we can take a look at the App Service Options.
Step 3 - Select Web App on Linux (Preview)
Deploying your Node Bot to the Linux app service will give you a few advantages such as Node.js version control, Docker integration and more options that we will cover later in this article.
Step 4 - Configure app name and resource group
In the next step, set your bot app short name, which will be used as part of your Azure URL. Additionally, I recommend setting a new Resource Group per bot that you create. This will keep all of your bot’s resources under a single tag, and you can be confident to controll only the objects related to this bot. For example, when creating multiple bots, it’s good to know I can delete or reconfigure one bot via the resource group, without affecting any other projects.
Step 5 - Configure Node.js version
Click on “Configure Container” at the bottom of the Web App create menu. Here you will see the available Node.js versions by clicking on the “Runtime Stack” dropdown menu. At the time of this writing, the Long Term Support (LTS) version of Node.js runtime is version 6.x.x so we will select the highest available version from the dropdown menu. Node will be updated regularly, so don’t be surprised if there are newer version not mentioned in this article. As always, Node and NPM versions need to synced up, so whenever there is a Node/npm update in the app service, don’t forget to update the “engines” attributes of your bot’s
Step 6 - Create app and pin to the Azure dashboard
Complete the process by checking the “Pin to dashboard” checkbox, and click “Create”.
Step 7 - Confirm new app created successfully
After any loading messages and notifications complete, you will see your app status overview page which provides options to stop and restart your app, as well as the public URL, FTP information and request/error monitoring widget.
Step 8 - Select deployment options
The next step is to configure Continuous Deployment via GitHub. Under the Deployment menu, click on “Deployment options”.
From the “Deployment source” menu click on “Choose Source”. In the next menu, select “GitHub” as your source option.
In the “Deployment source” menu, you will see options to select your account, repository, and branch you want to deploy. If this is your first time connecting to GitHub, you will be asked to confirm OAuth permissions for GitHub to interact with and share data with your Azure account. Finally, click “OK” to save your deployment source configuration.
After you click “OK” your deployment will begin to download the lates files from GitHub and install them into your Web App container.
Now that Continuous Delivery is configured, pushing new code to your GitHub repository will trigger a rebuild and redeployment or your bot!
You can monitor bot deployments via the Deployment Options view in the Azure Portal.
Step 9 - Register your bot app on the Bot Framework Portal
Navigate to the Bot Framework Portal at https://dev.botframework.com/ and signin with your MSA account. Once you are signed in, click on “Register a bot” in the top menu.
On the next screen, in the “Bot profile” section, you can upload a custom icon to help users identify your bot. Underneath the icon, enter your bot’s name as it will appear in your channel, for example Skype. The bot name is the public name that your users will see. Next set the bot handle, this is the name you will use to reference your bot in your code. Finally, add a short description that gives your users a basic overview of your bot’s functionality or intended purpose.
Scroll down and set your bot’s messaging API endpoint. This will be the domain name you setup in Azure App Service plus the route
/api/messages. In this example, our messaging endpoint is
After setting the messaging endpoint, click the button that says “Manage Microsoft App ID and password”. This will open a new browser tab on
https://apps.dev.microsoft.com where you will see your App name and App ID. Just below the App ID, click the button “Generate New Password”.
A popup window will appear that contains your App password. Save the password and App ID to a secure location such as One Note for future reference. You will not see this information again, so it’s very important that you save this information as you will need to refer to it in later configuration steps.
Finally, click “Finish and go back to Bot Framework”. You will be redirected back to the Bot Framework Portal page to finish the bot configuration.
You will see that the Bot Portal has populated your App ID in the Configuration section. Verify the “Admin” configuration section has your correct email address under “Owners”, click the “agree to terms” checkbox, and click “Register” to complete the new bot registration process.
A popup window will alert you that the bot was created successfully. Click “OK” and you will now see the bot properties page.
Step 10 - Add your App ID and password to the Azure App Service configuration settings
Now that you have registered your bot on the Bot Portal, we will use the App ID and password you saved earlier to configure our Azure App settings. Navigate back to https://portal.azure.com, open your app overview page and select “Application settings” from the left menu. Under “App settings”, add a new key-value pair for your
MICROSOFT_APP_ID and one for the
MICROSOFT_APP_PASSWORD. Paste in the keys you saved from the registration step, and click the “Save” button at the top.
Now that we have configured the App ID and password, we need to restart our bot app for the changes to take effect. Click on “Overview” in the left menu and click “Restart” at the top. After the app restarts it is time to verify our bot is connected via the Bot Portal.
Step 11 - Test the connection to your bot app in the Bot Framework Portal
In the Bot Portal configuration page for your new bot you will see a section called “Test connection to your bot”. Click the “Test” button. If everything is working correctly you will see the text “Accepted” appear just under the “Test” button. In the WebChat window to the right, type a message to your bot. The bot will respond with “Greetings! I am a demo bot.”, followed by a choice menu which will display some example message types. Congratulations! Your new bot deployment is now online and working correctly.
Now that you have setup your bot’s project repository, and successfully configured Continuous Deployment via Azure App Service, checking in new code to GitHub will automatically trigger a redeployment of your bot. You can now proceed to channel configuration and further iterate on your bot’s core functionality.
Nils Whitmont from the Bot Framework Team