For the purpose of this blog (4th post in the series on Power Virtual Agent) and just to avoid any confusion, when I mention “BF Bot”, it is the bot built with the bot framework. And bots built with the Power Virtual Agent (PVA) will be called as PVA bot.
I want to start this post by quickly talking about the Bot Framework as we really cannot talk about the innards of PVA without touching on the Bot Framework. If you have to build a BF Bot, you need to setup Dialogs, LUIS, Dispatches and this is a significant undertaking compared to what PVA offers. PVA essentially abstracts everything in the name of Topic.
At the end of the day, when you create a PVA Bot, PVA framework is building a bot with all the bells and whistles using the bot framework and dresses up in a way to look less daunting to the bot authors. Just by understanding this concept of PVA is nothing but a sugar coated framework to help us create a bot without us having to understand all the intricacies of the bot framework opens up some significant possibilities.
The Bot Framework provides something called Direct Line REST API for anyone to access the bots directly – which means we can even access the PVA Bots with this Direct Line REST API. This concept of using Direct Line API to access the PVA just opens up a world of possibilities in terms of extending the PVA Bot’s behaviour. Let’s explore what this means in detail. Strap yourself in.
Embed the bot built with Bot Framework on a Webpage
Let’s say we hire a developer to build a bot with the bot framework and deploy it in azure. The developer will setup a Bot Channel Registration and as part of that, Web Chat channel will be setup.
The developer clicks on “Edit” next to the Webchat channel to navigate to the page below to retrive the Embed code. Before using the embed code, the developer typically updates it with the Secret Code as shown below.
So, this iframe is what enables the end user who is visiting our webpage to interact with the BF Bot. This iframe is powered by a humble “Webchat” – a component part of the Bot Framework family that provides the chat interface to interact with the BF Bot. When we setup the Webchat channel in the Azure, all we are doing is to connect to the Webchat hosted by default by Microsoft. This Webchat abstracts all the communication protocols, the message transfers, uploading the file etc.,
If you come this far in the post, you would already be very familiar with this interface – the Chat interface. Infact the Webchat is an open source Bot Framework component and you can get all the details about the Webchat in this github link.
If you just run the above webchat code (artifact 4), you got yourself a custom Webchat component that you can host yourself and can be used instead of the “Embed Code” that we get from Bot Channel Registration in Azure (artifact 2).
Bot + Direct Line Api + Webchat
As I mentioned before, you can access the bot created using the Direct Line Rest API. The Direct Line API allows us to pass the message typed by the end user and get the reply back from the bot etc.,
The Webchat is essentially using the Direct Line API to perform the same actions and it is all abstracted with the “renderWebChat” method. Note that Direct Line API is also offered as .net nuget package and node.js
Let’s see if we can run the above webchat code (artifact 4). I need to update the DIRECT LINE TOKEN in the above webchat code (artifact 4) to run it. In order to get the Direct Line Token, I need to retrieve the Secret Key (Artifact 2) and do a postman request like shown below:
And you get the below result with the Direct Line Token.
Paste this token in the above webchat html code (artifact 4) and run it. You will see the chat interface taking over the whole html page and you can interact with the BF Bot directly in this interface. My simple bot just echoes my message.
Now, let’s turn our attention to the Power Virtual Agent portal.
PVA Bot + Direct Line Api + Webchat
Once you create a new PVA Bot, publish and click on “Custom Website” in the Channels section, you will see a page similar to the one below:
Notice the Embed code in the above image. It actually uses the Webchat component in order to access the PVA Bot.
This Webchat is specifically hosted for the PVA Bots. I can say this because the PVA Bots do not have an upload capability, where as the Webchat that is hosted for the BF Bots has the upload capability (as seen in the previous section).
But the overall Webchat component is the same and the decision to enable/disable the upload capability or styling the webchat are all just configuration settings if you decide to host your own Webchat (Refer artifact 4 – webchat code)
If we are convinced that the PVA actually works on top of the bot framework, we should be able to access the PVA Bots using the Direct Line API just like how we accessed the BF Bots.
Obviously, the above code (artifact 4 – webchat code) doesn’t quite work yet because we need to update the code with the DIRECT LINE TOKEN. But, we do not have access to the Bot Channel Registration for the PVA Bots. So, how are we going to test this out?
It turns out, PVA exposes an API through we can retrieve the Direct Line Token to access the underlying bot provided we pass the Bot ID and Tenant ID.
You can get the Bot ID and the Tenant ID by
- Publish your PVA Bot.
- Go to Channels -> Demo website
- Copy the link shown on the page to access the PVA Bot.
- cci_bot_id=efdd83f3-f524-b087-2bfffc84a53d & cci_tenant_id=d9ac162-4fc8-965c-0e1ef92e80f1. This is the Bot id and the Tenant id.
Just a quick GET request on the browser will give you the direct line token:
Now, use this token in the same webchat code (artifact 4), and you will see the chat interface coming alive on the html page. Bingo! you are able to chat with the PVA Bot.
In the above figure (artifact 12), if you notice keenly, you will see an ability for us to attach a file, whereas out of the box webchat offered by the PVA doesn’t have it, it is because, the webchat deployed by the PVA team has this feature disabled.
You can use the StyleOptions of the Webchat in order to enable/disable settings. If you set the hideUploadButton to true, then it hides the upload capability on the webchat.
Obviously if you enable the upload button, you need to also handle the entire upload functionality within your hosted webchat code.
This is an important understanding. Now, what we have learnt so far is that we can pretty much influence how the webchat looks and feels and even add functionalities if we are ready to host our webchat. This opens up a lot of possibility with PVA.
Enabling and disabling the upload functionality is just one of many. You can find all the available style option settings here: https://github.com/microsoft/BotFramework-WebChat/blob/master/packages/component/src/Styles/defaultStyleOptions.js
Also, as you are able to directly access the underlying bot using the Direct Line REST API, you can even change some of the behavior of the PVA Bot.
Modifying the bot’s behaviour
Currently, when the PVA Bot is launched, the bot will wait for the user to start the conversation. But let’s say we want the bot to start the conversation. Let’s see how to do that:
Get a new Direct Line Token (by following the artifact 12), update it in the below code (artifact 14 – Greet user) and run it.
This starts the conversation with simulating the user typing “hello”. This way, when the user launches the bot, it welcomes automatically without the user having to initiate a conversation by typically typing “hello”. The number 1 best practice as indicated in my previous blog states that “When the customer launches the bot, it is your first opportunity to onboard the customer. Greet the customer and at the same time set the expectation what they can expect from the bot”. So, here you have it.
Modifying the style of the chat
Let’s say that you want to customize the color of the message bubbles to suit your website branding. This can be achieved by simply adding StyleOptions.
Use the below code (artifact 16) in your webchat to influence the message bubble colors.
There are 2 important notes here:
- Understanding that Direct Line API can be used to access the PVA Bot opens up amazing new possibilities. This idea is what allows us to integrate the PVA Bot with the BF Bot.
- If you are ready to host the webchat yourself, then you are significantly upping the game as to how your PVA Bot can look and behave.
For fun, just type “help” in this link to get inspired by some of the possibilities of the Webchat UI customizations. This does not stop here; as you have the Direct Line API access capability within the Webchat, you can add new behaviors to the bot such as automatic user location detection, speech recognition, cognitive services integration etc.,
This is best of both the worlds. We are using PVA’s interface to setup the actual bot without having to worry about all the details that go into developing the bot with the bot framework, but when we find PVA bot not supporting the functionalities that the business needs out of the box, we can host the webchat to directly access the underlying bot using Direct Line API.
That’s all for the day. Hope this exploration added value to your understanding on where the PVA bot fits in with the overall bot framework and opened up different perspectives and possibilities for extension and customization.