Sending a message to an internal Microsoft Teams workspace

In this guide we'll cover how to send a message to an internal Microsoft Teams workspace using Knock. It assumes that you have already created a Microsoft Teams channel in Knock as outlined in the Microsoft Teams integration overview guide.

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

• Retrieving an incoming webhook URL from Microsoft Teams
• Setting channel data for an Object in Knock
• Triggering a workflow with an object recipient to send a message to a Microsoft Teams channel

Microsoft Teams channels are connections on Objects

In Knock, we model channels in a Microsoft Teams workspace as connections on Objects. Objects allow you to model any resource in your system within Knock, and while their primary purpose is to act as non-user recipients, they are very flexible abstractions.

An overview of Objects

Individual Objects exist within a collection and always have a unique ID or key within that collection. The Object itself can store any number and type of properties as key-value pairs. You can see some examples of possible Object structures in the official documentation on setting Object data.

Let’s say you are building a devtool product like GitHub and want to set up Microsoft Teams notifications whenever someone comments on an issue within a repository. First, you’ll want to create an Object to model your repository as part of the repositories collection:

Once you have a repository object created, you can add the channel data for Microsoft Teams as a connection on the object.

Objects as workflow recipients

To add channel data, we’ll set up an incoming webhook in Microsoft Teams. 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 a Microsoft 365 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.

Set the webhook as channel data

Now that you have the webhook URL, we’ll store that webhook as a special property on the repository Object called channel data. Channel data is both channel and recipient-specific data stored for use with particular channels, like a token used for push notifications or webhooks stored for chat apps like Slack, Teams, and Discord. Both Users and Objects can store channel data.

In the code example below, we’ll use the knockClient.objects.setChannelData method to update the channel data for our repository Object.

Here, you’ll also need your KNOCK_MS_TEAMS_CHANNEL_ID as the third parameter, which is the channel ID of your Microsoft Teams integration within Knock, so that Knock can reference that channel when it processes workflows that use it. The last parameter is an object of a specific format that varies based on the type of message provider. In this case, it is an MsTeamsConnection object with an incoming_webhook property that contains the URL of an incoming webhook in Microsoft Teams.

Trigger a workflow with an object recipient

With the channel data in place, you can add Microsoft Teams as a workflow step in any workflow. For this example, we’ll create a new-issue workflow that pings users in our connected Microsoft Teams channel whenever someone adds a new issue.

As you create your message template, remember that in this case the repository Object is the recipient of your workflow. That means any properties you reference on your Liquid template tags need to exist as properties of the Object as well:

Finally, we’ll add the workflow trigger to our code with the repository Object as a recipient.

With that, you should see a message in your selected Microsoft Teams channel: