Automatically start a chatbot conversation

  • Article

Important

Power Virtual Agents capabilities and features are now part of Microsoft Copilot Studio following significant investments in generative AI and enhanced integrations across Microsoft Copilot.

Some articles and screenshots may refer to Power Virtual Agents while we update documentation and training content.

You can configure your bot to start a conversation conversation with a user. You can also combine the customized greeting with customization to the look and feel of the bot.

Important

Having the bot start the conversation will show up in your analytics and will 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.

By default, chatbots created with Microsoft Copilot Studio and published to a website will load without a greeting, and will passively wait for the user to start the conversation.

However, you can use custom CSS and JavaScript code to automatically have the bot start the conversation when the bot loads. For example, you could have your bot say, "Hi, I'm Botty, a virtual agent" as soon as the bot loads.

First, you'll need 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.

Important

You may install and use the sample code included in this documentation only for use with the Microsoft Copilot Studio product. 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.

Retrieve token endpoint

To customize your canvas, whether it's the default canvas or a custom one you connect to, you need to retrieve your bot details.

  1. In the navigation menu under Settings, select Channels.

  2. Select Mobile app.

    Screenshot of the mobile app channel tile.

  3. Next to Token Endpoint, select Copy.

    Screenshot of the endpoint token id.

Customize the default canvas (simple)

Configure how the chat canvas looks with some simple CSS and JavaScript styling options.

First, you need to configure where you're deploying your bot canvas.

  1. Create and publish a bot.

  2. Copy and paste the HTML code below and save it as index.html.
    You can also copy and paste the code below into the w3schools.com HTML try it editor. You'll still need to add your token endpoint.

    <!DOCTYPE html>
<html>
<head>
    <title>Contoso Sample Web Chat</title> 
    <!-- This styling is for the Web Chat demonstration purposes. It is recommended that style is moved to a 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 id="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>

  3. In the index.html file you created, enter your token endpoint at the line var theURL = "<YOUR TOKEN ENDPOINT>";.

  4. Open index.html using a modern browser (for example, Microsoft Edge) to open the bot in the custom canvas.

  5. 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 = "<YOUR TOKEN ENDPOINT>", and surrounded by double quotation marks (").

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.

If you modify or create a new greeting topic, it's a best practice to include some sort of identification that the user is talking to a bot (or "virtual agent"), so they don't think they're talking to a human.

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

  1. In the navigation menu, select Topics, then select the Greeting topic row.

    Screenshot of the Topics page, with the Greeting topic highlighted.

  2. Edit the text inside the Message nodes. You can also add or delete additional nodes.

  3. Select Save.

  4. Publish your bot.

You can now test your bot by going to the webpage 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. For more information, see the topic Analyze billed session information.

  1. In the navigation menu, select Topics.

  2. Select New topic, and give it a name.

  3. Add the text inside the Message node.

  4. Select Save when you've finished editing the message.

  5. In the navigation menu, select Topics, then select the Greeting topic row.

  6. Delete the message nodes on the Greeting topic.

  7. To automatically divert the bot to a user topic, select Add node (+) to add a node, and then Go to another topic.

  8. In the flyout menu, select the user topic you created above.

  9. Select Save when you've finished editing the message.

  10. Publish your bot.

You can now test your bot by going to the webpage where you deployed your bot's custom canvas. You'll see the bot start the conversation by automatically showing the new topic.