Transcripts with Microsoft Bot Framework v4

For those that have been working with conversational interfaces namely bots, both developers and business users, have at some point come across the term transcript. So what is a "bot transcript file"?

According to docs.microsoft.com,
"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, etc. All of this information can then be used to help find and resolve issues when testing or debugging your bot."

If we look closely at this definition, we can see that a transcript is much more than just contents of messages exchanged between user and bot. It contains a lot more information in it's raw form. Thereby, it is quite evident that a transcript has use for both business users and developers.

How can a business user use a transcript file?

• Replay conversations to understand user behavior.
• Analyze conversational flow that can be used as input for improving bot behavior.
• If conversation feedback is enabled, it is possible to correlate where the conversation flow went wrong.

How can developers use a transcript file?

• Correlate telemetry with conversations.
• Use recorded conversations for testing and debugging

So, as a developer how do you enable transcripts in your bot? On a very high level, these are the steps you must take to enable transcripts on a bot built from the "core bot" template available from Microsoft.

• Create a container in a Azure Blob Storage Account. This container will store your transcripts.
• In Startup.cs, create the TranscriptStore to store activities and the TranscriptLoggerMiddleware to log activities to the TranscriptStore. TranscriptLoggerMiddleware is available as part of the Microsoft Bot Framework v4. It is also possible to write your own middleware if you want to do more than standard offered with Transcript Logging.
• Use the TranscriptLoggerMiddleware in the BotFrameworkAdapter

Startup.cs

public class Startup
    {
        private readonly AzureBlobTranscriptStore _myTranscripts;
        private readonly IConfiguration _config;
         public Startup()
        {
            // connects transcript storage pointer _myTranscripts to your Azure blob transcript storage account
            _myTranscripts = new AzureBlobTranscriptStore("<your-blob-transcript-storage-account-string>", "<your-blob-transcript-container-name>");
        }
         // This method gets called by the runtime. Use this method to add services to the container.
        public void ConfigureServices(IServiceCollection services)
        {
            ...
            // Create the TranscriptStore
            services.AddSingleton<ITranscriptStore>(_myTranscripts);
            // Create the TranscriptLoggerMiddleware to log all activities to the TranscriptStore
            services.AddSingleton<IMiddleware, TranscriptLoggerMiddleware>(serviceProvider =>
            {
                return new TranscriptLoggerMiddleware(_myTranscripts);
            });
             ...
         }
    }

In AdapterWithErrorHandler.cs, add the following to use the Transcript Logger

Use(new TranscriptLoggerMiddleware(transcriptLogger));

After the above configuration has been made, all new conversations are now added to the Transcript Store that we created in the Azure Blob Storage Account. So, how does the transcript store structure the transcripts and how do you find your way around it.
The following is a schematic representation of the transcript store that will help you traverse the data and get relevant information from transcripts as needed.

As can be seen in the diagram above, due to the stateless nature of the bot, we see that the transcript-logger aggregates individual activities under a channel and conversation structure. However, for effectively using correlations, we have to find a way to combine the activities. Also, individual activities are logged as JSON, which to business users are not completely meaningful. Business users wanted to have a way to replay the entire conversation in a friendly manner and not browse through thousands of lines of JSON.

To tackle this, I created a tool that goes through the entire transcript store and creates a ".transcript" file combining the activity JSONs. The idea is to then consume this ".transcript" file in the Microsoft Bot Framework Emulator.
The Bot Framework Emulator allows business users to view the entire conversation in a conversational manner while developers can use the inspect capabilities to inspect other data that is part of the transcript. Developers can of course also look into the raw JSON for troubleshooting and debugging purposes.

Source code to generate transcripts is available in GitHub at https://github.com/royarin/Bot-Framework under CreateTranscripts.

This piece of code is created to generate transcripts on demand using a supplied "conversationId" and to download the generated transcript to local system directly. The conversationId for correlation purposes can be easily obtained from telemetry sent to Application Insights. Remember, a conversation is akin to a user session. Therefore when looking for "conversationId" in your telemetry data, this is nothing but the unique session_id.