Build Search Based Messaging Extension With Microsoft Teams App

Introduction

 

Messaging extensions enable users to execute search queries or trigger actions within a designed external system. As a result, messages are received from custom web services or API to the Microsoft Teams Client.

 

Messaging Extension 

 

Messaging extensions take advantage of the Bot Framework's messaging schema and secure communication protocol to connect with Microsoft Teams Client App.

 

There are three type of messaging extenions that can be build for Microsoft Teams:

1. Search based messaging extenion for Microsoft Teams
2. Action based messaging extenion for Microsoft Teams
3. Unfurl Url with messaging extension for Microsoft Teams 

How Messaging Extension works

1. Command box: This is the area at the top of the Microsoft Teams client
2. Compose message box: This is the area at the bottom of a 1:1 or group chat and at the bottom of the Conversations tab in a channel
3. More Actions menu: It is accessible, when users hover over a message in a conversation chat

When the messaging extension is invoked, Microsoft Teams will send, via the Bot Framework, an HTTPS message with a JSON payload that includes all relevant information.

 

Your web service will respond with a JSON payload, via the Bot Framework, that informs the Microsoft Teams client what interaction to enable next.

 

Prerequisites

• Microsoft Teams
• Azure Bot Framework, .NetCore
• Azure Web API .Net Standard
• Microsoft 365 tenant
• Microsoft Azure subscription

Let's get started,

 

To create Microsoft Team Messaging Extension requires two activities:

1. Create Microsoft Azure Bot.
2. Create manifest file with bot reference 
3. Upload manifest file to MS Team Client App.

Step 1 - Create Microsoft Azure Bot

1. Browse the https://portal.azure.com with your work or school account.
2. Click "+Create Resource"
3. Select "AI + Machine Learning"
4. Select "Web App Bot"

 

Step 2 - Complete all required information and click create to provision the bot

1. Bot handle:- The unique name of your bot.
2. Subscription:- Select a valid available subscription.
3. Resource Group:-Select an appropriate resource group or create a new one as per requirement.
4. Location:- Select your closed azure location or the preferred location.
5. Pricing:- Select the required pricing tier or F0 as free for POC activity.
6. App Name:- Leave it as-is for this demo purpose.
7. Service Plan:- Leave it as-is for this demo purpose.
8. Bot Template:- Leave it as-is for this demo purpose.
9. Application insight: Select off for this demo purpose
10. Microsoft App Id and Password:- Leave it as-is for this demo purpose.
11. Click create to provision.

 

 

Step 3 - Enable Microsoft Teams Channel for your Bot

 

In order for the bot to interact with MS Teams, you must enable the Teams Channel.

 

 

 

To complete the process, MS Teams and Webchat should be available and should be listed in your channel lists.

 

 

Step 4 - Create a Bot Framework

 

In this section, we are going to create a echo bot using Visual Studio 2019

• Open the Visual Studio, Select create project and navigate to the desired directory to create a project.
• Select Echo Bot (Bot Framework v4) .Net Core
  

Step 5 - Update Default Bot Code

1. Select EchoBot.cs 
2. Remove all default methods defined into EchoBot Class
3. Inherit Team Activity Handler to EchoBot Class to implement messaging extension related method.
4. Add Query Async method to pass query parameter to external api.
5. Select Item Async method used to post the selected message into team channel conversation area via adaptive card.

 

Query Async Method - Take typed query as parameter and pass it to api to get JSON Payload, render the JSON Payload into hero card with list; i.e., attachment layout.

protected override async Task<MessagingExtensionResponse> OnTeamsMessagingExtensionQueryAsync(ITurnContext<IInvokeActivity> turnContext, MessagingExtensionQuery query, CancellationToken cancellationToken)
        {
            var text = query?.Parameters?[0]?.Value as string ?? string.Empty;

            var packages = await FindPackages(text);

            var attachments = packages.Select(package => {
                var previewCard = new ThumbnailCard { Title = package.Item1, Tap = new CardAction { Type = "invoke", Value = package } };
                if (!string.IsNullOrEmpty(package.Item5))
                {
                    previewCard.Images = new List<CardImage>() { new CardImage(package.Item5, "Icon") };
                }

                var attachment = new MessagingExtensionAttachment
                {
                    ContentType = HeroCard.ContentType,
                    Content = new HeroCard { Title = package.Item1 },
                    Preview = previewCard.ToAttachment()
                };

                return attachment;
            }).ToList();

            return new MessagingExtensionResponse
            {
                ComposeExtension = new MessagingExtensionResult
                {
                    Type = "result",
                    AttachmentLayout = "list",
                    Attachments = attachments
                }
            };
        }

 Call External API based on provided query parameter.

