feat(kno-7297): update MS Teams integration docs (#680)

content/integrations/chat/microsoft-teams/overview.mdx

@@ -0,0 +1,163 @@
+---
+title: Microsoft Teams notifications with Knock
+description: Learn how to use Knock to send Microsoft Teams notifications to your users.
+tags: ["msteams", "teams", "chat"]
+section: Integrations > Microsoft Teams
+layout: integrations
+---
+
+In this guide you'll learn how to use Knock to send notifications to Microsoft Teams.
+
+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](/integrations/chat/microsoft-teams/sending-an-internal-message).
+- As a Microsoft Teams bot, via Microsoft Bot Framework. This is suitable for multi-tenant integrations, and supports both [sending notifications to channels](/integrations/chat/microsoft-teams/sending-a-message-to-channels) and [sending direct messages to users](/integrations/chat/microsoft-teams/sending-a-direct-message).
+
+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 <a href="https://dev.botframework.com/" target="_blank">Microsoft Bot Framework</a> 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.
+
+### 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](#designing-notification-templates-for-teams) of this guide.
+
+### Trigger the workflow
+
+Now you're ready to notify Teams. [Trigger the workflow](/send-notifications/triggering-workflows) 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.
+
+<MultiLangCodeBlock
+  snippet="workflows.trigger-with-object-as-recipient"
+  title="Trigger a workflow with an object recipient"
+/>
+
+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.
+
+## How to set channel data for a Microsoft Teams integration in Knock
+
+In Knock, the [`ChannelData`](/managing-recipients/setting-channel-data) 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](/managing-recipients/setting-channel-data#chat-app-channels), you'll see that there are two different schemas for an `MsTeamsConnection` stored on a [`User`](/send-and-manage-data/users) or an [`Object`](/send-and-manage-data/objects) in Knock.
+
+Here's an example of setting channel data on an `Object` in Knock.
+
+<MultiLangCodeBlock
+  snippet="objects.setChannelData.msTeams"
+  title="Store Microsoft Teams connection on object"
+/>
+
+<br />
+
+<Callout
+  emoji="🚨"
+  text={
+    <>
+      <span className="font-bold">Potential confusion alert.</span> In the
+      example above, the <code>KNOCK_TEAMS_CHANNEL_ID</code> 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{" "}
+      <span className="font-bold">Integrations</span> {">"}{" "}
+      <span className="font-bold">Channels</span> in the Knock dashboard and
+      then copying the ID of your Microsoft Teams channel.
+    </>
+  }
+/>
+
+### Channel data requirements
+
+Here's an overview of the data requirements for [setting recipient channel data](/send-notifications/setting-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.
+
+<AccordionGroup>
+  <Accordion title="MsTeamsConnection as a bot" description="For self-serve customer integrations">
+    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 Teams tenant ID    |
+    | ms_teams_channel_id | `string` | A Microsoft Teams channel ID   |
+    | ms_teams_user_id    | `string` | A Microsoft Teams user ID      |
+
+  </Accordion>
+  <Accordion title="MsTeamsConnection with an incoming webhook url" description="For internal or one-off integrations">
+     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) |
+
+  </Accordion>
+</AccordionGroup>
+
+### 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.
+
+<AccordionGroup>
+  <Accordion title="Users" description="For notifying users via direct message">
+    If your integration involves a user opting in to receive direct messages from your Microsoft Teams integration, you’ll be storing the channel data [on that user](/reference#set-user-channel-data) in Knock. When you want to notify this user, you'll include them as a recipient in a Knock workflow trigger.
+
+    For this integration, you'll store a user's Microsoft Teams `ms_teams_user_id` in the `MsTeamsConnection` object.
+
+  </Accordion>
+  <Accordion title="Objects" description="For notifying Microsoft Teams channels about non-user resources">
+    If your integration involves a customer connecting a _non-user resource_ in their product (such as a project or a page) to a Microsoft Teams channel, you’ll want to store that channel data [on an object](/reference#set-object-channel-data) in Knock, as it’s not specific to any single user.
+
+    For this integration, you'll store a Microsoft Teams `ms_teams_channel_id` in the `MsTeamsConnection` object.
+
+  </Accordion>
+</AccordionGroup>
+
+## 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](https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-reference#adaptive-card) 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.
+
+<Callout
+  emoji="⚠️"
+  text={
+    <>
+      <strong>Note:</strong> 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. 🙏