Add bot to mobile and custom apps

Article
03/24/2023

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

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

There are different procedures for connecting to your mobile app, depending on whether your app is a web-based app or a native app.

Connecting your bot 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 bot into your app. Both procedures are described in this article.

Prerequisites

Learn more about what you can do with Power Virtual Agents.
.NET Core SDK version 2.1.
Nuget package Microsoft.Bot.Connector.DirectLine.
A bot created in Power Virtual Agents that you want to connect to your app.

Connect your bot to a web-based app

In Power Virtual Agents, in the navigation menu under Settings, select Channels.
Select the Mobile app tile to open the configuration window.
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 bot to a native or custom app

Tip

While this section describes how to connect to a mobile app, the same process could be applied for custom or native apps, such as IoT (Internet of things) apps.

If your goal is to connect to Azure Bot Service channels, besides following the instructions here, your developers can learn more at Connect your bot to Azure Bot Service channels.

Important

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:

Connector sample code

References

The instructions in this document reference the following:

Retrieve your Power Virtual Agents bot parameters

To connect to the bot you have built with Power Virtual Agents, you'll need to retrieve your bot's name and token endpoint to identify it.

Copy your bot's name in Power Virtual Agents.
In the navigation menu under Settings, select Channels.
Select Mobile app.
Next to Token Endpoint, select Copy. You'll need this in the Get Direct Line token step.

Get Direct Line token

To start a conversation with your Power Virtual Agents bot, you need a Direct Line token. You need to add code that retrieves a Direct Line token with the Bot ID and Tenant ID from the previous section to your app.

To request a Direct Line token, issue a GET request to the endpoint below:

GET /api/botmanagement/v1/directline/directlinetoken

Query Parameter	Required
`botId`	yes
`tenantId`	yes

Example:

GET https://powerva.microsoft.com/api/botmanagement/v1/directline/directlinetoken?botId=<ENTER-YOUR-BOTID>&tenantId=<ENTER-YOUR-TENANTID>

If the request is successful, a Direct Line token will be returned for the requested bot.

Sample code example

The following example uses samples from the Connector sample code to get a Direct Line token for a Power Virtual Agents bot.

using (var httpRequest = new HttpRequestMessage())
{   
    httpRequest.Method = HttpMethod.Get;
    UriBuilder uriBuilder = new UriBuilder(TokenEndPoint);
    uriBuilder.Query = $"botId={BotId}&tenantId={TenantId}";
    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; }
}

The response will be:

{
  "token": "<token>"
}

Use Direct Line to communicate with the bot

After retrieving the Direct Line token, you are ready to have a conversation with your Power Virtual Agents bot with Direct Line. Follow the instructions at Bot Framework Direct Line API to start a conversation and send and receive messages.

The following example uses samples from the Connector sample code to start a conversation and send and receive messages from a Power Virtual Agents bot.

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;
  }

Once started, each conversation can be identified and connected 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",
          });
      }
  }

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

  // Use the same token to create a directLineClinet
  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 may need to add code to refresh the Direct Line token if your application has a lengthy conversation with the bot. The token expires but can be refreshed before it expires; learn more at Direct Line Authentication.

The following example uses samples from the Connector sample code to refresh the token for an existing Power Virtual Agents 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 bot

After starting a conversation with the bot, the conversation JSON payload uses the standard Microsoft Bot Framework Direct Line activity. You can learn more at Bot Framework Direct Line API.

Handle hand-off activity

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

Trigger a welcome message

If you want your bot to send the Greeting system topic automatically when a user starts a conversation, you can send an activity with Type=event and Name=startConversation.