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

# Agents in Microsoft Teams

> Chat with Omni, the built-in agent, mention it in a channel, route a team channel to an agent and write its engagement rules, and where the conversations live.

Your administrator connects the Microsoft 365 tenant to xpander once. From then on you have your own conversation with Omni, the built-in agent, in Teams, and any channel can be routed to one of your organization's agents from that agent's settings.

## How it responds

The app decides who answers based on how a message arrives:

| You...                                           | Who answers                                                                     |
| ------------------------------------------------ | ------------------------------------------------------------------------------- |
| **Chat 1:1 with the app**                        | Omni, in your own conversation: the same history you have in Xpander Chat       |
| **@mention the app** in a channel                | Omni in your own conversation, replying in the same reply chain                 |
| **Post an untagged message** in a routed channel | The agent routed to that channel, when the message matches its engagement rules |

Replies from a routed agent are prefixed with **the agent's name in bold**, so a channel always shows which agent answered. 1:1 replies keep the app's own identity. After you @mention the app in a channel, your follow-up replies in that reply chain keep reaching Omni for about five minutes - no need to re-mention it on every message.

Everyone always has **their own** conversation with Omni, with their own context and, where systems allow, their own permissions, even in a shared channel. There is no shared or company-wide Omni conversation.

## Talk to Omni

<Steps>
  <Step title="Message the app">
    Find **xpander** in your Teams app list and send it a message.
  </Step>

  <Step title="Automatic sign-in">
    If your Microsoft work email matches your xpander account, you're linked automatically and the answer arrives right away. Otherwise you'll get a **Link account** button - one click connects your Teams identity to your xpander profile, and the message you already sent is answered as soon as the link completes.
  </Step>

  <Step title="Work as usual">
    Your Teams chat is a real conversation with Omni: it appears in Xpander Chat's sidebar, remembers context, uses its skills, and builds dashboards. Replies stream in as the agent works. Send `new chat` (or `new conversation` or `reset`) to start a fresh conversation.
  </Step>
</Steps>

Images and attached files are processed automatically. A few responses arrive in a Teams-specific shape:

* **Questions** come as tappable button cards. Tap an answer and the conversation continues.
* **Dashboards and visuals** carry a **View here** button that opens them full-screen in the browser - no sign-in needed.
* **Long answers** arrive as a PDF attachment with a short lead paragraph, instead of one long message.

You can also **build and update agents right from the chat**: Omni asks its setup questions with tappable buttons, sends authorization links for the accounts your agent needs, and creates the agent when you approve.

<Info>
  Your xpander profile must belong to the organization the tenant is connected to. If your profile lives in a different organization, you'll be asked to link again - by design.
</Info>

## Route a team channel to an agent

Untagged channel messages can be handled by one of your organization's agents. The tenant-wide permission was granted when your administrator connected the tenant; what is left is per team.

<Steps>
  <Step title="Add the app to the team (team owner)">
    A **team owner** opens **Team → ••• → Manage team → Apps → Add** and adds the xpander Teams app.

    This must be a **team install**. Pinning the app as a tab in a channel, or using it personally, does not enable routing. The correct install shows a consent prompt mentioning **receiving channel messages** - accept it. That consent is what lets an agent see untagged messages in the team.
  </Step>

  <Step title="Pick a team, a channel, and an agent">
    In Xpander Chat, open your agent's settings and find **Microsoft Teams channels**, or use the channel selector under the composer. Pick the team, then the channel, then click <kbd>Add</kbd>.
  </Step>

  <Step title="Write engagement rules">
    Expand the channel row's settings. Each rule is a plain-language description of when the agent should step in - the agent engages when a message matches **any** rule. Rules apply within about a minute; there is no publish step.
  </Step>
</Steps>

Write rules as specific intent descriptions, not keyword lists:

* Specific: "When someone reports a bug, error, or outage"
* Specific: "When a question about pricing or plans goes unanswered"
* Too broad: "bug, error, pricing" (triggers on most messages)

When a channel is routed to an agent, that agent answers in the thread under each message. The answer is attributed to the person who wrote the message and, where systems allow, the agent acts with that person's permissions. Only messages without an @mention are routed; an @mention still goes to Omni in the author's own conversation. Once the agent has answered in a thread, it keeps following that thread for a few minutes without re-checking the rules on every message.

