BotFramework-Emulator/content/CHANNELS.md

Getting started with the Bot Inspector

jump to Bot State Inspection

Prerequisites

• A bot configured in Azure configured to use the additional channels. (Microsoft Teams, etc).
• The latest Emulator

TL;DR

1. Update your Emulator to be on version 4.5. You can do this by selecting Help -> Check for Update...
2. Install ngrok and navigate to the ngrok executable's location in a terminal.
3. Update your bot's code
4. Run ngrok ./ngrok http 3979 --host-header=localhost
5. Open your bot in the Azure Portal, select the Settings blade and paste the ngrok url provided in the terminal into the Messaging Endpoint field then save. note: If necessary, don't forget to add the /api/messages endpoint.
6. Set the appropriate environment variables (prefix with EXPORT for OSX/Linux, SET for Windows):

NODE_ENV=development;
MicrosoftAppId=<your app id>;
MicrosoftAppPassword=<your bot's password>;

1. Run your bot: npm start
2. Open the respective channel's chat link provided in the Azure Portal in the Channels blade.
3. Open the Emulator and toggle to Bot Inspector mode via View -> Bot Inspector Mode
4. Connect to your locally running Bot by pasting the URL to the Bot's endpoint in the connection modal. note: if configured with an external channel you may need to supply your Microsoft App Id & Microsoft App password.
5. Copy the /INSPECT attach <UUID> command rendered in the Conversation window and paste it into your configured channel's chat.

Run Your Bot in an external Channel and observing with the Bot Framework Emulator

If you have configured your bot to run in 1 or more channels and would like to test a locally running bot using the Emulator while interacting with it in a communication app (Teams, Skype, Slack, WebChat, etc.), these instructions will show you how.

Note: Since chat messages, Adaptive Cards, and other features have notable differences across the many available channels, the Emulator cannot visually recreate all experiences at this time. Instead, the Emulator provides the inspection of channel-specific protocol data and internal bot state as each turn context executes throughout the conversation within a channel.

How it works

The tunneling software ngrok is used to create a tunnel to your locally running bot. The tunnel's URL is provided to your Web App bot in Azure. You build your bot with the BotBuilder 4.4 InspectionMiddleware, and run it locally, chatting with it in Teams or another configured channel. The Emulator will receive the conversation's message exchange as usual, and some internal bot state information now being exposed through this middleware.

Let's get Started

If you haven't already, get the latest Emulator, ngrok and update your bot's dependencies to use BotBuilder v4.4+

1. Update Your Bot's Code

Your bot will need to configure the Bot Inspector middleware in order to connect to and send the conversation exchange to the Emulator. Include the InspectionMiddleware in your Bot's middleware stack:

const { MemoryStorage, UserState, ConversationState, InspectionState, InspectionMiddleware } = require('botbuilder')
const { MicrosoftAppCredentials } = require('botframework-connector')

let memoryStorage = new MemoryStorage();
let inspectionState = new InspectionState(memoryStorage);

let userState = new UserState(memoryStorage);
let conversationState = new ConversationState(memoryStorage)

let credentials = undefined;
if (process.env.MicrosoftAppId && process.env.MicrosoftAppPassword) {
  credentials = new MicrosoftAppCredentials(process.env.MicrosoftAppId, process.env.MicrosoftAppPassword);
}

// Do not forget to provide your MicrosoftAppId & MicrosoftAppPassword in the InspectionMiddleware constructor parameters
adapter.use(new InspectionMiddleware(inspectionState, userState, conversationState, credentials, process.env.MicrosoftAppId, process.env.MicrosoftAppPassword))

2. Run ngrok

Open a terminal instance and run ngrok with the following command to create a new tunnel (you may need to navigate to where the ngrok executable lives on your filesystem) the port specified is the same port your bot is running on:

OSX

./ngrok http 3978 --host-header=localhost

Windows

"ngrok.exe" http 3978 --host-header=localhost

Save the https entry generated by ngrok to your clipboard.

3. Update Azure to Point to the Tunnel

In the azure portal, navigate to your bot's settings and paste the url provided by the ngrok terminal in the Messaging endpoint field and save the changes. Do not forget to use /api/messages. It's best to create a Bot in Azure that is used specifically for this purpose. Do not overwrite the messaging endpoint of a deployed production bot.

4. Set the appropriate environment variables in your Bot's running process & start the Bot

MicrosoftAppId=<your app id>;
MicrosoftAppPassword=<your bot's password>;

Node

node index.js

C#

dotnet run

5. Connect to a Channel & start a conversation in it

If you haven't already done so, connect your bot to a channel. You may also need to download and install the app associated with the channel if you have't already. Afterwards, open the respective chat link provided in the Azure Portal in the Channels blade.

6. Start up the Emulator

Open the Emulator if it isn't open already.

7. Connect to your locally running Bot

Connect to your bot by selecting Open Bot and provide the appropriate fields. Select the "Open in debug mode" checkbox. Don't forget the MicrosoftAppId & MicrosoftAppPassword if configured to use an external channel.

8. Copy the /INSPECT attach <UUID> command rendered in the Conversation window and paste it into the configured channel's chat

A successful connection to the bot with the InspectionMiddleware configured will render the text that you see above. We need to save this text and paste it in to the channel you intend to have the conversation in. You can do this few ways. The easiest is by right-clicking on the rendered message and selecting "Copy text" from the context menu.

9. Have conversation in external channel

Have a normal conversation with your Bot in your configured channel, and while doing so you will see information populating in your connected conversation in the Emulator.

Note: You can also have a normal conversation with your bot in the Emulator directly, by connecting to the bot via traditional means (Open Bot) and not selecting the "Open in debug mode" checkbox.

Bot State Inspection

The Bot Inspector now renders the Bot State for each Turn Context executed in the Bot's runtime. You can view this by selecting the Bot State element rendered in the Conversation control and then clicking the View diff button in the inspector panel that appears. At this point you can toggle between Bot States, seeing the state diff across each turn.

Have fun! And please provide any feedback by filing a new issue on the Bot Framework Emulator Github Project