Microsoft Teams notifications with Knock

In this guide you'll learn how to use Knock to send notifications to Microsoft Teams. Depending on your use case, there are a few different ways to approach this integration. This guide serves as a starting point and will cover the basics of setting up a Microsoft Teams integration with Knock regardless of your use case.

Here's what we'll cover in this guide.

The different methods of sending notifications to Microsoft Teams
How to add a Microsoft Teams channel to your Knock instance
How to store Microsoft Teams connection data in Knock using channel data
How to design notification templates for Teams

Supported notification methods

Today, Knock supports sending notifications to Microsoft Teams using two different methods:

Using an incoming webhook URL. This is suitable for internal or one-off integrations.
As a Microsoft Teams bot, via Microsoft Bot Framework. This is suitable for multi-tenant integrations, and supports both sending notifications to channels and sending direct messages to users.

How you configure your Microsoft Teams channel in Knock depends on the method you choose.

How to connect to Teams with Knock

Prerequisites

If you're using an incoming webhook URL, there are no prerequisites.

If you're using a Microsoft Teams bot, make sure your bot has been registered with Microsoft Bot Framework and is deployed to Azure. Knock does not manage deploying and configuring your bot. To set up Knock to send notifications as your bot, you'll need your bot's ID and password. These are sometimes called the App ID and App Password, and were provided to you when you registered your bot with Microsoft Bot Framework.

Additionally, if you intend to use TeamsKit or Knock's Microsoft Teams-related React hooks, you'll need to configure your bot in the Microsoft Entra admin center.

Add Teams to Knock as a channel

First you'll need to add Teams as a channel in Knock. Navigate to the “Channels” page within Knock and click “Create channel” to add Microsoft Teams.

If you're using an incoming webhook URL, no additional environment configuration is required.

If you're using a Microsoft Teams bot, click “Manage configuration”, scroll down to “Provider settings”, and enter the ID and password associated with your bot.

Add a Teams channel step to a workflow

Next, navigate to a workflow in Knock that you want to notify Teams and add a chat channel step. Select the Teams channel you just configured and create a notification template for the channel.

You can learn more about how to write basic and advanced templates for Teams in the designing notifications templates section of this guide.

Trigger the workflow

Now you're ready to notify Teams. Trigger the workflow that you added your Teams channel to. You'll need to include the user or object that has your Teams channel data as a recipient on the workflow trigger call.

Your Teams channel should have received a notification. If you need to debug your integration, you can view the logs page in the Knock dashboard.

Configuring your bot in Microsoft Entra

To use TeamsKit, you'll need to configure the API permissions and OAuth redirect URL associated with your Microsoft Teams bot in the Microsoft Entra admin center.

Find your bot in the Microsoft Entra admin center

Log in to the Microsoft Entra admin center. In the sidebar, navigate to Identity > Applications > App registrations, and locate your bot.

Add a redirect URL

On your bot's app registration page, click Authentication. Under Platform configurations, click Add a platform and select Web.

Copy and paste the following URL into the Redirect URI text field:

This will allow Knock to handle the OAuth redirect on behalf of your bot, and manage connecting a Microsoft Entra tenant to a Knock tenant.

Leave the Front-channel logout URL text field empty. Click Configure to save your changes.

Add API permissions

In the top-level sidebar, navigate to API permissions and click Add a permission. Select Microsoft Graph > Application permissions.

Under Select permissions, add the following permissions:

Team.ReadBasic.All: This permission allows your bot to read a list of all teams within a Microsoft Entra tenant.
Channel.ReadBasic.All: This permission allows your bot to read a list of all channels within a team.
AppCatalog.Read.All: This permission allows your bot to locate itself in the Microsoft Teams app catalog.
TeamsAppInstallation.ReadWriteSelfForTeam.All: This permission allows your bot to install itself into a team.
TeamsAppInstallation.ReadWriteSelfForUser.All: This permission allows your bot to install itself into a user's personal scope.

