Share via

Microsoft Bot Framework Part 1: Getting Started

  • Article

One of the many big announcements made at Microsoft’s //BUILD conference in March was Microsoft’s brand new “Bot Framework.” They did this cool demonstration of how to build an automated bot that could order pizza for you just by typing messages to it in plain English!

Image of a pizza-ordering Dominoes bot talking to a user.

I have been working on building Bots using the Microsoft Bot Framework. Today I’m going to share my experience surrounding the bots I’ve been putting together, and the basics of what you need to know about building them.

What I used

Microsoft Bot Framework is a powerful tool that makes it easy to create a single back end and then publish to a bunch of different platforms called Channels. You can use any of the following to get started:

I used Node.js, for the ease of using lightweight text editors and command line interfaces with speedy download times.
If you're more of a Visual Studio 2015, C# or .NET fan, Kat Harris has a great set of posts about how to use the Bot Connector Template for Visual Studio.

Install the Tools 

For the sake of brevity, I’m going to assume you already have a few things:

To use the Microsoft Bot Framework Connector, you must have:

  1. A Microsoft Account to log into the Bot Framework developer portal, used to register your Bot.
  2. An Azure-accessible REST endpoint exposing a callback for the Connector service. (I’ll show you how.)
  3. Developer accounts on one or more communication services (such as Slack) where your Bot will communicate.

Set up a GitHub repository

First, go to GitHub.com, log in, and click the '+' in the top right to create a new repository. Give it a name and a short description. Make it public. Initialize with a README. Set .gitignore to add "Node," and set license to 'ISC' if you want.
Click Create repository. Copy to clipboard the URL from GitHub. (You may need to click “Clone or download” to see URL.)

See my GitHub repos for Hello World Bot and Weather Bot completed code.

Obtain a GitHub repo from a URL

Open up Node.js command prompt, navigate to the folder directory you wish to clone into. (“dir” shows all folders.) The following instructions show you how to CLONE from a repository with files already in it; you do NOT need to CREATE a new folder for your bot:

 >C:\git
>git clone [url from newly created github repository with files in it]
>cd folder-name
>git status
>code README.md

[Make changes to the ReadMe file, then save.]

 >git add .
>git commit -m "Updated ReadMe"
>git push origin master

Type in your username and password to authenticate pushing to GitHub.
Refresh GitHub online repo to see changes made.

Set up a project with a package.json File

Back in Node.js Command Prompt, run npm init in your folder:

 >npm init

[This utility will walk you through creating a package.json file. Make your Entry Point "app.js".]

 >name: lowercase-letters-only
>version: (1.0.0)
>description: "Build a bot in Node.js on Microsoft Bot Framework."
  >entry point: app.js
>test command: (leave blank)
>git repository: (default)
>keywords: bot, slack, whatever
>author: (Your Name)
>license: (ISC)
>Is this ok? (yes)

Watch this screenshot gif to see how.

[video width="676" height="600" mp4="https://msdnshared.blob.core.windows.net/media/2016/06/CGR_123456.mp4"][/video]

Install Dependencies

Get the BotBuilder and Restify modules using npm. Do the same for any other modules you want, such as a RESTful API.

 >npm install --save botbuilder
>npm install --save restify

I plan on uploading this project onto Microsoft Azure. Making a file called server.js or app.js (or index.js) will automatically cause Azure to recognize it as a Node.js app. Azure will immediately look for a package.json file and install all dependencies listed therein. Make sure package.json is up-to-date with your dependencies before you publish to Azure.
The entry point for the app should be at the main folder level.

 >explorer .

[Opens Windows Explorer in the current folder]

 >code .

[Opens VS Code in the current file. Check to see dependencies are accurately opening.]

Write the app.js File

Once you have those configured, we can create an app.js file that will setup our application.

In the Node.js cmd prompt, type:

 >cls>app.js

[Creates a file called “app.js” in your file explorer. Edit this through VS Code.]

Let's just start by saying hello in a few lines of code.

  // Add your requirements
var restify = require('restify'); 
var builder = require('botbuilder'); 

 // Setup Restify Server
var server = restify.createServer();
server.listen(process.env.PORT || 3000, function() 
{
   console.log('%s listening to %s', server.name, server.url); 
});

 // Create chat bot
var connector = new builder.ChatConnector
({ appId: 'YourAppId', appPassword: 'YourAppPassword' }); 
var bot = new builder.UniversalBot(connector);
server.post('/api/messages', connector.listen());

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

If you want to save your changes so far and push the new files to your repo, you can either use Visual Studio Code to commit and push to GitHub (see screenshot gif), or type these steps into Node.js Command Prompt:

 >git status
>git add .
>git commit -m "Created package.json and app.js"
>git push origin master

