Debug your bot using transcript files

  • Article

APPLIES TO: SDK v4

One of the keys to successful testing and debugging a bot is your ability to record and examine the set of conditions that occur when running your bot. This article discusses the creation and use of a bot transcript file to provide a detailed set of user interactions and bot responses for testing and debugging.

The bot transcript file

A bot transcript file is a specialized JSON file that preserves the interactions between a user and your bot. A transcript file preserves not only the contents of a message, but also interaction details such as the user ID, channel ID, channel type, channel capabilities, time of the interaction, and so on. All of this information can then be used to help find and resolve issues when testing or debugging your bot.

Creating/Storing a bot transcript file

This article shows how to create bot transcript files using the Bot Framework Emulator. Transcript files may also be created programmatically; see Blob transcript storage to read more concerning that approach. In this article, we'll use the Bot Framework sample code for Multi Turn Prompt Bot that requests a user's mode of transportation, name and age, but any code that can be accessed using Microsoft's Bot Framework Emulator may be used to create a transcript file.

To begin this process, ensure that the bot code you want to test is running within your development environment.

  1. Start the Emulator.

  2. On the Welcome tab, select Open Bot.

  3. Enter the address of the port to which your bot is listening, followed by /api/messages, for instance, http://localhost:3978/api/messages.

    If your bot is configured with a Microsoft app ID and password, enter the ID and password in the Open a bot dialog. Otherwise, the Emulator won't be able to connect to your bot.

  4. Select Connect to connect the Emulator to your bot.

    Screenshot of dialog for connecting to a bot from the Emulator.

Test your code by interacting with your bot in the Emulator. After you've entered all of the user interactions you want to preserve, use the Bot Framework Emulator to create and save a transcript file containing this conversation.

  1. In the Live Chat tab, select Save transcript.

    Screenshot of a conversation and the 'save transcript' button in the Emulator.

  2. Choose a location and name for your transcript file and select Save.

    Screenshot of the 'save conversation transcript' dialog.

All of the user interactions and bot responses that you entered to test your code with the Emulator have now been saved into a transcript file that you can later reload to help debug interactions between your user and your bot.

Retrieving a bot transcript file

When you open a transcript file, the Emulator loads the saved conversation into a new tab.

To retrieve a bot transcript file:

  1. Open the Emulator.
  2. From the menu, select File then Open Transcript.
  3. Use the Open transcript file to select and open the transcript file you want to retrieve.

Screenshot of the 'open transcript file' dialog.

Debug using transcript file

With your transcript file loaded, you're now ready to debug interactions that you captured between a user and your bot.

  1. Select any user or bot message, or activity recorded in the Emulator's log pane.

  2. The Emulator will display the activity information in the inspector pane. The activity information is the payload of the HTTP request for the activity.

    A message activity includes:

    • The activity type
    • The time the activity was sent from or received by the channel
    • Information about the user's channel
    • Information about the sender and receiver of the activity, in the from and recipient fields, respectively
    • Information specific to the type of activity, such as the message text for a message activity.

This detailed level of information allows you to follow the step-by-step interactions between the user's input and your bot's response, which is useful for debugging situations where your bot either didn't respond in the manner that you anticipated or didn't respond to the user at all. Having both these values and a record of the steps leading up to the failed interaction allows you to step through your code, find the location where your bot doesn't respond as anticipated, and resolve those issues.

Using transcript files together with the Bot Framework Emulator is just one of the many tools you can use to help you test and debug your bot's code and user interactions.

Additional information

For more testing and debugging information, see: