Pass Parameters to Copilot Studio Bot from Calling Site

Pass Parameters to Copilot Studio Bot from Calling Site

When building a Copilot there are times when we need to be able to pass context to the Copilot to improve the user experience by passing data that could be helpful in greeting the customers or retrieving customer information ahead of time. Microsoft has provided some documentation on how to accomplish this when building Copilots using Copilot Studio. Let's look at how we can implement this with an example.

Configuring Global Variables as Parameters

Update: Based on the comment from Karishma in the comments section, there is now an even simpler and cleaner approach recommended by Microsoft. Below is a simple example of a variable configured using the recommended approach as described here.

Note: The original method described below still works but it's easier to use the above approach

To configure a global variable that we can use as a parameter we need to define it in a Topic. I have a simple demo Copilot created and added a blank topic where I can set the variable value to some random value that will never get assigned. Currently this is the only way I could find in defining a global variable that will only be used to get data into the Copilot during the startup. Ideally if we have a way to just declare a global variable without having to set a value that would be cleaner. Here are the steps in detail.

Create blank Topic in Copilot

I'm just going to call this Topic, Parameter Config and set the trigger to empty.

Set a Global Variable in Topic

Let's create a new variable name and edit the properties after it's created by clicking on the variable. Make sure to check External sources can set values.

Similarly, I'm going to create another variable called issueType. This would be useful in situations where we want to apply branching logic and show context aware actions based on the issue or any criteria that applies to the Copilot use case.

Our Topic would look like below once everything is configured. The variable value doesn't matter, and we can set it to anything.

Let's save our Topic. We can now use these variables as parameters and expose them appropriately or use them as needed within the Topic to either apply branching logic or just display the value.

Next, I am going to update the system Conversation Start Topic to modify the initial greeting message and display the user's name and also apply branching criteria.

I have already created another Topic called Activation and going to start this Topic based on the issueType.

My Activation Topic is configured as below.

I have saved all the changes and published our Copilot. Let's enable the authentication settings to use it in the channels. This step is optional depending on your use case.

Configure Manual Authentication

Depending on the use case we might sometimes need to configure Authentication for the Copilot to perform actions that return private or sensitive data. This is very straightforward to setup under the Authentication section (Settings->Security). Microsoft also has documentation that explains this in detail.

Configure single sign-on with Microsoft Entra ID - Microsoft Copilot Studio
Enable your bot to authenticate an already-signed-in user

I have configured my authentication as below.

Using Copilot in Custom Website

Now that we have configured the settings, let's go the Custom website (Settings-> Channel) section to get the URL to the Copilot.

I copied the above URL and included the global variables as query parameters we have configured in our Copilot as below.{ENV_ID}/bots/{BOT_SCHEMA_NAME}/webchat?__version__=2&name=Joe&issueType=activation

Now if we open this URL, we will see the below page that requests us to Login when using authentication. If we do not have the authentication enabled, we will not see the login prompt.

After the login, we should now see our bot displaying the name we passed in the URL and also branching the logic using the issueType parameter.

Hopefully this gave you some ideas on how you could leverage global variables to provide context-based actions at the start of your Copilot. Let me know your thoughts in the comments below.