Debug with the emulator

The Bot Framework Emulator is a desktop application that allows bot developers to test and debug their bots, either locally or remotely. Using the emulator, you can chat with your bot and inspect the messages that your bot sends and receives. The emulator displays messages as they would appear in a web chat UI and logs JSON requests and responses as you exchange messages with your bot. Before you deploy your bot to the cloud, run it locally and test it using the emulator. You can test your bot using the emulator even if you have not yet created it with Azure Bot Service or configured it to run on any channels.


Connect to a bot running on localhost

Emulator UI

To connect to a bot running locally, click Open bot or select you preconfigured configuration file (a .bot file). You don't need a configuration file to connect to your bot, but the emulator still works with one if your bot has one. If your bot is running with Microsoft Account (MSA) credentials, enter these credentials too.

Emulator UI

Use bot credentials

When you open the bot, set the Microsoft App ID and Microsoft App password if your bot is running with credentials. If you created your bot with the Azure Bot Service, the credentials are available on the bot's App Service, under the Settings -> Configuration section. If you do not know the values, you can remove those from the locally running bot's configuration file, then run the bot in the Emulator. If the bot isn't running with these settings, you don't need to run the emulator with the settings either.

View detailed Message Activity with the Inspector

Send message to your bot and the bot should respond back. You can click on message bubble within the conversation window and inspect the raw JSON activity using the INSPECTOR feature to the right of the window. When selected, the message bubble will turn yellow and the activity JSON object will be displayed to the left of the chat window. JSON information includes key metadata including channelID, activity type, conversation id, the text message, endpoint URL, etc. You can inspect activities sent from the user, as well as activities the bot responds with.

Emulator Message Activity

Save and load conversations with bot transcripts

Activities in the emulator can be saved as transcripts. From an open live chat window, select Save Transcript As to the transcript file. The Start Over button can be used any time to clear a conversation and restart a connection to the bot.

Emulator save transcripts

To load transcripts, simply select File > Open Transcript File and select the transcript. A new Transcript window will open and render the message activity to the output window.

Emulator load transcripts

Add services

You can easily add a LUIS app, QnA knowledge base, or dispatch model to your bot directly from the emulator. When the bot is loaded, select the services button on the far left of the emulator window. You will see options under the Services menu to add LUIS, QnA Maker, and Dispatch.

To add a service app, simply click on the + button and select the service you want to add. You will be prompted to sign in to the Azure portal to add the service to the bot file, and connect the service to your bot application.


Adding services only works if you're using a .bot configuration file. Services will need to be added independently. For details on that, see Manage bot resources or the individual how to articles for the service you're trying to add.

If you are not using a .bot file, the left pane won't have your services listed (even if your bot uses services) and will display Services not available.

LUIS connect

When either service is connected, you can go back to a live chat window and verify that your services are connected and working.

QnA connected

Inspect services

With the new v4 emulator you can also inspect the JSON responses from LUIS and QnA. Using a bot with a connected language service, you can select trace in the LOG window to the bottom right. This new tool also provides features to update your language services directly from the emulator.

LUIS Inspector

With a connected LUIS service, you'll notice that the trace link specifies Luis Trace. When selected, you'll see the raw response from your LUIS service, which includes intents, entities along with their specified scores. You also have the option to re-assign intents for your user utterances.

QnA Inspector

With a connected QnA service, the log will display QnA Trace, and when selected you can preview the question and answer pair associated with that activity, along with a confidence score. From here, you can add alternative question phrasing for an answer.

Login to Azure

You can use Emulator to login in to your Azure account. This is particularly helpful for you to add and manage services your bot depends on. See above to learn more about services you can manage using the Emulator.

To login

Azure login

To login

  • You can click on File -> Sign in with Azure
  • On the welcome screen click on Sign in with your Azure account You can optionally have Emulator keep you signed in across Emulator application restarts.

Azure login

Disabling data collection

If you decide that you no longer want to allow the Emulator to collect usage data, you can easily disable data collection by following these steps:

  1. Navigate to the Emulator's settings page by clicking on the Settings button (gear icon) in the nav bar on the left side.

    disable data collection

  2. Uncheck the checkbox labeled Help improve the Emulator by allowing us to collect usage data under the Data Collection section.

    disable data collection

  3. Click the "Save" button.

    disable data collection

If you change your mind, you can always enable it by re-checking the checkbox.

Additional resources

The Bot Framework Emulator is open source. You can contribute to the development and submit bugs and suggestions.

For troubleshooting, see troubleshoot general problems and the other troubleshooting articles in that section.

Next steps

Saving a conversation to a transcript file allows you to quickly draft and replay a certain set of interactions for debugging.