Experimenting and Learnings

Blog about learning from design and coding

Creating a bot through Microsoft Bot Framework Pt.1

Earlier this year in 2016, Microsoft released a Bot Development Framework which was designed to be a single framework to create Bots / Conversational UI across multiple surfaces (ex. Skype, Slack, Facebook messenger, and more). I decided to give it a shot recently and realized along the way that while there are great documentations online, you need to scavenge and jump around different sources to get a complete (and up-to-date code) view of how to initially get things rolling. For someone like myself who's never used Node.js, never deployed a web app to a cloud service, and never created a bot, it took some time to set everything up. As the first part of my experience with the Bot Framework, I created this article as a note-for-self (and others like me) to easily get things started in the future. There were lots of great articles I referenced and this is meant to be a single page cheatsheet of what worked for me.

Step 0. Tools & Preparation

  1. Node.js
    There are multiple ways to build bots using the Bot Framework, including Node.js / C# / REST API. I decided to use Node.js because of my familiarity with Javascript. I had no prior experience with Node.js.
    - Follow this link to install Node.js and npm
  2. Bot Framework
    This is a framework created and provided by Microsoft. There isn't any file to download other than installing components later through Node.js. You will need to create a Microsoft account to be able to register a bot for development.
    - Create Microsoft Account
  3. Text Editor
    For editing code. There are many options available, including
    - Brackets
    - Visual Studio Code
  4. Cloud service to host the bot
    The bot you create will need to be deployed and hosted as a web app on a cloud service. Through this, you will also be able to obtain the Endpoint URL needed when registering a bot here later. I chose to use Azure, which is a Microsoft cloud service, to host the bot.
    - Sign up for Azure
  5. Way to deploy bot code to a cloud service (Azure in this case)
    As you make updates to the bot code, updates need to be deployed to the cloud service to take effect. Azure provides an easy way to detect updates made to a number of other cloud services and automatically deploy them. GitHub, a popular code repository, is one of the options that's supported by Azure and easy to integrate.
    - Create a GitHub Account
  6. Tools to test the bot
    - Download the bot emulator (for Windows only)
    - Download ngrok

Step 1. Creating a repository on GitHub