Type in your username and password to authenticate pushing to GitHub.
Refresh GitHub online repo to see changes.

Watch this screenshot gif to see how to push changes to GitHub straight from VS Code:

  1. Type in a Commit message in the message box
  2. Click the check mark icon or hit Ctrl+Enter to commit a local git change
  3. Click the “…” icon for the option to Sync, Pull, or Push to GitHub.

[video width="800" height="570" mp4="https://msdnshared.blob.core.windows.net/media/2016/06/GitVS_123.mp4"][/video]

Set up a Microsoft Azure App Service

You’ve probably noticed that you need to do something about that appId: 'YourAppId', appPassword: 'YourAppPassword' code. The AppId is chosen and the AppPassword is generated when your Bot is registered with the Microsoft Bot Framework Connector.

When you fill out the registration form, you’ll need to have deployed a web app to Azure to get your Endpoint URL.

Let’s jump over to https://portal.azure.com, and sign in with a Microsoft Account to take care of that now.

How to create a Microsoft Account and Azure Subscription:

[video width="678" height="600" mp4="https://msdnshared.blob.core.windows.net/media/2016/06/CMA_CAS_11223.mp4"][/video]

By default, the bot should be published as a Microsoft Azure App Service.

Click on “App Services” in the left blue bar, then click on “Add +”. Fill out the form to create a Web App service. Give it a unique name (preferably what you want YourAppId to be), set the default resource group, app service plan, and server location, using your Azure subscription. (Don’t have one? You can get a free trial from here: https://azure.microsoft.com/en-us/)

Click “Create” when you’re done. The URL assigned to this new web app will be YourAppId.azurewebsites.net. Save this URL for later.

How to create an Azure-accessible REST endpoint exposing a callback for the Connector service:

[video width="678" height="600" mp4="https://msdnshared.blob.core.windows.net/media/2016/06/CWS_123.mp4"][/video]

Register a Bot

Go to www.botframework.com. (Sign in with your Microsoft Account here, too.)

Click on “Register a Bot” and fill out the registration form following the site’s instructions.

Copy and paste the URL you saved from your Azure portal into the “Endpoint” field. Prefix the URL with “https” instead of “http”. Add “/API/Messages” to the end of the pasted URL. Azure will take care of providing HTTPS support on your bot.

(CAUTION: this endpoint URL is CaSe SeNsItIvE! Writing "API/Messages" in one place and "api/messages" in another will break your project!)  

You can use https://aka.ms/privacy if you need a quick privacy URL. You can use your GitHub repository ReadMe URL as your bot’s website.

When you get to the bottom of the form, under Config Info, type in a new AppID of your own choosing.

Click on “Register” and hit “OK!”

Take note of your newly generated AppPassword and YourAppId.

Watch this screenshot gif to see how.

[video width="678" height="600" mp4="https://msdnshared.blob.core.windows.net/media/2016/06/CBR_1234567.mp4"][/video]

Keep your App ID and your AppPassword handy while you click on Microsoft Bot Framework's Documentation. In the table of contents, you can search for "Bot Builder for Node.js" > "Getting Started" to view Microsoft's documentation on making conversational bots using Node.js. This is where I found the above "Hello World" code.

In your app.js code, swap out 'YourAppId' and 'YourAppPassword' for the values that you just generated by registering your bot.

[video width="674" height="600" mp4="https://msdnshared.blob.core.windows.net/media/2016/06/CNB_1.mp4"][/video]

Test your bot (Windows Only)

Use the Bot Framework Emulator to test your bot on https://localhost:3000/api/messages.

Install the emulator from here and then start your bot in the Node.js command prompt window.

 >node app.js

Start the emulator, enter your AppId, AppPassword, and the localhost REST endpoint, and say “hello” to your bot. (Note that the first request after your Bot starts up can take 20-30s as Azure starts up the web service for the first time. Subsequent requests will be quick.) This simple viewer will let you see the JSON object returned by your Bot.

Check out Microsoft Bot Framework Part 2 for more info on how to protect your code secrets by using Environment Variables and complete a Hello World bot!

Comments

  • Anonymous
    August 10, 2016
    Hi,i am able to post my sample project on azure and if test connection in bot registration page i am getting 'ok' response.actually my problem is i am not getting reply from BOT if i type 'hi' it should give 'Hello world' but it's not working.-thanks
  • Anonymous
    October 04, 2016
    When trying to test my connection to the bot...I have appended /api/messages correctly as far as i can i don't see the error BUT i keep getting "NotFound The resource you are looking for has been removed, had its name changed, or is temporarily unavailable." error. ;-(
    • Anonymous
      April 26, 2017
      Did you find a solution? I have the same problem... Thank youArbi