Make your Power Virtual Agents bot start the conversation using a custom canvas

Diganta Kumar, Principal Product Manager, Conversational AI, 20 เมษายน 2563

One of the topmost asks from Power Virtual Agents customers is to make a bot start the conversation. Customers want their bot to greet their users before they ask any questions. For example, a bot begins a conversation by saying, “Hi, I’m Botty, a virtual agent”.

In this blog, you can learn how to do that using a custom canvas. First, you’ll learn how to deploy a custom canvas that includes arguments that trigger the greeting. By default, the custom canvas calls the default system greeting topic. You can, however, create a new topic to be used as the greeting, although you will need to divert the default system greeting topic to a new topic.

Information: Having the bot start the conversation will show up in your analytics and increase your session count. If the user of your bot doesn’t engage with the bot (for example, they load the page but don’t ask the bot anything), the session will be marked as an unengaged session. This might impact your analytics.

You can also combine the customized greeting with customization to the look and feel of the bot.

Deploy a custom canvas for your bot

To make your bot start the conversation, you’ll need to deploy a custom canvas that includes arguments that cause the default system greeting topic to be displayed when the bot loads.

Create and publish a bot.
In the navigation menu under Settings, select Channels.
Select Mobile app.
Next to Token Endpoint, select Copy.
Copy-paste the HTML code below and save it as index.html.
In the index.html you created, enter your Token Endpoint at the line var theURL = "<BOT TOKEN ENDPOINT>".
Open index.html using a modern browser (for example, Edge) to open the bot in the custom canvas.
Test the bot to ensure you are receiving responses from your bot and that it’s working correctly. If you encounter problems, make sure you’ve published your bot, and that your Token Endpoint has been inserted in the correct place. It should be after the equals sign (=) at the line var theURL, and surrounded by double quotation marks (“).

Alternately, you can copy and paste the code below into the w3schools.com HTML try it editor to see how it works (remember to add your Bot ID).

<!DOCTYPE html>
<html>
<head>
    <title>Contoso Sample Web Chat</title> 
    <!-- This styling is for the canvas demonstration purposes. It is recommended 
that style is moved to separate file for organization in larger projects -->
    <style>
        html, body {
            height: 100%;
        }
        body {
            margin: 0;
        }
        h1 {
            font-size: 16px;
            font-family: Segoe UI;
            line-height: 20px;
            color: whitesmoke;
            display: table-cell;
            padding: 13px 0px 0px 20px;
        }
        .heading {
            background-color: black;
            height: 50px;
        }
        .main {
            margin: 18px;
            border-radius: 4px;
        }

        div[role="form"]{
            background-color: black;
        }        
        #webchat {
            position: fixed;
            height: calc(100% - 50px);
            width: 100%;
            top: 50px;
            overflow: hidden;
        }
      </style>
</head>
<body>
    <div>
        <div class="heading">

            <!-- Change the h1 text to change the bot name -->    
            <h1>Contoso Bot Name</h1>

        </div>
        <div id="webchat" role="main"></div>
    </div>    
  <script src="https://cdn.botframework.com/botframework-webchat/latest/webchat.js"></script>
  <script>
        const styleOptions = {
           // Add styleOptions to customize web chat canvas
           hideUploadButton: true
        };

        // Add your BOT token endpoint below
        var theURL = "<BOT TOKEN ENDPOINT>";

        var environmentEndPoint = theURL.slice(0,theURL.indexOf('/powervirtualagents'));
        var apiVersion = theURL.slice(theURL.indexOf('api-version')).split('=')[1];
        var regionalChannelSettingsURL = `${environmentEndPoint}/powervirtualagents/regionalchannelsettings?api-version=${apiVersion}`; 

        var directline;
            fetch(regionalChannelSettingsURL)
                .then((response) => {
                    return response.json();
                    })
                .then((data) => {
                    directline = data.channelUrlsById.directline;
                    })
                .catch(err => console.error("An error occurred: " + err));

      fetch(theURL)
            .then(response => response.json())
            .then(conversationInfo => {
                window.WebChat.renderWebChat(
                    {
                        directLine: window.WebChat.createDirectLine({
                            domain: `${directline}v3/directline`,
                            token: conversationInfo.token,
                        }),
                        styleOptions
                    },
                    document.getElementById('webchat')
                );
            })
            .catch(err => console.error("An error occurred: " + err));
    </script>
  </body>
</html>

Change the bot’s default greeting

The code in the index.html file causes a topic to be called automatically when the bot is loaded. By default, it calls the system greeting topic. You can also create a new topic and divert the default system greeting topic to that new topic.

In both instances, you make changes to the topic you want to call as you would normally.

We recommend you modify the system greeting topic so that you don’t have to edit the index.html code.

Modify a system topic (recommended)

Select Topics in the side navigation pane.
Under System Topics, select the Go to authoring canvas icon on the Greeting topic row.
Edit the text inside the Message boxes. You can also add or delete additional nodes.
Select Save when you’re finished editing the message.
Publish your bot.
You can now test your bot by going to the web page where you deployed your bot’s custom canvas. You’ll see the bot start the conversation by automatically showing the greeting topic.

Create a new user topic

Warning: Using a user topic to start a conversation will increase your billed sessions. A billed session is an interaction between a customer and a bot and represents one unit of consumption. The billed session begins when a user topic is triggered. More information: Licensing guide.

Select Topics on the side navigation pane.
Select New topic, and give it a name.
Select Go to authoring canvas.
Add the text inside the Message node.
Select Save when you’ve finished editing the message.
Select Topics again on the side navigation pane.
Under System Topics, select the Go to authoring canvas icon on the Greeting topic row.
Delete the message nodes on the Greeting topic.
To automatically divert the bot to a user topic, select + to add a node, and then Go to another topic.
In the flyout menu, select the user topic you created above.
Select Save when you’ve finished editing the message.
Publish your bot.
You can now test your bot by going to the web page where you deployed your bot’s custom canvas. You’ll see the bot start the conversation by automatically showing the new topic.

You can also find additional documentation here.

We’d love to hear your feedback. Please visit our community forum at https://aka.ms/PowerVirtualAgentsForum and share your feedback.

And submit your idea requests at https://aka.ms/PowerVirtualAgentsIdeas.

Disclaimer

You may install and use the sample code included in this documentation only for use with the Microsoft Power Virtual Agents service. The sample code is licensed “as is” and is excluded from any service level agreements or support services. You bear the risk of using it. Microsoft gives no express warranties, guarantees, or conditions and excludes all implied warranties, including merchantability, fitness for a particular purpose, and non-infringement.