Automatically start an agent conversation

2025-05-21

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

Important

Having the agent start the conversation shows up in your analytics and increases your session count.

If the user of your agent doesn't engage with the agent (for example, they load the page but don't ask the agent anything), the session is marked as an unengaged session. This behavior might affect your analytics.

Web app
Teams

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

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

First, you need to deploy a custom canvas that includes arguments that trigger the greeting. By default, the custom canvas calls the predefined Greeting topic. You can, however, create a new topic to be used as the greeting. You divert the default Greeting topic to this new topic.

Important

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

Customize the default canvas

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.

Create and publish an agent.

Copy the following HTML code and save it to a file named index.html. Alternatively, copy and paste the code into the w3schools.com HTML try it editor.

<!DOCTYPE html>
<html>
<head>
    <title>Contoso Sample Web Chat</title> 
    <!-- This styling is for Web Chat demonstration purposes. For larger projects, we recommend you move style to a separate file -->
    <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 the token endpoint for your agent below
        var theURL = "<YOUR 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>

Retrieve the token endpoint for your agent.
In index.html, at the line var theURL = "<YOUR TOKEN ENDPOINT>", replace the placeholder with the token endpoint for your agent.
Open index.html using a modern browser (for example, Microsoft Edge) to open the agent in the custom canvas.
Test the agent to ensure you're receiving responses from it and that it's working correctly.

If you encounter problems, make sure you published your agent, and that the token endpoint is in the correct place. The token endpoint should be after the equals sign (=) at the line var theURL = "<YOUR TOKEN ENDPOINT>", and surrounded by double quotation marks (").

Retrieve the token endpoint for your agent

To customize your canvas, whether it's the default canvas or a custom one you connect to, you need the token endpoint for your agent.

In the navigation menu under Settings, select Channels.
Select Email. The configuration panel for this channel appears.
Next to Token Endpoint, select Copy.

Change the agent's default greeting

The code in the index.html file causes a topic to be called automatically when the agent is loaded. By default, the code calls the Greeting topic. You can also create a new topic and divert the default 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 the Greeting topic or create a new one, you should indicate that the user is talking to an agent (or "virtual agent"). Such an indication helps the user understand they aren't talking to a human.

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

Modify the predefined greeting topic (recommended)

Go to the Topics page for your agent and select the Greeting topic.
Edit the text inside the Message node. You can also add or delete nodes.
Select Save.
Publish your agent.

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

Create a new custom topic

Warning

Using a custom topic to start a conversation increases your billed sessions. A billed session is an interaction between a customer and an agent and represents one unit of consumption. The billed session begins when a custom topic is triggered. For more information, see Manage message capacity.

Go to the Topics page for your agent.
Select Add a topic > From blank.
Enter a name for your new topic.
Add a Message node and configure it with the desired message.
Select Save when you're done editing the message.
Go to the Topics page again and select the Greeting topic.
Delete all message nodes from the Greeting topic.
To automatically divert the agent to your new topic, add a Redirect node, with the new topic for the destination.
Select Save, and publish your agent.

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

Share via