> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suprsend.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Microsoft Teams
> Send SuprSend notifications to Microsoft Teams as channel posts or DMs, using a Workflows webhook or a bot you register in Azure.
This page covers how to send notifications to Microsoft Teams with SuprSend. Depending on what you're building, there are a few different ways to approach the integration.
## Choose a use case
Let's say you are a SaaS product, and the companies using it want activity from your product to show up in their Microsoft Teams.
| If your customer wants… | How they connect | Start here |
| - | - | - |
| Posts in **one channel** they pick, such as `#deploys` or `#development`. No DMs. | They paste a Workflows webhook URL. Microsoft's Workflows app posts the message. | [Post with a webhook](/docs/microsoft-teams-incoming-webhook) |
| **DMs and channel posts** from your product's bot — for example an incident tool that DMs the on-call and posts into `#incidents` | They install **your** Teams app in their Microsoft teams account. | [Send using your Teams app](/docs/microsoft-teams-customer-workspaces) |
| The same bot experience, but the bot must be **registered in their Entra directory** (common for banks and healthcare) | They create the app in *their* Azure and hand you credentials. | [Send via your customer's Teams app](/docs/microsoft-teams-customer-bot) |
The fastest path. Your customer pastes a Workflows webhook URL into your product, and every notification lands in that one channel, posted by Microsoft's **Workflows** app. You don't install your app in their tenant, and you can't DM anyone as your product.
*Example: a CI product like GitHub Actions or CircleCI. A customer connects their `payments-api` repository to `#deploys`. Every build result posts there, and nowhere else.*
Your customer installs your Teams app once. After that you can DM individual people and post in any channel they choose, and every message shows your bot's name and icon.
*Example: an incident tool like PagerDuty or Opsgenie. When `api-prod` goes down, the on-call engineer gets a DM, and `#incidents` gets the same alert so the rest of the team sees it.*
The same DM and channel experience, but the bot is registered in your customer's Entra directory and they hand you its credentials. Pick this when their security team won't approve a third-party bot in their tenant.
*Example: a hospital network that only allows apps registered in its own tenant. Every message arrives from their internal app, not from yours.*
If the customer only needs one channel and never DMs, use a webhook. Register and install your own bot when you need DMs, several channels, or the message to show your product's name and icon.
## Two ways to deliver
**Incoming webhook.** You still fill the Microsoft Teams vendor with App ID, password, App Type, and Tenant ID — same form as a bot send. The destination is a Workflows URL on the recipient. SuprSend POSTs to that URL; Microsoft's **Workflows** app (Power Automate) posts in the channel, usually as the flow bot or on behalf of the person who created the flow. The message will not appear as *your* product's bot, and you cannot DM someone this way. Microsoft retired Office 365 connectors; create the URL with Workflows.
**Azure bot + Teams app.** You register a bot, wrap it in a Teams app package, and store the bot credentials on the Microsoft Teams vendor in SuprSend. The channel or person to notify is stored as an `$ms_teams` channel on a [user](/docs/users) or an [object](/docs/objects) in SuprSend. Put DMs on users and map Teams channels to objects.
## How bot delivery is modeled
The channel or person to notify is stored as an `$ms_teams` channel on a [user](/docs/users) or an [object](/docs/objects) in SuprSend. When you trigger a workflow with that user or object as the recipient, SuprSend reads the `$ms_teams` value and delivers there.
**Where to store it**
* **DMs go on users.** Store the person's Teams identity as `$ms_teams` on their SuprSend user. If the same person uses your product under more than one customer org, store it on their [per-tenant profile](/docs/user-tenant-mapping) so an alert from one org doesn't DM the identity they use in another.
* **Channels go on objects.** A channel is not a person, so don't attach it to a user. Model the thing the channel is about (a repository, a service, a project) as a SuprSend [object](/docs/objects) and store `$ms_teams` on it. When `api-prod` goes down, you trigger with the `api-prod` object as the recipient and the post lands in the channel mapped to it.
**What goes in the user or object `$ms_teams` channel**
```json Channel on an object theme={"system"}
{
"$ms_teams": [
{
"tenant_id": "c1981ab2-9aaf-4f36-8c1e-7d2a54e0b3f9",
"conversation_id": "19:c1524d7c-a06f-456f-8abe-2f9e1a4b7c3d@thread.tacv2"
}
]
}
```
```json DM on a user theme={"system"}
{
"$ms_teams": [
{
"tenant_id": "c1981ab2-9aaf-4f36-8c1e-7d2a54e0b3f9",
"user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
]
}
```
| Field | Purpose | Required |
| - | - | - |
| `conversation_id` | The Teams channel to post in, such as `19:abc123def@thread.tacv2`. | For channel posts |
| `user_id` | The person to DM. Prefer their Entra object ID, such as `3fa85f64-5717-4562-b3fc-2c963f66afa6`. | For DMs |
| `tenant_id` | The Microsoft Entra tenant ID of the directory this channel or person lives in. | Optional — see below |
| `service_url` | Teams messaging endpoint. Defaults to `https://smba.trafficmanager.net/teams`, which covers all commercial Microsoft 365 tenants. Set it only if the customer is on a Microsoft US Government cloud (GCC High or DoD) — those run on isolated infrastructure with their own `*.microsoft.us` endpoints, so the commercial URL can't reach them. | Optional |
An entry holds either a `conversation_id` or a `user_id`. A user or object can carry several entries if it should be notified in more than one place.
**When to include `tenant_id` in the `$ms_teams` channel**
If you leave `tenant_id` out, SuprSend uses the home tenant ID saved in the Microsoft Teams vendor credentials. That's the right default when one SuprSend workspace serves one customer, or when every user and object in the workspace belongs to the same Entra directory as your bot. You can skip the field entirely in that case.
Include `tenant_id` when a single workspace notifies people or channels across several Entra directories — for example a SaaS product where each customer has its own Microsoft 365 tenant and has installed your Teams app. The value tells SuprSend which directory to deliver into; without it, the send goes to your bot's home directory instead of the customer's.
The SuprSend [tenant](/docs/tenants) on the workflow trigger is a different thing. Its `tenant_id` is your own slug for the customer account (`customer-a`), not the Entra ID. It selects that customer's branding, preferences, and [tenant vendor](/docs/tenant-vendor), and SuprSend does not read the Entra directory from it.
```json theme={"system"}
{
"workflow": "new-incident",
"tenant_id": "customer-a",
"recipients": [{ "object_type": "services", "id": "api-prod" }],
"data": { "severity": "high" }
}
```
## Next
Register the bot, build the app package, and add the vendor in SuprSend. Start here.
One channel, stored on an object. Workflows posts the message.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.