> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runlayer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Microsoft Teams

> Connect an agent to Microsoft Teams for @mentions, DMs, channel monitoring, and proactive channel updates

Each agent can have its own Microsoft Teams bot: users can @mention it in a channel or DM it directly, and admins can optionally let it respond in channels without being tagged. The bot can also post updates into a channel on its own, independent of any incoming message.

## Setup

Connecting Teams is a two-step process: one workspace-level connection, then a per-agent bot install.

**1. Connect Microsoft Teams**

In **Settings → Integrations**, click **Connect Microsoft Teams** and complete admin consent for your tenant. This is a one-time, org-wide step — it authorizes Runlayer to create and manage bot registrations in your tenant.

**2. Install the agent's bot**

On the agent detail page, under **Microsoft Teams**, click **Install**. In the **Install Teams app** dialog:

* Choose **User (direct message)** to install for a specific person, or **Team (all channels)** to make the bot available across every channel in a team
* Search for the user or team and select it, or use **Install for all users** / **Install for all teams** to install in bulk
* Click **Install**

Installing for a team makes the bot's mention/DM behavior available in every channel of that team — it does not, on its own, let the bot respond without being tagged (see below).

## Talking to the Agent

Once installed, the agent responds to:

| Trigger | Behavior |
| - | - |
| **@mention in a channel** | Responds in that channel |
| **Direct message** | Responds in the DM |
| **Channel message, no mention** | Only if **Respond without being tagged in channels** is enabled (see below) |

### Responding without being tagged

Under the agent's **Microsoft Teams** settings, toggle **Respond without being tagged in channels** to let the bot answer channel messages it isn't @mentioned in.

> [!NOTE]
>
> This applies to every channel of every team the bot is installed into — there is no per-channel allow-list. The first time you enable it, you'll need to reinstall the Teams app so the team owner can grant the extra permission it requires.

Optionally, add a natural-language condition (e.g. "only respond to messages about deployment failures") in the text field that appears once the toggle is on, then click **Save**. Leave it blank to respond to every channel message.

## Posting Updates to a Channel

Beyond replying to what triggered it, an agent can post a brand-new message into a Teams channel on its own — for example, to send a status update partway through a run, in addition to its normal final answer.

This always posts **as the agent's bot** — there is no separate "as a specific user" identity option for Teams the way there is for Slack's connector tools, because Teams has no equivalent user-identity connector today.

### Channel reachability

A channel becomes postable to once the bot has seen **any** message from that Teams tenant — not necessarily that exact channel. In practice:

1. The bot must be installed (see Setup above).
2. Someone sends at least one message the bot receives, anywhere in the tenant — an @mention in any channel, a DM, or (if enabled) an ambient channel message.
3. After that, the agent can post into any channel in that tenant, as long as it's told the destination channel's ID (copy it from Teams, e.g. via **Get link to channel**).

> [!TIP]
>
> If an agent tries to post into a channel and gets an "unknown channel" error, it means the bot hasn't received a single message from that tenant yet. Send it one message anywhere — a DM is enough — and retry.

### Known limitations

* **No channel picker.** There's no UI for choosing a destination channel — the agent needs the raw channel ID, typically supplied in its prompt/instructions.
* **No scheduled-run destination.** Scheduled agent runs have no built-in "post to this channel" field. To have a scheduled run post updates, include the channel ID directly in the schedule's prompt text.
* **No outbound messaging controls.** Unlike Slack (which has per-agent DM/channel blocking and a blocked-channels list), Teams currently has no admin-side restriction on which channels an agent can post into.

## Workspace Notifications

Separate from any individual agent's bot, your workspace can have one shared **Runlayer Teams Bot** that posts platform-level notifications (currently: security scan violations) — the Teams analog of the Slack app's notification channel.

Set it up from **Settings → Integrations → Microsoft Teams**:

1. Click **Create Teams Bot** to provision the shared bot (requires the workspace-level tenant connection above).
2. @mention or message the bot at least once from the channel(s) you want it to post into — like an agent's bot, it can only post into a channel it has seen a message from.
3. Pick a **Notification channel** — where general workspace notifications go.
4. Optionally pick a separate **Security alerts channel** — where security scan violations go instead. Leave it unset to fall back to the notification channel above.
5. Optionally enable **Only alert on blocked calls** to skip alert/mask-only violations and only notify on calls the scanner actually blocked.

Use **Test** next to either channel to confirm delivery before relying on it.

> [!NOTE]
>
> Unlike Slack (which can post an incident-lifecycle summary instead of per-violation alerts), Teams always sends one alert per violation — there's no incident-style digest option yet.

## Link Previews

When someone pastes a Runlayer link (an agent, skill, plugin, artifact, or session URL) into a Teams message, the agent's bot can turn it into a rich card — title, resource type, and creator — the same way Slack unfurls Runlayer links today.

> [!NOTE]
>
> No new app registration is required. Link previews are a capability added to each agent's **existing** Teams bot manifest, not a separate app — there's nothing extra to register in Azure/Entra.

**To enable it:**

1. This capability ships in the agent's Teams manifest automatically going forward. For a bot installed **before** this feature shipped, reinstall the Teams app once (agent page → **Microsoft Teams** → **Install**, same dialog used for the initial install) so Teams downloads the updated manifest.
2. Paste a Runlayer link into any chat or channel the bot is in. Teams calls the bot to resolve the link and replaces the raw URL with a card.

The preview always shows the resource type at minimum. It also shows the resource's title and creator when the person who pasted the link (identified via their linked Runlayer account — see **Talking to the Agent** above) has access to that resource; otherwise it falls back to a type-only card, same access-aware behavior as Slack's link previews.

> [!TIP]
>
> If a pasted link stays a plain hyperlink instead of turning into a card, either the bot hasn't been reinstalled since this feature shipped, or the link isn't under your organization's Runlayer app URL.

## Troubleshooting

> **Agent doesn't respond to @mentions**
>
> Confirm the bot is installed for that team (agent page → **Microsoft Teams** → **Install**, check the **Already installed** list) and that the mention actually tags the bot's name.

> **Agent doesn't respond without being tagged**
>
> Check that **Respond without being tagged in channels** is enabled and that the Teams app was reinstalled after first enabling it. If a condition prompt is set, the message may simply not match it.

> **"Unknown Teams channel" when posting an update**
>
> The bot hasn't received any message from that tenant yet. Send it a DM or @mention it once anywhere in the tenant, then retry — after that, any channel ID becomes reachable.

> **Agent never responds on a self-hosted deployment**
>
> Teams delivers every message by calling your deployment over HTTPS. If your deployment only accepts traffic from your office or VPN IPs, Teams can't reach it. Exempt `/api/v1/integrations/ms-teams/` from the WAF IP allowlist. See [Slack and Microsoft Teams with an IP allowlist](https://docs.runlayer.com/deployment/ecs-networking.md#slack-and-teams-inbound).

> **Connection shows disconnected**
>
> Reconnect from **Settings → Integrations**. If the bot was removed from Teams directly, reinstall it from the agent's **Microsoft Teams** settings.

> **Pasted Runlayer link doesn't turn into a card**
>
> Reinstall the agent's Teams app (agent page → **Microsoft Teams** → **Install**) so Teams picks up the manifest capability for link previews, then paste the link again.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.