README.md

Intelligent Chatbot Workshop

Preparations

Download and install

• NodeJS
• BotFramework Emulator
• Visual Studio Code (recommended, not required)

Azure registration

If you're not already registered, use one of the following links to create a free Azure account:

• Azure free account for Students (no credit card required)
• Azure free account (requires credit card)

Bot Setup

Go to portal.azure.com and log in with your Microsoft Account. You should now see the Azure Portal.

Create free app service plan

Click on Create a resouce (top-left corner) and search for App Service Plan. Select and click Create and fill out the details.

• App Service plan: an arbitrary name (you'll need it later)
• Subscription: select your free subscription
• Resource Group: Create new and an arbitrary name (you'll need it later)
• Operating System: Windows
• Location: West Europe
• Pricing tier: Click on it, select Dev / Test in the header of the new window and choose the free F1 plan. Click apply ;)
• Create

On the left side you can find the navigation bar. Click on the New button and search for Web App Bot. Click on the entry followed by a click on the Create button (which you can find in the lower left corner). Next you are asked for some basic bot properties.

• Bot name: should be lowercase without any whitespaces (think about a unique bot name ;))!
• Subscription: select your free subscription
• Resource group: select Create new and enter something related to your bot's name
• Location: West Europe
• Pricing tier: F0 (free)
• App name: should be automatically generated by Azure
• Bot template: SDK v3 and Language understanding (NodeJS) (click on entry to select and confirm selection by clicking Select)
• App service plan/Locations: Click on the entry, select your previously created app service plan and click Ok
• Azure Storage: select Create new and use default name
• Application Insights Location: West Europe
• In Microsoft App ID and Passowrd click on Auto create App ID and Password

Confirm the checkbox, also check out Pin to dashboard and click on the Create button.

Now we need to wait some seconds until Azure has succesfully created your bot. You will see a notification on the upper right corner within the Azure Portal if the bot instance has been successfully created. If so, you should also see a new entry on the Azure Portal Dashboard with your bot's name. Click it! The following view should appear.

To receive your bot's code, go to Build on the left navigation bar and click on Download zip file.

Unzip the downloaded file open the directory with Visual Studio Code.

First thing to do after we opened the bot's project in VSCode is to update the package.json file. Therefore click on View -> Integrated Terminal. The terminal window should popup at the bottom of your editor. Next execute the following commands:

npm i

npm i -s mvgapi

Next we need to provide our LUIS credentials. Open app.js file and have a look for the following code:

var luisAppId = process.env.LuisAppId;
var luisAPIKey = process.env.LuisAPIKey;
var luisAPIHostName = process.env.LuisAPIHostName || 'westus.api.cognitive.microsoft.com';

Extend these two lines of code such that we provide a fallback if no env variables are passed:

var luisAppId = process.env.LuisAppId || '<YourLuisAppId>';
var luisAPIKey = process.env.LuisAPIKey || '<YourLuisAPIKey>';
var luisAPIHostName = process.env.LuisAPIHostName || 'westeurope.api.cognitive.microsoft.com';

Replace <YourLuisAppId> and <YourLuisAPIKey> with your personal credentials. You can find them at the Azure Portal! Go back to your browser and navigate to the Application Settings of your bot. By scrolling a little bit down and you will see the environment variables LuisAPIKey and LuisAppId. Besides get the LuisAPIHostName URL and change it in the code.<>

The same need to be done to provide the microsoft app id and app password. Search for

var connector = new builder.ChatConnector({
    appId: process.env.MicrosoftAppId,
    appPassword: process.env.MicrosoftAppPassword,
    openIdMetadata: process.env.BotOpenIdMetadata
});

and also provide a fallback

var connector = new builder.ChatConnector({
    appId: process.env.MicrosoftAppId || '<YourMicrosoftAppId>',
    appPassword: process.env.MicrosoftAppPassword || '<YourMicrosoftAppPassword>',
    openIdMetadata: process.env.BotOpenIdMetadata
});

Again, replace <YourMicrosoftAppId> and <YourMicrosoftAppPassword> with your personal credentials which are also provided by Azure Portal Application Settings.

We are nearly done! But before testing, we need to remove some lines of code. Search for

var botbuilder_azure = require("botbuilder-azure");

and remove or comment out this line. Do the same for the following code lines:

var tableName = 'botdata';
var azureTableClient = new botbuilder_azure.AzureTableClient(tableName, process.env['AzureWebJobsStorage']);
var tableStorage = new botbuilder_azure.AzureBotStorage({ gzipData: false }, azureTableClient);

bot.set('storage', tableStorage);

Save your changes and head over to the integrated terminal. Execute the following command to start our bot:

node app.js

If the bot started successfully, there should be something like

restify listening to http://[::]:3978

on the console output.

Next start the BotFramework Emulator and enter the follwoing url http://localhost:3978/api/messages. Furthermore, we need to provide the Microsoft AppID and AppPassword (again you can find them either in the Azure Portal or app.js file). Click connect and test your bot!

Your are now ready to implement your bot conversations and features. For testing purposes, you need to stop and start the bot again by clicking into the integraded terminal window, pressing STRG + C and again executing node app.js.

If your bot is ready for release, you can simpy run

node publish.js

and the bot is automatically uploaded to Azure (don't worry, this process can take 1-2 minutes until changes are deployed).

Further information

Some sample code for a small and easy language understanding bot can be found here.

The official documentation of the Microsoft Bot Framework is also a good reference for a quick look.

LUIS

On eu.luis.ai you can handle your LUIS intent and entity recognizers.

You'll see your LUIS App that was automatically created by Azure:

When you click on your app you can customize your intents and entities.

Bot Connector Setup

Of course we want to see our bot in action if our core features are implemented. The setup wizard for different bot platforms can be found under the Channels tab in the Azure Portal.

Just follow the instructions by clicking on a bot platform's entry.

MVG API

The documentation of the MVG API can be found here.

Contributors

• Yannick Stachelscheid (yss14)
• Martin Wepner (martinwepner)
• Johannes Jung (johannesjung)