Microsoft Teams notifications with Knock

This page covers 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 documentation serves as a starting point and will cover the basics of setting up a Microsoft Teams integration with Knock regardless of your use case.

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 registered with Azure. This is suitable for bots published to the Microsoft Teams Store, 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.

If you're using an incoming webhook URL, there are no prerequisites. If you're using a Microsoft Teams bot, you'll need to follow the steps below to enable your users to connect your Teams app to their Microsoft Teams workspaces. Knock does not manage deploying and configuring your bot.

Additionally, if you intend to use our TeamsKit SDK or Knock's Microsoft Teams-related React hooks, you'll need to configure a Graph API-enabled application in the Microsoft Entra admin center.

If you haven't already, you'll need to create a bot with the Bot Framework SDK and register it in Azure. Once your bot is created, you'll need to deploy it to Azure so that it can be used by your customers.

To use TeamsKit, you'll also need to configure the API permissions and OAuth redirect URL associated with a Graph API-enabled application in the Microsoft Entra admin center. You can use the bot application that has already been registered with Azure, or you can use a separate application.

Before you can start sending production notifications to your customers, you'll need to publish an app package to the Microsoft Teams Store.

The Teams app package includes a manifest.json file that contains the configuration for your bot. The required scopes will depend on the specific use case that you're targeting; see the documentation on sending messages to public channels and sending direct messages for more details.

While your submission is under review, you can test your integration end-to-end by sideloading your app into a tenant directly. Download your Teams app as a .zip package from the Teams Developer Portal, then upload it to the Teams Admin Center of the tenant you want to test in under Teams apps > Manage app > Upload. This makes your app available in that tenant's catalog without needing to wait for store approval.

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 Azure or the Microsoft Teams Developer Portal.

First you'll need to add Teams as a channel in Knock. Navigate to Integrations > Channels in your Knock dashboard account settings 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, follow these steps to configure your bot in the Knock dashboard.

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 below.

Now you're ready to notify Teams. Trigger the workflow that you added your Teams channel to. You'll need to include a user or object that has Teams channel data set as the recipient on the workflow trigger call; if no channel_data is set on the recipient, the Teams step will be skipped.

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.

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.

When you're sending as a Microsoft Teams bot, every notification needs two things, and Knock lets them live in different places:

• Scope — which Microsoft Entra tenant to reach: the ms_teams_tenant_id.
• Destination — where the message goes: a ms_teams_channel_id (a channel) or a ms_teams_user_id (a direct message).

The destination is stored on the recipient (a User or Object). The scope can be stored on the recipient too — or, in a multi-workspace product, once on the tenant, so every recipient in that tenant shares the same Entra tenant ID. The two sections below cover each location.

If you're using an incoming webhook instead of a bot, none of the above applies: the webhook URL is self-contained and requires no scope or destination.

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.

When you map a Microsoft Entra tenant to a Knock tenant (as our TeamsKit components do), you store that Entra tenant's ID as channel_data on the Knock tenant. At send time, when you trigger a workflow with that tenant, Knock takes the destination from the recipient's channel_data (the ms_teams_channel_id or ms_teams_user_id) and uses the tenant's ms_teams_tenant_id for scope: the tenant provides the scope, the recipient provides the destination. If the recipient also carries an ms_teams_tenant_id, the tenant's takes precedence — so the ms_teams_tenant_id on the recipient's MsTeamsConnection[] above is not required when a tenant holds one.

Do you need a tenant? Store the Entra tenant ID on a Knock tenant when one Microsoft Entra tenant connection should serve every recipient or object in that Knock tenant. This keeps the Entra tenant ID in one place while each recipient or object stores only its Teams destination (ms_teams_channel_id or ms_teams_user_id), which is useful as you add more destinations within the same Entra tenant later. You don't need a Knock tenant if you post to a single internal workspace (use an incoming webhook — there's no Entra tenant ID to share) or only ever use one Entra tenant's ID and prefer to store it directly on each recipient or object. Knock never auto-creates a tenant for you (though TeamsKit can, on the fly), so use one when a shared Entra tenant ID should live at the tenant level.

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

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.

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.)

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 Microsoft 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 Microsoft Teams on your behalf.

Here's an example of the JSON you'll need to provide. Note that you must include your Adaptive Card JSON within the attachments array and set the contentType to application/vnd.microsoft.card.adaptive.