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

# Microsoft Teams

> Capture channel messages and talk to the Modem Agent in Teams

export const Prompt = ({text, variant = 'accent'}) => {
  const [copied, setCopied] = useState(false);
  const handleCopy = async () => {
    try {
      await navigator.clipboard.writeText(text);
      setCopied(true);
      setTimeout(() => setCopied(false), 2000);
    } catch {}
  };
  const clipboardIcon = <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
            <title>Copy</title>
            <rect x="9" y="9" width="13" height="13" rx="2" ry="2" />
            <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />
        </svg>;
  const checkIcon = <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
            <title>Copied</title>
            <polyline points="20 6 9 17 4 12" />
        </svg>;
  const promptIcon = <svg width="16" height="16" viewBox="0 0 24 24" fill="currentColor" style={{
    flexShrink: 0,
    opacity: 0.4
  }}>
            <title>Prompt</title>
            <path d="M20 2H2v20h2V4h16v12H6v2H4v2h2v-2h16V2zM6 7h12v2H6zm8 4H6v2h8z" />
        </svg>;
  return <div className={`prompt prompt-${variant}`} style={{
    marginTop: '12px',
    marginBottom: '12px'
  }}>
            {promptIcon}
            <span className="prompt-text">{text}</span>
            <button className="prompt-copy" onClick={handleCopy} title="Copy to clipboard" type="button">
                {copied ? checkIcon : clipboardIcon}
            </button>
        </div>;
};

The Microsoft Teams integration captures messages from the channels you choose and feeds them into Modem for analysis. Install the Modem app in Teams to ask the agent about customer signals and take action through your connected tools.

<Info>
  Modem captures **channel messages** from the channels you subscribe, including replies, edits, deletions, reactions, and @mentions.
  It does not capture 1:1 or group chats (DMs). You query captured Teams data from the [Modem Agent on the web](/docs/features/agent).

  Channel capture and the Teams agent have separate setup steps. You can capture messages without installing the bot.
  To talk to the agent in Teams, [install the Modem app](#installing-the-teams-agent).
</Info>

## How it works

Modem connects to your Microsoft 365 tenant with an app-only Microsoft Graph app that a tenant administrator approves once. After you subscribe specific channels, Modem uses **Graph change notifications** to receive a signal whenever someone posts, then fetches the message and ingests it in real time.

Graph channel subscriptions expire after about an hour, so Modem runs a background loop that renews them continuously and recreates any that lapse. This means capture is self-healing after a brief outage, but a prolonged outage has a gap: Microsoft does not replay missed notifications, so messages posted during a long interruption are not captured automatically. You can recover them with a manual [history import](#importing-history) within the 30-day window.

## Prerequisites

* A Microsoft 365 **work or school tenant** (personal Microsoft accounts are not supported)
* A **Microsoft tenant administrator** to grant admin consent during setup
* **Owner or admin** role in your Modem organization

## Setup

<Steps>
  <Step title="Start the connection">
    Go to **Settings** → **Integrations** → **Microsoft Teams** in your Modem dashboard and click **Connect Microsoft Teams**. Only
    organization owners and admins can connect.
  </Step>

  <Step title="Grant admin consent">
    You'll be redirected to Microsoft to sign in and approve the permissions Modem needs. This step requires a **tenant administrator**.
    See [Permissions](#permissions) below for the exact scopes. If your tenant blocks consent for unverified publishers, an admin may
    see a warning during approval.
  </Step>

  <Step title="Wait for channel sync">
    Back in Modem, your teams and their channels sync automatically. This populates the channel list so you can choose what to monitor.
    You can re-run it anytime with **Sync teams**.
  </Step>

  <Step title="Subscribe to channels">
    Channels start unmonitored. Check the channels you want Modem to capture, then click **Save changes**. See [Subscribing to
    Channels](#subscribing-to-channels) below.
  </Step>

  <Step title="Import history (optional)">
    Click **Import history** to backfill the last 30 days of messages from your subscribed channels. See [Importing
    History](#importing-history) below.
  </Step>
</Steps>

## Permissions

During admin consent, a tenant administrator approves the following application (app-only) Microsoft Graph permissions. The Graph app reads message content and basic directory information. It never posts or changes anything in your tenant. The Modem bot, if your tenant installs it, replies where it's @mentioned or messaged.

| Permission | Why Modem needs it |
| - | - |
| `ChannelMessage.Read.All` | Read channel messages and replies |
| `Team.ReadBasic.All` | Discover the teams in your tenant |
| `Channel.ReadBasic.All` | Discover the channels in each team |
| `User.Read.All` | Resolve message authors to people (name, email) |

Modem authenticates as the approved app and does not store any per-user sign-in tokens. Consent is tenant-wide and can be revoked only from the Microsoft Entra admin center. [Disconnecting](#disconnecting) in Modem stops capture but leaves the consent in place.

<Note>
  Each Microsoft tenant can be connected to one Modem organization, and each organization can have one active Teams connection. To connect
  a different tenant, [disconnect](#disconnecting) the current one first.
</Note>

## Subscribing to Channels

Channels are not captured by default. After connecting, open **Settings** → **Integrations** → **Microsoft Teams** and check the channels you want Modem to monitor. Your selections stay pending until you click **Save changes**.

Subscribing a channel starts real-time capture for that channel. Replies and threads within a subscribed channel are captured along with root messages.

### Recommended Channels

* Support or help channels where customers and users raise issues
* Feedback or ideas channels for feature requests
* Bug-report channels for user-reported problems

### Channels to Avoid

* Internal team-only or admin channels (unless relevant)
* Bot or automation channels
* Off-topic or social channels (high noise, low signal)

<Tip>Start with a few high-signal channels and expand based on what's useful. You can change your channel selection anytime.</Tip>

## Importing History

To capture conversations from before you connected, click **Import history** on the integration settings page. Modem backfills recent messages from every subscribed channel, so subscribe the channels you care about first.

Import limits:

* Up to the **last 30 days** of messages
* Up to **500 messages per channel**

One import runs at a time, and progress (channels processed and messages imported) is shown live on the settings page. Imported messages that overlap with live capture are automatically deduplicated, so running an import after messages have already streamed in won't create duplicates.

## Analyzing Teams Conversations

Once messages are flowing, ask the [Modem Agent](/docs/features/agent) about them from the web dashboard like any other source.

<Prompt text="What are people asking about in our Teams channels this week?" />

<Prompt text="Summarize the bug reports from Microsoft Teams in the last 7 days" />

<Prompt text="Create a Linear ticket for the recurring login complaints from our Teams support channel" />

## Installing the Teams agent

Connect your Microsoft 365 tenant in Modem first, then install the app in each team where you want to use the agent.

<Steps>
  <Step title="Download the app">
    In **Settings** → **Integrations** → **Microsoft Teams**, find **Teams agent** and click **Download Teams app**.
    You can also [download the production app package](https://app.modem.dev/integrations/msteams/modem-teams-1.0.0.zip) directly.
    Keep the ZIP file zipped. It contains the app manifest and icons; you do not need to supply any keys or secrets.
  </Step>

  <Step title="Upload and add Modem to your team">
    In Teams, open **Apps** → **Manage your apps** → **Upload an app** → **Upload a custom app** and select the ZIP.
    Add **Modem** to each team where you want to mention the agent.

    If custom uploads are unavailable, ask your Teams administrator to upload the ZIP through **Teams admin center** →
    **Teams apps** → **Manage apps**, then make it available in your organization's app catalog.
    Your administrator controls who can install custom apps. See [Microsoft's custom app guidance](https://learn.microsoft.com/en-us/microsoftteams/upload-custom-apps).
  </Step>

  <Step title="Check installation status">
    Return to Modem and click **Refresh status**. Each team shows **Installed** once Modem has received activity from the installed app.
    Downloading the ZIP alone does not confirm installation. Installation status is separate from channel subscriptions.
  </Step>

  <Step title="Link your account and test a reply">
    In a channel where you installed the app, select **@Modem** from the mention menu, then send the prompt below.
    If the bot asks you to link your account, follow its link, sign in to Modem, and link the Microsoft account you use in Teams.
    You must also be a member of the connected Modem organization. Mention the bot again after linking.

    <Prompt text="Reply with &#x22;Modem is connected&#x22;." />
  </Step>
</Steps>

You can also add Modem for personal use and message it directly. Personal installation does not mark the app as installed in a team.
Direct messages to the agent are conversations with Modem; they are not captured as channel feedback.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connected in Modem, but the Teams agent doesn't reply">
    The tenant connection enables channel capture. To use the agent, [install the Modem app](#installing-the-teams-agent) in the team,
    select it from the @mention menu, and send a message. Check **Teams agent** → **Installation status** in Modem settings. If it asks
    you to link your Microsoft account, follow the bot's link and try again.
  </Accordion>

  <Accordion title="Admin consent failed or asked for approval I couldn't give">
    Connecting requires a Microsoft **tenant administrator** to grant tenant-wide consent. A regular member can't approve it. If your
    tenant restricts consent to verified publishers, your admin may need to approve the request explicitly or accept a warning about the
    publisher. Personal Microsoft accounts can't be used, only work or school tenants.
  </Accordion>

  <Accordion title="Some channels are missing from the list">
    Modem discovers channels using app-only access. If Microsoft refuses to list a team's channels to the app, which can depend on your
    tenant's policies, that team appears with no channels. Private and shared channels that Microsoft does list appear alongside
    standard channels. Try **Sync teams** to refresh the list.
  </Accordion>

  <Accordion title="Messages stopped being captured">
    Teams subscriptions expire roughly hourly and Modem renews them continuously, so brief interruptions recover on their own. Microsoft
    does not replay notifications missed during a longer outage, so use **Import history** to recover messages from the affected window
    (within the last 30 days).
  </Accordion>

  <Accordion title="Attachments or files aren't fully captured">
    Message text, mentions, reactions, and threads are captured. File attachments point to SharePoint and require Microsoft
    authentication, so their contents may not be fully accessible in Modem yet.
  </Accordion>

  <Accordion title="It says my tenant is already connected">
    A Microsoft tenant can only be linked to one Modem organization. If the tenant was previously connected to another organization,
    contact [support@modem.dev](mailto:support@modem.dev).
  </Accordion>
</AccordionGroup>

## Disconnecting

To disconnect Microsoft Teams:

1. Go to **Settings** → **Integrations** → **Microsoft Teams**
2. Click **Disconnect** and confirm

Disconnecting removes the stored connection and stops channel-message capture for your organization. Live subscriptions stop being renewed and lapse within about an hour. To fully revoke Modem's access on the Microsoft side, remove the app's consent from the Microsoft Entra admin center.

Historical data remains in Modem after disconnecting.

## Related

<CardGroup cols={2}>
  <Card title="The Modem Agent" icon="https://mintcdn.com/modem-844d7a4a/Wr2r4IRr97lNQiQb/icons/bot.svg?fit=max&auto=format&n=Wr2r4IRr97lNQiQb&q=85&s=2496f9106cb54fa9f4e27ad1f8f3a171" href="/docs/features/agent" width="22" height="22" data-path="icons/bot.svg">
    Query and act on your captured Teams conversations from the web.
  </Card>

  <Card title="Topics" icon="https://mintcdn.com/modem-844d7a4a/Wr2r4IRr97lNQiQb/icons/label-alt-multiple.svg?fit=max&auto=format&n=Wr2r4IRr97lNQiQb&q=85&s=e7fbaf23c28396ac670b89cf38e1e4a6" href="/docs/guides/topics" width="24" height="24" data-path="icons/label-alt-multiple.svg">
    See how messages are grouped into themes and classified.
  </Card>

  <Card title="Companies & People" icon="https://mintcdn.com/modem-844d7a4a/Wr2r4IRr97lNQiQb/icons/contact.svg?fit=max&auto=format&n=Wr2r4IRr97lNQiQb&q=85&s=727cb0ef6c8547993c6acfdaa30bd837" href="/docs/guides/people" width="24" height="24" data-path="icons/contact.svg">
    Understand how Modem links message authors into unified profiles.
  </Card>

  <Card title="All Integrations" icon="https://mintcdn.com/modem-844d7a4a/Wr2r4IRr97lNQiQb/icons/link.svg?fit=max&auto=format&n=Wr2r4IRr97lNQiQb&q=85&s=e774d33588635d44c6c935b78ed55f13" href="/docs/integrations/overview" width="24" height="24" data-path="icons/link.svg">
    Browse every data source and agent tool.
  </Card>
</CardGroup>


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