Having a repository for the bot code on GitHub is convenient to automatically deploy updates to Azure as your bot evolves. Follow the following steps to create a new repository.

  1. Go to github.com and select New Repository
  2. Set repository name as testbot
  3. It can be either public or private repository. It doesn't impact the integration with Azure.
  4. Click on Add .gitignore and select Node (Screenshot below).
  5. Create repository
  6. Copy the git url (ex. https://github.com/MYUSERNAME/testbot.git) and clone it on your local hard drive. You can do this through a command line interface or through a GitHub desktop application. For someone new to GitHub or git, desktop application might be the easier option. Once you login in the GitHub desktop application, you can find the option to Clone and you will be able to find the project testbot you just created in steps 1-5.
  From github.com on October 2016

From github.com on October 2016


Step 2. Using Node.js to pull in Bot Framework and required libraries to your project

1. Open command line prompt (On Windows, type in cmd in the search box. On Mac, type in terminal), and go to the directory of the GitHub project you just cloned onto the local hard drive (For example, C:\Users\Steve\Desktop\testbot).

> (Cursor blinking in the project directory)

2. Once you are in the directory, type in

> npm init

This command kicks off the process to automatically create package.json, which manages information about the project including dependencies you will add in later. When the code is uploaded to Azure's cloud service, Azure will take a look at the package.json file to detect what the dependencies are install them.

3. Command line prompt will walk you through a number of questions. Fill out each line and press enter. Important thing to note is making sure entry point is set to app.js / index.js / or server.js. This relates to how Azure automatically detects that the project is a Node.js project when there is a file of this name.

> name: testbot
> version: (1.0.0)
> description: "Type in your description"
> entry point: app.js
> test command: (leave blank)
> git repository: (this should point to the git url. ex,  https://github.com/MYUSERNAME/testbot.git)
> keywords: bot, botframework
> author: (Your Name)
> license: (ISC)
> Is this ok? (yes)

4. npm is also used to installed required libraries in the dependencies. We have two dependencies currently: botbuilder which is the bot framework from Microsoft, and restify which is is a framework for building REST APIs. Type in the following four commands

> npm install --save botbuilder
> npm install --save restify
> npm install --save https
> npm install --save express

Now your project folder should include additional files including node_modules folder which contains the dependencies you just installed.

Step 3. app.js for defining the bot

Create a new file named app.js at the root of the project folder and add the following code in. This is based off of Bot Framework V3. You can also clone / download it from a GitHub project.

// START OF CODE==============================================

var restify = require('restify'); //this is loading the library installed earlier
var builder = require('botbuilder'); //this is loading the library installed earlier

// Setting up server, connector, and bot

// Setup Restify Server
var server = restify.createServer();
server.listen(process.env.port || process.env.PORT || 3978, function () {
   //When testing on a local machine, 3978 indicates the port to test on
   console.log('%s listening to %s', server.name, server.url); 
// Create chat bot
// MICROSOFT_APP_ID and MICROSOFT_APP_PASSWORD are created when you register a bot at https://dev.botframework.com/bots 
// I will walk through how to add them as a process.env variables in a next step.
var connector = new builder.ChatConnector({
    appId: process.env.MICROSOFT_APP_ID,
    appPassword: process.env.MICROSOFT_APP_PASSWORD
var bot = new builder.UniversalBot(connector);
server.post('/api/messages', connector.listen());

// Defining how bot carries on the conversation with the user

bot.dialog('/', function (session) {
    session.send("Hello World");

// END OF CODE================================================


Step 4. Setting up a Web App on Azure for REST Endpoint

We need to setup a Web App on Azure to create a REST Endpoint for the bot connector and also integrate the GitHub project into this Web App so new updates will be automatically deployed to the Azure server whenever you push an update to the GitHub repository.

Step 4A. Let's begin with creating the Web App on Azure

1. Go to Azure portal page
2. Click or New
3. Search for and select Web App

4. Choose Create
5. Fill out the required fields. It is important to make the App name field unique, but it doesn't have to exactly match the name of the Node.js project in GitHub. The Resource Group doesn't necessarily have to be unique.

6. Once a new Web App has been created, go to Application setting page and decide whether you want to enable Always On or not.
7. Go to the Overview page and copy the URL. For example, if your app name were testbot, the URL will read http://testbot.azurewebsites.net .
This URL will be used in the next step when registering a bot.

Step 4B. Link the project repository on GitHub with Azure for automatic deployment

1. Go to the this bot's Web App page on Azure Portal
2. Search for Deployment options page.
3. There will be options to link a GitHub project as the source for automatic deployment.

Step 5. Registering bot to get App ID and Password

To have app.js working properly, you need to register the bot to get App ID and password.

1. Go to Bot Framework site and click on Register a Bot
2. Fill out the required fields. Bot handle will be used in the URL of your bot, but is different from the URL you copied from Azure. In the Messaging Endpoint field, insert the URL copied from Azure and append it with api/messages. Keep in mind that this is case-sensitive. For example, Messaging Endpoint can read  http://testbot.azurewebsites.net/api/messages
3. In the Configuration section, use the helper provided to create the App ID and password. Make sure to copy the password somewhere because it will not be accessible from the website later on.

4. Click on Register to complete the process.

Step 6. Updating app.js with App ID and Password

Now that you have the App ID and password from registering the bot, you need to place them in app.js . There are 3 ways to do it.

Step 6A. Place it in the code app.js

Place the values in single quotes when initializing var connector. This is the simplest way to get things set up, but it leaves the secret app password vulnerable and exposed.

/*In app.js*/
var connector = new builder.ChatConnector({
    appId: 'Place app id here',
    appPassword: 'Place app password here'

Step 6B. Place it as an environment variable in Azure server

1. Open your Web App in Azure portal
2. Open the Web App's Application settings and scroll to App settings section

3. Create a key MY_APP_ID and put in the app id as its value. Do the same for MY_APP_PASSWORD.

4. What you entered in the previous step are accessible with the prefix process.env like below.

      var appId = process.env.MY_APP_ID,
      var appPassword = process.env.MY_APP_PASSWORD;

5. Update app.js to be following so that the app password is not exposed.

      /*In app.js*/
      var connector = new builder.ChatConnector({
          appId: process.env.MY_APP_ID,
          appPassword: process.env.MY_APP_PASSWORD

6. Push all changes to the GitHub repository for this project.

After all the new updates are deployed on Azure, go to your bot's page in dev.botframework.com and try the Test button. If everything is set up correctly, it should return the message Accepted.

Step 7. Test the bot with emulator (Windows)

Things are ready to go now. You can test the bot from local device or from Azure.

Step 7A. Testing bot on local device

  1. From the project directory, type in
    node app.js
    using the command prompt.
  2. Open Bot Framework Channel Emulator
  3. In Bot URL fieldtype in http://localhost:3978/api/messages
    "3978" can be replaced with another port number defined in app.js
  4. Enter Microsoft App Id and Microsoft App Password with the app id and password from bot registration.
  5. Begin chatting with your bot.
  6. Make sure that appId and appPassword values in are accessible in app.js (If these values are saved in Azure server, they wouldn't be accessible and will cause an unauthorized error in the emulator).

Step 7B. Testing bot deployed in Azure

  1. Copy ngrok.exe into the project root folder on local hard drive.
  2. From the command line prompt, type in
    ngrok http -host-header=rewrite 9000
    It will come back with an output similar to below. Without this step, you wouldn't see the response coming back from the bot in the emulator.

3. Copy the url that shows up for Forwarding (7th item from the top). For example, https://0c4736ab.ngrok.io from the example above.
4. Open Bot Framework Channel Emulator
5. In Emulator Url field, type in the url from step 3. For the Local Port field, use 9000.
6. In Bot URL field, type in the Messaging Endpoint indicated in the bot registration. For example, http://testbot.azurewebsites.net/api/messages
7. Enter Microsoft App Id and Microsoft App Password with the app id and password from bot registration.
8. Begin chatting with your bot.

This should set up the basic environment to get a bot up on a server with a conversation channel open with the user.

* These are opinions of my own and do not reflect opinions from Microsoft.