Routing looks at **top-level channel messages**. Untagged replies inside a reply chain don't engage the agent unless you turn on **engage in thread replies** on the channel row - an @mention always works.

<Warning>
  Without the team install and its **receive channel messages** consent, the app still answers @mentions in that team but never sees untagged messages. Channel routing degrades to mention-only, silently. If routing isn't firing, check this first.
</Warning>

## Where conversations live

* **1:1 conversations** appear in your xpander sidebar like any other conversation with Omni.
* **Channel conversations** (mentions and routed replies) stay out of the personal sidebar but are visible in the organization's [Task Manager](/use/agents/conversations#the-task-record), which lists every task for an agent.

## Differences from Slack

If you already run the xpander Slack app, these are the behaviors that differ:

|                                   | Slack                                      | Microsoft Teams                                                              |
| --------------------------------- | ------------------------------------------ | ---------------------------------------------------------------------------- |
| Reply identity in channels        | Posted under the agent's own name and icon | Prefixed with the agent's name in bold                                       |
| Reading untagged channel messages | The app joins the channel                  | The team owner grants a per-team consent at install                          |
| Streaming                         | Everywhere                                 | 1:1 chats stream natively; channels show a progress message updated in place |
| Slash commands                    | Available                                  | Not available yet                                                            |

## Troubleshooting

<AccordionGroup>
  <Accordion title="The app doesn't respond to my 1:1 messages">
    Check that Microsoft Teams is enabled for your organization under **Settings → Channels** in Xpander Chat. If it's on and the app is still silent, confirm the app is **Allowed** in the Teams admin center and permitted by your setup policy.
  </Accordion>

  <Accordion title="I get a link-account prompt instead of an answer">
    Your Microsoft work email doesn't match an xpander account in this organization. Tap **Link account** and sign in, or ask your admin to invite that email to the organization. If your xpander profile belongs to another organization, you must link again from Teams.
  </Accordion>

  <Accordion title="The Link account button expired or looped">
    Link codes are single-use and valid for 15 minutes. Send any message again and a fresh button is issued.
  </Accordion>

  <Accordion title="Untagged messages in a channel are ignored">
    The most common cause is that the app was added personally or as a channel tab instead of to the **team**. Re-add it via **Team → ••• → Manage team → Apps** and accept the **receive channel messages** consent. Then check that the channel row's auto-engage toggle is on and that a rule actually matches your message. Untagged replies inside a reply chain only engage when **engage in thread replies** is on. Rule edits take up to a minute to apply.
  </Accordion>

  <Accordion title="The Microsoft Teams settings are missing from my agent">
    The Teams section appears in an agent's settings only after an administrator has connected your tenant. Organization admins see a connect prompt instead; other members see nothing.
  </Accordion>

  <Accordion title="The channel list is empty or errors when I try to add a channel">
    The picker only lists teams the app has actually been added to, so add the app to the team (the first step under Route a team channel) and reopen the picker. If it is still empty, your tenant may have been connected before the permission became part of connecting: an admin can click **Reconnect** on the Channels tab to grant it.
  </Accordion>

  <Accordion title="Answers aren't streaming in a 1:1 chat">
    Teams occasionally refuses a stream, and the reply falls back to a single message updated in place. Nothing is lost - this is expected, not a failure. Channel replies never stream; Teams supports streaming in 1:1 chats only.
  </Accordion>

  <Accordion title="The app says the organization is out of credits">
    Runs stop with a billing notice when your organization's credits run out. An organization admin can top up under **Settings** in Xpander Chat - then send your message again.
  </Accordion>

  <Accordion title="The agent responds when it shouldn't">
    Tighten the rules: broad conditions like "when someone asks a question" match most messages. After an engagement, follow-ups in the same channel may engage without re-checking rules for a few minutes.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Agents in Slack" icon="slack" href="/guides/deploy/slack">
    The same in your Slack workspace
  </Card>

  <Card title="Microsoft Teams tenant" icon="shield-check" href="/run/integrations/microsoft-teams">
    For administrators: uploading the app and connecting the tenant
  </Card>

  <Card title="Channels" icon="radio" href="/use/agents/channels">
    Every way work reaches an agent, and what is recorded
  </Card>
</CardGroup>