KnockDocs

How to send Microsoft Teams notifications with Knock

In this guide youโ€™ll learn how to use Knock to send notifications to your customer's Microsoft Teams channels.

Weโ€™ll cover:

  • A primer on how Teams integrations work
  • How to connect to Teams with Knock
  • How to design notification templates for Teams

An introduction to Microsoft Teams integrations

If you're new to sending notifications to Microsoft Teams channels, here's a quick primer on how it works.

TL;DR: Teams uses incoming webhook URLs to receive messages from external services and post them to channels.

There are two ways to generate an incoming webhook URL for a Teams channel:

  1. Your customer can create an incoming webhook and send it to you.
  2. You can build an Office365 Connector that your customers will install in Teams and add to their channels. When a customer adds your Connector to a channel, you receive an incoming webhook URL.

Whichever method you choose, the end result is the same: an incoming webhook URL. You'll store this webhook URL on either users or objects in Knock, then trigger workflows with those users/objects included as a recipient to programmatically send notifications to Teams.

๐ŸŒ 
What about OAuth? If you're used to building Slack apps you may be wondering about OAuth and the role it plays in Microsoft Team connectors. As of February 2022, there is no OAuth support for integrating with Microsoft Teams via an app, so all you need is the incoming webhook URL.

How to connect to Teams with Knock

Once you have a method for receiving incoming webhook URLs from your customers, you're ready to set up your Microsoft Teams integration in Knock.

Here's a step-by-step for how to do so.

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. No additional environment configuration is required.

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.

Store Teams channel data on a user or object

Once you have a workflow that includes your new Microsoft Teams channel, you'll need to set the incoming webhook URL (from Teams) as channel data in Knock on either a user or object using their respective set channel data endpoints.

The format of the channel data you store on Knock will look like this:

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.

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. ๐Ÿ™

Channel data requirements

In order to send a message to a recipient, you'll need to have the following channel data set for the recipient.

connectionsMsTeamsConnection[]*One or more connections to Teams

MsTeamsConnection with incoming webhook url

incoming_webhook.urlstring*The incoming webhook URL