Publish an agent to mobile or custom apps

You can connect your agent to a custom app so that the app's users can interact with the agent directly from within your app.

In most cases, your custom app is a mobile-device app that is either a web-based app or a native app. It can also be an adapter to other services that your business requires.

Different procedures exist for connecting to your mobile app, depending on whether your app is a web-based app or a native app.

Connecting your agent to a web-based app is relatively straightforward as it involves copying a code snippet into your app. However, both web-based apps and native or custom apps still require considerable developer expertise to fully integrate the agent into your app. This article describes both procedures.

Prerequisites

• .NET Core SDK version 2.1.
• NuGet package Microsoft.Bot.Connector.DirectLine.
• An agent created in Copilot Studio that you want to connect to your app.

Connect your agent to a web-based app

1. In Copilot Studio, in the navigation menu, select Channels.

2. Select the Mobile app tile to open the configuration window.

3. Copy the code under the Web-based apps section and provide it to your app developers to add to your web-based app.

   

Connect your agent to a native or custom app

If you want to connect to Azure Bot Service channels, see Publish an agent to Azure Bot Service channels.

References

The instructions in this document reference the following source material:

• Bot Framework Direct Line API
• Direct Line Authentication
• Context variables available upon handoff
• Microsoft Bot Framework Activity

Retrieve your Copilot Studio agent parameters

To connect to the agent you built, retrieve your agent's name and token endpoint to identify it.

1. In Copilot Studio, go to the Overview page of your agent, and copy your agent's name.

2. Select Channels > Mobile app.

3. On the Mobile app page, next to Token Endpoint, select Copy. You need this endpoint for the Get Direct Line token step.

   

Get Direct Line token

To start a conversation with your agent, you need a Direct Line token. Get this token by sending a GET request to the endpoint shown in the Copilot Studio screen. Use this token as the header for the next calls to the direct line API.

Example:

GET <BOT TOKEN ENDPOINT>

If the request is successful, the endpoint returns a Direct Line token, expiration time, and a conversationId for the requested agent.

Example:

{
    "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
    "expires_in": 3600,
    "conversationId": "abc123"
}

Get Direct Line token code example

The following example gets a Direct Line token for a Copilot Studio agent.

/// <summary>
/// Get directline token for connecting bot
/// </summary>
/// <returns>directline token as string</returns>
public async Task<DirectLineToken> GetTokenAsync(string url)
{
    try
    {
        return await _httpClient.GetFromJsonAsync<DirectLineToken>(url);
    }
    catch (HttpRequestException ex)
    {
        throw ex;
    }        
}

/// <summary>
/// class for serialization/deserialization DirectLineToken
/// </summary>
public class DirectLineToken
{
  public string Token { get; set; }
  public int Expires_in { get; set; }
  public string ConversationId { get; set; }
}

The response object is the same as the GET request you saw earlier.

{
  "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
  "expires_in": 3600,
  "conversationId": "abc123"
}

Use Direct Line to communicate with the agent

After retrieving the Direct Line token, you're ready to have a conversation with your Copilot Studio agent by using Direct Line. To start a conversation and send and receive messages, follow the instructions at Bot Framework Direct Line API.

The following example starts a conversation and sends and receives messages from a Copilot Studio agent.

1. Initialize a DirectLineClient instance with the Direct Line token and start a conversation:

      // 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. Once started, you can identify and connect to each conversation by using the combination of token and conversationtId. Send a user message to an existing conversation:

      // Use the retrieved token to create a DirectLineClient instance
      // Use the conversationId from above step
      // endConversationMessage is your predefined message indicating that user wants to quit the chat
      while (!string.Equals(inputMessage = /*Get_User_Input()*/, endConversationMessage, StringComparison.OrdinalIgnoreCase))
      {
          using (var directLineClient = new DirectLineClient(token))
          {
              // Send user message using directlineClient
              // Payload is a Microsoft.Bot.Connector.DirectLine.Activity
              await directLineClient.Conversations.PostActivityAsync(conversationtId, new Activity()
              {
                  Type = ActivityTypes.Message,
                  From = new ChannelAccount { Id = "userId", Name = "userName" },
                  Text = inputMessage,
                  TextFormat = "plain",
                  Locale = "en-Us",
              });
          }
      }
   

3. Retrieve the agent's response by using the same token and conversationId. The retrieved Direct Line response activities contain both the user's and agent's messages. You can filter response activities by your agent's name to get only the agent's response message.

      // Use the same token to create a directLineClient
      using (var directLineClient = new DirectLineClient(token))
      {
          // To get the first response set string watermark = null
          // More information about watermark is available at
          // https://learn.microsoft.com/azure/bot-service/rest-api/bot-framework-rest-direct-line-1-1-receive-messages?view=azure-bot-service-4.0
   
          // response from bot is of type Microsoft.Bot.Connector.DirectLine.ActivitySet
          ActivitySet response = await directLineClient.Conversations.GetActivitiesAsync(conversationtId, watermark);
   
          // update watermark from response
          watermark = response?.Watermark;
   
          // response contains set of Activity from both user and bot
          // To display bot response only, filter Activity.From.Name equals to your bot name
          List<Activity> botResponses = response?.Activities?.Where(x =>
                    x.Type == ActivityTypes.Message &&
                      string.Equals(x.From.Name, /*Bot_Name*/, StringComparison.Ordinal)).ToList();
   
          // Display botResponses
      }
   

Refresh Direct Line token

You might need to add code to refresh the Direct Line token if your application has a lengthy conversation with the agent. The token expires but can be refreshed before it expires. To learn more, see Direct Line Authentication.

The following example refreshes the token for an existing Copilot Studio conversation:

  // DirectLine provides a token refresh method
  // Requires the currentToken valid when refreshing
  string refreshToken = new DirectLineClient(currentToken).Tokens.RefreshToken().Token;
  // create a new directline client with refreshToken
  directLineClient = new DirectLineClient(refreshToken);
  // use new directLineClient to communicate to your bot

Parse conversation payload from the agent

After you start a conversation with the agent, the conversation JSON payload uses the standard Microsoft Bot Framework Direct Line activity. To learn more, see Bot Framework Direct Line API.

Handle handoff activity

If your application needs to hand off to a live agent provider, you need to handle the handoff activity. The handoff activity is sent when the Transfer to agent node is hit. You can learn more on the payload of the handoff activity.

Trigger a welcome message

To have your agent automatically send the Greeting system topic when a user starts a conversation, send an activity with Type=event and Name=startConversation.