Click Add permissions to save your changes.

How to set channel data for a Microsoft Teams integration in Knock

In Knock, the ChannelData concept provides you a way of storing recipient-specific connection data for a given integration. If you reference the channel data requirements for Microsoft Teams, you'll see that there are two different schemas for an MsTeamsConnection stored on a User or an Object in Knock.

Here's an example of setting channel data on an Object in Knock.

🚨

Potential confusion alert. In the example above, the KNOCK_TEAMS_CHANNEL_ID variable is the id of the Knock channel you've created to represent your Microsoft Teams integration within the Knock dashboard. You can find it by going to Integrations > Channels in the Knock dashboard and then copying the ID of your Microsoft Teams channel.

Recipient channel data requirements

Here's an overview of the data requirements for setting recipient channel data for either an incoming webhook URL or a Microsoft Teams bot connection. Both will need to live under the connections key.

Property	Type	Description
connections	`MsTeamsConnection[]`	One or more connections to Microsoft Teams

An MsTeamsConnection can have one of two schemas, depending on whether you're using a Microsoft Teams bot or an incoming webhook.

If you're using a Microsoft Teams bot, your MsTeamsConnection schema looks like this. You'll use either ms_teams_channel_id or ms_teams_user_id depending on whether you're storing connection data to message a channel or user in Microsoft Teams:

Property	Type	Description
ms_teams_tenant_id	`string`	A Microsoft Entra tenant ID
ms_teams_channel_id	`string`	A Microsoft Teams channel ID
ms_teams_user_id	`string`	A Microsoft Teams user ID

If you're using an incoming webhook, your MsTeamsConnection schema is quite simple:

Property	Type	Description
incoming_webhook.url	`string`	The Microsoft Teams incoming webhook URL (to be used instead of the properties above)

Tenant channel data requirements

When you map a Microsoft Entra tenant to a Knock tenant, you'll store the ID of the Microsoft Entra tenant as channel_data on the Knock tenant. Then, when you apply the Knock tenant to your workflow triggers, Knock will combine that Microsoft Entra tenant ID with the recipient's channel_data to send notifications to the correct Microsoft Teams channel within a Microsoft Entra tenant. For this implementation method, the ms_teams_tenant_id on the recipient's MsTeamsConnection[] data above is not required.

Here's an overview of the data requirements for setting channel data when storing a Microsoft Entra tenant ID on a Knock tenant.

Property	Type	Description
ms_teams_tenant_id	`string`	A Microsoft Entra tenant ID

Setting channel data: users vs. objects

Depending on the Microsoft Teams integration you build into your product, you'll store the connection data you receive from Microsoft Teams as channel_data on either a User or an Object in Knock.

Designing notification templates for Teams

When you add a new Teams channel step to a workflow in Knock, you'll need to configure a template for that step so Knock knows how to format the message to Teams.

By default, we provide a basic markdown editor that you can use for sending simple messages to Teams. Just write in Markdown and we'll handle the rest. (Note: As of February 2022, Teams only supports the following markdown styles: bold, italic, unordered lists, ordered lists, hyperlinks. All other markdown styles are not supported.)

Advanced Teams notifications

If you find yourself wanting to send notifications that include more advanced formatting and interactivity, such as buttons, data layouts, and so on, you'll need to use Microsoft's adaptive card format to build your notification templates in Knock. This is essentially a JSON block language you use to lay out your Teams message.

To switch to the JSON editor in the Knock template designer, look for the "Switch to JSON editor" button at the bottom of the template editor page. When you're in JSON editing mode, you can provide adaptive card JSON and we'll pass it to Teams on your behalf.

⚠️

Note: We do not support adaptive card previews in Knock at this time.

What did you think of this guide? Did we miss any key steps? Did you run into a blocker? Let us know using the feedback component at the top of this page. 🙏

←Sending a message to channels

Sending an internal message→