Add a Copilot Studio copilot to Azure Bot Service channels


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 connect your copilot to existing Azure Bot Service channels. This can be helpful if you want to connect your copilot to end users on Azure Bot Service channels.

Adding your copilot to Azure Bot Service channels requires considerable developer expertise. This article is written for IT admins or developers who have experience developing and writing code.


You do not need to follow this document to add your Microsoft Copilot Studio copilot to your website, Facebook, or Microsoft Teams. If your goal is to connect to a custom web-based or native app, your developers can learn more at Add copilot to mobile and custom apps.


Instructions in this section require software development from you or your developers. It is intended for experienced IT professionals, such as IT admins or developers who have a solid understanding of developer tools, utilities, and IDEs.


Code samples

Code snippets used in this document are from relay bot sample code.


The instructions in this document reference the following:

Create or use an existing Azure Bot Service bot

You need an Azure Bot Service bot that can relay conversations between your Microsoft Copilot Studio copilot and Azure Bot Service channels.

Relay bot diagram.

The relay bot sample code is a good starting point if you do not have an existing Azure Bot Service bot. It is built from Microsoft Bot Framework bot sample code that can be compiled and deployed to the Azure Bot Service. The sample code is meant to be used as a starting point and not intended to be used in production directly. You will need to add code and optimization to match your business needs.

If you already have an Azure Bot Service bot, you need to add a Microsoft Copilot Studio connector and code to manage conversation sessions. You can then deploy the bot to the Azure Bot Service and connect to channels with the Azure portal.

Get your Microsoft Copilot Studio copilot parameters

To connect to the copilot you have built with Microsoft Copilot Studio, you'll need to retrieve your copilot's name and token endpoint.

  1. Copy your copilot's name in Microsoft Copilot Studio.

    Get bot name.

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

  3. Select the channel you want to connect to. This scenario uses Slack as an example.

    Slack channel.

  4. To copy and save the Token Endpoint value, select Copy. You'll need your endpoint to connect your copilot to the Azure Bot Service channel.

    Get bot parameters.

Manage conversation sessions with your Microsoft Copilot Studio copilot

There can be multiple conversations between the Azure Bot Service channels and the Direct Line connection with your Microsoft Copilot Studio copilot.

Your Azure Bot Service bot will need to map and relay the conversation from the Azure Bot Service channel to the Direct Line conversation with the Microsoft Copilot Studio copilot and vice versa.

Sample code example

The following example uses samples from the relay bot sample code.

  1. On every new external Azure Bot Service channel conversation start, start a Microsoft Copilot Studio conversation. Refer to Get Direct Line token and Use Direct Line to communicate with the bot for instructions on starting a new conversation with the bot.

    using (var httpRequest = new HttpRequestMessage())
        httpRequest.Method = HttpMethod.Get;
        UriBuilder uriBuilder = new UriBuilder(TokenEndPoint);
        httpRequest.RequestUri = uriBuilder.Uri;
        using (var response = await s_httpClient.SendAsync(httpRequest))
            var responseString = await response.Content.ReadAsStringAsync();
            string token = SafeJsonConvert.DeserializeObject<DirectLineToken>(responseString).Token;
    /// <summary>
    /// class for serialization/deserialization DirectLineToken
    /// </summary>
    public class DirectLineToken
        public string Token { get; set; }
     // Use the retrieved token to create a DirectLineClient instance
     using (var directLineClient = new DirectLineClient(token))
         var conversation = await directLineClient.Conversations.StartConversationAsync();
         string conversationtId = conversation.ConversationId;
  2. To manage multiple sessions, you need to maintain a mapping of external Azure Bot Service channel conversations to corresponding Microsoft Copilot Studio conversations. A Microsoft Copilot Studio conversation can be identified with and connected with two properties: ConversationtId and Token.

    Dictionary<string, PowerVirtualAgentsConversation> ConversationRouter = new Dictionary<string, PowerVirtualAgentsConversation>();  

    To manage the conversation lifecycle, refresh the Direct Line tokens or clean up idled conversations. Learn more about token refresh at Refresh Direct Line token. A Microsoft Copilot Studio conversation to support those is defined as following:

    /// <summary>
    /// Data model class for Microsoft Copilot Studio conversation
    /// </summary>
    public class PowerVirtualAgentsConversation
        public string ConversationtId { get; set; } // The Microsoft Copilot Studio conversation ID retrieved from step 1
        public string Token { get; set; } // The DirectLine token retrieved from step 1
        public string WaterMark { get; set; } // Identify turn in a conversation
        public DateTime LastTokenRefreshTime { get; set; } = DateTime.Now; // Timestamp of last token refresh
        public DateTime LastConversationUpdateTime { get; set; } = DateTime.Now; // Timestamp of last active user message sent to copilot
  3. When a new Microsoft Copilot Studio conversation starts, add a key value pair (external_Azure_Bot_Service_channel_conversationID, PowerVirtualAgentsConversation) to the mapping table.

    // After new Microsoft Copilot Studio conversation starts
    ConversationRouter[external_Azure_Bot_Service_channel_conversationID] = new PowerVirtualAgentsConversation()
        Token = token,
        ConversationtId = conversationId,
        WaterMark = null,
        LastConversationUpdateTime = DateTime.Now,
        LastTokenRefreshTime = DateTime.Now,
  4. To continue on an existing conversation, upon a new external Azure Bot Service channel message received, retrieve the existing conversation from the mapping table, relay the external conversation activity to your Microsoft Copilot Studio copilot, and get a response.

    The following sample shows relaying conversation by overriding the ActivityHandler.OnMessageActivityAsync((ITurnContext<IMessageActivity>, CancellationToken) method

    // Invoked when a message activity is received from the user
    // Send the user message to Microsoft Copilot Studio copilot and get response
    protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
        // Retrieve copilot conversation from mapping table
        // If not exists for the given external conversation ID, start a new Microsoft Copilot Studio conversation
        ConversationRouter.TryGetValue(externalCID, out PowerVirtualAgentsConversation currentConversation) ?
                currentConversation : /*await StartBotConversationAsync(externalCID)*/;
        // Create DirectLine client with the token associated to current conversation
        DirectLineClient client = new DirectLineClient(currentConversation.Token);
        // Send user message using directlineClient
        await client.Conversations.PostActivityAsync(currentConversation.ConversationtId, new DirectLineActivity()
          Type = DirectLineActivityTypes.Message,
          From = new ChannelAccount { Id = turnContext.Activity.From.Id, Name = turnContext.Activity.From.Name },
          Text = turnContext.Activity.Text,
          TextFormat = turnContext.Activity.TextFormat,
          Locale = turnContext.Activity.Locale,
        // Update LastConversationUpdateTime for session management
        currentConversation.LastConversationUpdateTime = DateTime.Now;
  5. Refer to Use Direct Line to communicate with the bot for how to get the Microsoft Copilot Studio copilot's response. When the Microsoft Copilot Studio copilot's response is received, refer to Parse conversation payload from the copilot for how to parse the response to the external Azure Bot Service channel response.

An example of response parsing can be found in the relay bot sample code ResponseConverter.cs.

Deploy to Azure Bot Service

After you have your Azure Bot Service relay bot ready, you need to deploy the bot to your Azure Bot Service.

Set up Azure Bot Service channels

You can set up the channels you want to connect to by signing in to the Azure portal and selecting the Azure Bot Service resource group you have deployed to. View the specific instructions for each channel at Azure Bot Service Channels.