Microsoft Bot Framework Part 1: Getting Started
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!
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:
- Bot Connector
- Bot Builder C#
- Bot Builder Node.js
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:
- Node.js (at least version 0.10) with git commands and NPM installed.
- A GitHub account.
- A text editor (My screenshots will be showing Visual Studio Code).
- A Microsoft Account (Hotmail, Live, Outlook.Com).
- An Azure subscription (Not yet? Free trial: https://azure.microsoft.com/en-us/)
- A communication service like Skype, Slack, or the web.
To use the Microsoft Bot Framework Connector, you must have:
- A Microsoft Account to log into the Bot Framework developer portal, used to register your Bot.
- An Azure-accessible REST endpoint exposing a callback for the Connector service. (I’ll show you how.)
- 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:
- Type in a Commit message in the message box
- Click the check mark icon or hit Ctrl+Enter to commit a local git change
- 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.