Episode #144 – Creating Teams Link Unfurling Extensions with Yo Teams v 3.x
Here you can find the transcript of Episode #144 of PiaSys TechBites.
Welcome back to Pia Sys Tech Bites. This week I want to talk to you about how we can create a Link Unfurling Extensions for Microsoft Teams using the Yo Teams Generator version three. A Link Unfurling Extension is an extension that allows us to replace or enrich a link written inside a conversation. So, a chat or a channel with an Adaptive Card which will add additional information on top of the bare link.
In order to do that, we need to create a Messaging Extension and to register a BOT for Microsoft Teams. And inside the BOT, we need to manage the queryLink event. Yo Teams version three, does not provide out of the box in its scaffolding tool the generation of a Link Unfurling extension. But we can easily do that simply by changing the generated code for a search or for an action command extension.
So, let me move to the demo environment. Let me show you how to do that in practice. Here, you can see the official documentation page about how to create Link Unfurling extensions and you can find the URL in the notes about this video.
Here you can see, you simply need to create an extension. You need to register in the manifest of your solution, that you want to create a Link Unfurling message handler, and you will have to implement your handling of the URL by processing the link query request. So, let me do that using Yo Teams generator. So, I already started it. I will provide a name for my solution and I will go quite fast on this stage because it is almost the same that we saw last week about how to create a Search Messaging Extension. So, I’m using the current folder.
This will be the name, the company name. I will use the Manifest 1.8 and I will do the quick scaffolding. I will choose to create a Messaging Extension command and I will have to provide the URL for my extension, which could be for example, this one followed by ngrok.io. So, HTTPS, ngrok.io. Then, I will have eventually to show a loading indicator, which is not needed for this kind solution. I’m going to create a new BOT and I will completely skip this stage. You can refer to video number 143, in order to see how to do that. Once the scaffolding will be ready, we will see what changes we need to make to the scaffolded code in order to implement a Link Unfurling extension.
So, the scaffolding is now ready and as such we can start “code .” To see what we have got generated. Here we see the solution generated and available invidious to the code. First of all, I will have to go to the environment file and I will have to configure the client secret for my application. I don’t need to obfuscate it, because I will delete the BOT right after recording this video. So, here I have my environment file configured, let me save it. Secondly, I need to go to the manifest and I need to change the manifest definition in order to support the Link Unfurling functionality. So, I will completely remove the content of the commands array of items. But I need to keep it because it is mandatory. I will have to add a new section, which is called message handlers and which I will copy just for convenience.
So, here I create a message handler section, which will be made of one or more handlers, and I’m registering an handler of type link, which will target any URL under my company domain. So, *.piasys.com. Let me save this manifest as well. Now I can go to the server side of the generated code inside the messaging extension. I simply need to replace the onQuery event handling, with the onQueryLink event handling. So, this will be the method that I want to implement. If we go to the definition of the base type that we implement, we can see the onQueryLink will accept these two input arguments. So, let me go back here and let me update the signature of the method. Moreover, I need to add a reference to the app-based link query, which will replace the messaging extension query, while the result type will be exactly the same of any other messaging extension.
Now that we have done that we can just for the sake of completeness, eventually logger the query object that we get whenever the user will write a URL, which targets our extension just to see what happens on the server side. Then we can easily create the content of an Adaptive Card, which will be the result of the URL link unfurling. So here we can create still an adoptive card that we are in the text block, which will show the title, we can provide the query.url value, which is the URL written by the user. We can eventually skip the description or we can just write “Navigate to the selected website”. Here we can provide a fake image to just enrich our adaptive card, but in the actions, rather than having an action.Submit, we could have an action.OpenURL that I will let simply replace here in order to open the URL, the query.url provided by the user.
Moreover, we can provide a preview of our card and indeed we can replace the fake content that we see here with the query.url that we have in query message that we get. Once we have done that, we can so far in this demo skip all of this logic, and we can simply return the result of the extension as the list of all of the cards actually just one the card representing our URL with its preview. And we don’t really need an onCardButtonClick. So simple as that, we simply create a card with whatever structure you like.
We create a preview of the card and we return a messaging extension result, including the card and the preview in the collection of attachments, in a list, which would be the result of our extension. So I save everything and going to the terminal, I can say gulp grok-serve to start my solution but in order to do that I also need to configure in the environment file the name that I want to use from a ngrok point of view and place it in the ngrok sub domain.
So let’s do that and to speed up the process, let’s keep the linting. And so gulp ngrok-serve –no-linting.
I will start my solution locally. Then because under the cover of ngrok-serve, there is also the packaging of the package of my solution, I can go to Microsoft Teams and there I can install my solution. So let’s go back to the browser and here in Teams, we can see that if I create a new message and if I provide the URL of my company right now .com right now, I don’t get any help or any advanced content. I can simply provide the URL and it will be just a simple URL. Now let me go to the apps. So let me install the app that we just created. So upload the custom app for my tenant. Let me go to the repo where I have the solution.
So right here, conferences-samples, which you will find also on GitHub. And then I go to my link unfurling sample, in the package folder I have my zip file, which represents my package. Once I’ve done that, I can simply click on it and we can add the extension to our tenant. So if I go back to a team channel, I can create a new message. Of course, let me refresh the browser to be sure that I will not have any caching in place. If I create a new conversation and I will provide the URL of my company website, we can see that now we will get the URL link unfurling inside the teams, and we can post a message and we can navigate to the URL that we provided. If we go back to Visual Studio Code, we can also see that we have got a request for the URL that we provided inside our messaging exchange. Like always thank you for watching this video. I hope you found it interesting. And we’re looking forward to seeing you next week and remember subscribe to this channel. Thank you.