Episode #143​ – Creating Teams Messaging Extensions with Yo Teams v 3.x

Here you can find the transcript of Episode #143 of PiaSys TechBites.

Welcome back to Piasys Tech Bites. Today, we keep on talking about the Yo Teams Generator version three. Specifically, I want to talk with you about how we can create Messaging Extensions for Microsoft Teams. In fact, with Yo Teams Generator v.3 we can create Search Extensions, Message Actions and Link Unfurling Extensions. Generally speaking, here is the list of all of the events that can be intercepted using the Messaging Extension infrastructure of Yo Teams version three.

So, like always, let me move to the demo environment and let me show you how to do that in practice.

Let’s start creating a Messaging Extension using Yo Teams Generator version three. First of all, we need to execute the Yeoman Generator for Teams using Yo Teams, and by following the steps of the wizard, we can now create our solution.

I will speed up this stage because we already saw it in some of the previous videos, but I will simply provide a name. Use the current folder. I will provide a title for the project, DemoExtensions, for example. I will provide a name for my company. I will choose to use version 1.8 of the schema. And once I’ve done that, I will select to use the quick scaffolding. I want to create a Message Extension Command, and I will provide a URL for my service. I can provide a loading URL while my extension is loading and I can use a new bot or an already existing bot. I will use a new one because I will create a new bot. And here we have to provide the ID of an application, which represents the bot on the Azure side of the story.

So, let me switch to Azure and let me create a new bot service here. So, I will click on New. I will select to create a Bot Channel Registration, and here I will create it and provide some basic settings, like for example the name of my bot handle. I will target a subscription, a resource group and a location. And once I will be done with the configuration of my Bot Channel Registration, I will be able to use the ID under the cover of this bot channel as the setting for my Yeoman Generator for Teams. I will choose the free one, and I will provide a URL for my Bot Channel Registration, which can be HTTPS, and it will be the URL of my solution under ngrok.

So, let me copy this URL and let me add ngrok.io/api/messages, which will be the URL where my bot will listen to. I don’t want to have Application Insights right now, and I can auto create the App ID and the password. The App ID is what we need to configure the Yeoman Generator. So, let me click on Create and after a while my Bot Channel Registration will be ready. Now my resource is ready I can go there, and we can see in the Configuration of the bot channel that we have a specific client ID that we can use while we need to keep track of this value, so I click on Manage. And I simply go to Overview and I copy the ID for this application.

Moreover, I also need to keep track of the client secret for my application, so let me do that. Let me go to Certificates & secrets. Let me add a new secret, which can be my ClientSecret. It will last for one year. And let me copy the value of this client secret, as well as all of these settings to configure the application in my generated application. It takes a while. And here I have my ClientSecret, which I will copy and keep in a safe place.

Now I can go back to my channel registration and I can go to the Channels section and I can configure this one to be a bot channel for Microsoft Teams for the Commercial one or for the Government one. Up to you, depending on where you are. Then I can agree on the terms and I can configure my Bot Channel Registration in order to work with Microsoft Teams.

So we can go back to the Yeoman Generator for Teams and we can provide the ID that we’ve just created, the GUID of the application. Now I can select to create a search based messaging extension or an action based messaging extension. Let’s go for the search one, for example. I can eventually have a settings page, which I want to have, and I will provide a name for my extension, which can be DemoSearch. Then I will provide a description, and that’s it. My solution will be scaffolded.

The solution is now fully scaffolded, so I can run code . and see what we’ve got generated. And here we can see, first of all, in the environment file that we have the application ID that we just copied from the Azure portal, and we also need to provide the shared secret that we saved before. So, let me do that. This is my secret. Moreover, I need to provide for ngrok the sub domain that I want to use for my application. So if I go back here and I go to Configuration, we can see that this is the URL on ngrok that I’m planning to use, so this will be the sub domain. Of course, you will have to buy an ngrok plan to be able to use a custom sub domain for your solution.

Now let’s see what got generated. Like it was in the previous example with the tab, we have the client folder, we have the server folder and the public one with the public assets. In the client folder, we have the React component using React Hooks, where we define the behavior and the UI of the settings page for our extension. Here you see we have a Flex with Fluent UI and we simply have a check box with an on or off status and a button to save the status, the settings of our messaging extension, our search Messaging Extension. Moreover, in the server side, we have the bot which will manage the bot logic for our solution and we have the Messaging Extension logic, which will trap all of the events sent through the bot channel to our solution. Here, for example, we have the onQuery event, which will be triggered whenever the user will make a new search using our search Messaging Extension.

Here we get inside the query object the information about the search query, and we can generate an output which can be, for example, a set of adaptive cards. So here, for example, we have a card which gets defined right here with json. And then we have a preview of the card, when the user will see just a small list of results before clicking on a specific result to see the expanded version of the search result. Then, based on the query parameters, if this is the initial run of the query, we simply provide, in this generated code, the card overriding the preview property of the output with this content and, actually, the generated code will do the same also for an actual search. But here you could replace this logic with your own search logic and create your own cards and provide the output for the search.

Moreover, because in the card we have an action, you see a Submit action, Action.Submit, which will get some content, some data in the request of the Submit. We have also the onCardButton clicked, which will look for the action clicked by the user and will get the value, the ID of the value provided in the Action.Submit.

We also have the onQuerySettingsUrl and onSettings events managed, because we need to manage the UI to configure the settings of our search extensions. So here we provide the URL of the UI, which will be a config.html page, which will be under the public folder, because this will be used in the public facing part of our solution. And here we have a very simple HTML file, which will render a React component, which is exactly and precisely the client TSX component that we saw before. Moreover, if we go back to the extension, we also have this action when we get the settings once the user will click on the Save button, and here we get back the new settings and we just show them in the log window of the application.

So, in order to run the solution, we can start the terminal and we can say “gulp ngrok-serve” and we can run this solution. The gulp ngrok-serve will create a new package for our solution that we can upload in a target team and will start listening, using Node.JS and will start listening for requests. Using ngrok will make our solution available with the public URL that we configured.

So, it is ready. Let me go to Microsoft Teams in my environment. Here we are. And here is the base infrastructure that is used under the cover of the Yo Teams Generator. This is the reap of Yo Teams Generator, and this is one of the NPM packages used by Yo Teams. This one is the one for the Messaging Extension. Here you can see what the extensions events supported are.

And here we go to Teams. We can go to Apps. We can choose to upload a new custom app. I will click on this button and I will choose to go to my temp folder and I want to use the solution that we just created. This is our solution, the one in which we are with the Visual Studio Code. So let me get into this one, get the package and upload the zip file of the package. By doing that, I will be able to add the solution to my tenant, to my Teams. I click on Add and by doing that, you see here I have my demo extension. Here I can search for something and whatever it will be the search I will get just one result, which will be my card preview. And if I click on it, I will see the extended card and I can click on more details, or I can copy the card.

I can do the same if I go into the channel and I use it from here, I can create a new message. I can click on the extension right here and do the same. I can search for test content. I will get the preview and I can include the expanded card into the content of my messages and send it as the content of a new conversation.

Like always, thank you for watching this video. I hope you found it interesting and I’m really looking forward to seeing you next week. And remember, subscribe to this channel. Thank you.