private async Task<IEnumerable<(string, string, string, string, string)>> FindPackages(string text)
        {
            var obj = JObject.Parse(await (new HttpClient()).GetStringAsync($"https://azuresearch-usnc.nuget.org/query?q=id:{text}"));
            return obj["data"].Select(item => (item["id"].ToString(), item["version"].ToString(), item["description"].ToString(), item["projectUrl"]?.ToString(), item["iconUrl"]?.ToString()));
        }

 Select Item Async used to post bot framework thumbnail card based on selected item information into teams channel conversation.

protected override Task<MessagingExtensionResponse> OnTeamsMessagingExtensionSelectItemAsync(ITurnContext<IInvokeActivity> turnContext, JObject query, CancellationToken cancellationToken)
       {
           var (packageId, version, description, projectUrl, iconUrl) = query.ToObject<(string, string, string, string, string)>();
           var card = new ThumbnailCard
           {
               Title = $"{packageId}, {version}",
               Subtitle = description,
               Buttons = new List<CardAction>
                   {
                       new CardAction { Type = ActionTypes.OpenUrl, Title = "Nuget Package", Value = $"https://www.nuget.org/packages/{packageId}" },
                       new CardAction { Type = ActionTypes.OpenUrl, Title = "Project", Value = projectUrl },
                   },
           };

           if (!string.IsNullOrEmpty(iconUrl))
           {
               card.Images = new List<CardImage>() { new CardImage(iconUrl, "Icon") };
           }

           var attachment = new MessagingExtensionAttachment
           {
               ContentType = ThumbnailCard.ContentType,
               Content = card,
           };

           return Task.FromResult(new MessagingExtensionResponse
           {
               ComposeExtension = new MessagingExtensionResult
               {
                   Type = "result",
                   AttachmentLayout = "list",
                   Attachments = new List<MessagingExtensionAttachment> { attachment }
               }
           });
       }

 Build and Publish the Bot Code to Publishing Profile.

 

 Step 5 - Create Manifest 

1. Create folder within solution with the name "TeamAppManifest" 
2. Create and add icon-color.png file
3. Create and add icon-outline.png file 
4. Create manifest.json file and Update compose Extension with Command Context "Compose" and "CommandBox" 

"composeExtensions": [
  {
    "botId": "4c961f60-bb20-44a9-913d-2177652ddb3b",
    "canUpdateConfiguration": true,
    "commands": [
      {
        "id": "searchQuery",
        "context": [ "compose", "commandBox" ],
        "description": "Test command to run query",
        "title": "Search",
        "type": "query",
        "parameters": [
          {
            "name": "searchQuery",
            "title": "Search Query",
            "description": "Your search query",
            "inputType": "text"
          }
        ]
      }
    ]
  }
]

 Select all three files and make it as .zip file and name it manifest.

Step 6 - Upload Manifest into Microsoft Teams App  

 

Navigate to manifest folder /src/manifest. Select both .png files and manifest.jon file and zip all three files. Give the name of zip file "manifest"

 

Login to https://teams.microsoft.com

1. Navigate to App Studio
2. Select Import an existing app
3. Select the manifest.zip file
4. Bot name with the icon will appear at the screen

 

Step 7 - Install Custom App to Teams Solution

1. Select the install App using Manifets file and It will navigate to create an app page will all pre-filled information.
2. Select test and distribute
3. Click Add to add app to teams. 

 

Once bot deployment and Manifest configuration is done, now it's time to test the messaging extension.

 

Output 

1. Navigate to teams and select channel
2. Click on below compose message box "..." and select deployed app i.e. "searc-extension-settigns"
3. Type keyword which will get searched from external api

Here we used nuget.org as external api. 

 

 

Select any item from messaging extension and the same will be posted as adaptive card to Teams Channel Conversation area. 

 

 

Code base exists here.

 

I hope you have enjoyed and learned something new in this article. Thanks for reading and stay tuned for the next article.