Unfurl links in Teams using bot
Microsoft Bot Framework extends the cards specification by adding a set of pre-defined cards that bots can use as a part of bot messaging. Link unfurling using bot in Teams helps you to register your app. And helps to receive an invoke activity, when the URL with domain is pasted into the compose message area. The invoke activity contains the full URL and you can respond with a card. Users can unfurl the link using bot with additional information to get an enhanced experience.
Note
Currently, link unfurling isn't supported on mobile clients.
Key features of link unfurling
- Allows user to paste URLs and respond with a card.
- Allows user to register the app and receives invoke activity.
This step-by-step guide helps you to create a bot to perform link unfurling in Microsoft Teams for https://www.BotFramework.com
. You'll see the following output:
Prerequisites
Ensure you install the following tools and set up your development environment:
Install | For using... | |
---|---|---|
Required | ||
Microsoft Teams | Microsoft Teams to collaborate with everyone you work with through apps for chat, meetings, call and all in one place. | |
Visual Studio 2022 version 17.3 Install one of the following two workloads: • ASP.NET and web development • .NET Core cross-platform development |
You can install the enterprise version in Visual Studio 2022 and install the workloads. | |
.NET Core SDK version 3.1 | Customized bindings for local debugging and Azure Functions app deployments. If you haven't installed the .NET 3.1 (or later) SDK globally, the portable version can be installed. | |
ngrok | Teams app features (conversational bots, message extensions, and incoming webhooks) require inbound connections. A tunnel connects your development system to Teams. It isn't required for apps that only include tabs. This package is installed within the project directory (using npm devDependencies ). |
Note
After downloading ngrok, sign up and install authtoken.
Set up local environment
Open Microsoft-Teams-Samples.
Select Code.
Select Open with GitHub Desktop from the dropdown menu.
Select Clone.
Create and register your bot in Azure portal
The following steps help you to create and register your bot in Azure portal:
- Create Azure Bot resource to register bot with Azure Bot Service.
- Create client secret to enable SSO authentication of the bot.
- Add Teams channel to deploy the bot to Teams channel.
- Use ngrok to create a tunnel to your web server's endpoints.
- Add messaging endpoint to the ngrok tunnel you created.
To create Azure Bot resource
Go to the Microsoft Azure portal.
Select Create a resource.
In the search box, enter Azure Bot.
Select Enter.
Select Azure Bot.
Select Create.
Enter required bot handle name in Bot handle.
Select your Subscription and Resource group from the respective dropdown list.
Select required Data residency (preview).
You can also create a new resource group (select Create new > enter resource name > select OK).
Select the required location from New resource group location dropdown list, if you've created a new resource group.
In the Microsoft App ID section, by default Create new Microsoft App ID is selected.
You can also select Use existing app registration and enter App ID, App tenant ID, and MSI resource ID.
Note
You can't create more than one bot with the same Microsoft App ID.
Select Type of App as Multi Tenant.
Select Review + create.
Once the validation is passed, select Create.
It takes a few moments for your bot service to be provisioned.
Select Go to resource.
Your Azure bot is created, and you can see the Resource group and Subscription ID in the Azure bot.
To create client secret
Perform the following steps if you've created a new Microsoft App ID:
In the left pane, select Configuration.
Tip
Save the Microsoft App ID or Client ID for future reference.
Next to Microsoft App ID, select Manage.
In the Client secrets section, select New client secret.
The Add a client secret window appears.
Enter Description to the client secret.
Select Add.
In the Value column, select copy to clipboard icon to copy value details.
Tip
Save the client secrets Value or app password for future reference.
To add the Teams channel
Select Home.
Select your bot from Recent resources.
Select Channels in the left pane.
Select Microsoft Teams
.
Select the checkbox to accept the Terms of Service.
Select Agree.
Select Apply.
To create tunnel for local web server
Use ngrok to create a tunnel to your locally running web server's publicly available HTTPS endpoints. Run the following command in ngrok:
ngrok http --host-header=localhost 3978
Tip
If you encounter ERR_NGROK_4018, follow the steps, as displayed in the command prompt to sign up and authenticate ngrok. Then run the ngrok http --host-header=localhost 3978
command.
To add messaging endpoint
From ngrok, copy the HTTPS URL (https to io).
Note
The HTTPS URL in your ngrok is your fully qualified domain name. The
WebAppDomain
is a fully qualified domain name that doesn't includehttps://
in it.In Settings, select Configuration.
In Messaging endpoint, use the HTTPS URL available from ngrok and at the end of the URL add /api/messages.
Select Apply.
You have successfully set up a bot in Azure Bot Service.
Update the Azure AD app registration
Go to the Azure portal.
Select Azure Active Directory.
In the left pane, select App registrations.
Select your bot.
Select Expose an API.
Select Set.
Set the Application ID URI in the form of
api://your ngrok/botid-{your AppID}
.The following image shows the domain name:
Note
If you're using a tunneling service such as ngrok, ensure you update the value whenever your ngrok subdomain changes.
For example: api://f631****.ngrok.io/92c11075-c629-4a1e-ab58-02b4fd4204c2
, wheref631****.ngrok.io
is the new ngrok subdomain name.Select Add a scope.
In the panel that appears, enter
access_as_user
as the Scope name.Set Who can consent? to
Admins and users
.To configure the admin and user consent prompts with appropriate values for
access_as_user
scope, provide the following information in the fields:Enter
Teams can access the user’s profile
as Admin consent display name.Enter
Allows Teams to call the app’s web APIs as the current user
as Admin consent description.Enter
Teams can access the user profile and make requests on the user’s behalf
as User consent display name.Enter
Enable Teams to call this app’s APIs with the same rights as the user
as User consent description.
Ensure that State is set to Enabled.
Select Add scope to save.
Note
The Scope name should match with the Application ID URI with
/access_as_user
appended at the end.api://your ngrok/botid-00000000-0000-0000-0000-000000000000/access_as_user
In the Authorized client applications section, identify the applications that you want to authorize for your app’s web application.
Select Add a client application.
Enter Client ID:
1fec8e78-bce4-4aaf-ab1b-5451cc387264
for Teams desktop application.Enter Client ID:
5e3ce6c0-2b1f-4285-8d4b-75ee78787346
for Teams web application.Select Authorized scopes.
The following image displays the Client ID:
In the left pane, select API Permissions.
Note
Users need to consent to the API permissions only if the Azure AD app is registered in a different tenant.
Select Add a permission.
Select Microsoft Graph > Delegated permissions.
Select the following permissions:
- offline_access
- OpenId
- profile
- User.Read
Select Add permissions.
From the left pane, select Authentication to set a redirect URI.
Note
If an app isn't granted IT admin consent, users must provide consent the first time they use an app.
Select Add a platform.
Select Web.
Enter the redirect URI for your app by appending
auth-end
to fully qualified domain name:https://your ngrok/auth-end
.Enable Implicit grant and hybrid flows by selecting the following checkboxes:
- ID tokens
- Access tokens
Select Configure.
Set up app settings and manifest files
Go to appsettings.json in cloned repository.
Open appsettings.json in Visual Studio.
Update the following information:
Set
"MicrosoftAppType"
to MultiTenant.Set
"MicrosoftAppId"
to your bot's Microsoft App ID.Set
"MicrosoftAppPassword"
to your bot's client secret ID value.Set
"MicrosoftAppTenantId"
as blank for MultiTenant bot.
Go to manifest.json in cloned repository.
Open manifest.json in Visual Studio.
Add the following code snippet to your manifest file, if not already present:
"bots": [ { "botId": "<<YOUR-MICROSOFT-APP-ID>>", "scopes": [ "personal", "team", "groupchat" ], "supportsFiles": false, "isNotificationOnly": false }
Replace all occurrences of
<<YOUR-MICROSOFT-APP-ID>>
with your bot's Microsoft App ID.
Build and run the service
To build and run the service using latest version of Visual Studio or Command line
Launch the latest version of Visual Studio.
Go to File > Open > Project/Solution.
Select TeamsLinkUnfurling.csproj file from samples > msgext-link-unfurling > csharp folder.
Open Solution Explorer from View.
Press F5 to run the project.
Select Yes if the following dialog appears:
A webpage opens with a message Your bot is ready!.
Upload Link Unfurling app
In your cloned repository, go to samples > msgext-link-unfurling > csharp > TeamsAppManifest.
Create a .zip with the following files that are present in the Manifest folder:
manifest.json
icon-outline.png
icon-color.png
Go to Microsoft Teams.
Select Apps.
Select Manage your apps.
Select Upload a custom app.
Select Open to upload the .zip file that you created in the TeamsAppManifest folder.
Select Add.
The app opens in a chat.
In the compose message area, enter
https://www.BotFramework.com
.The link unfurls as shown in the following image:
Press Enter.
Complete challenge
Did you come up with something like this?
Congratulations!
You've completed the tutorial to get started with Teams link unfurling app!
Have an issue with this section? If so, please give us some feedback so we can improve this section.
Feedback
Submit and view feedback for