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

# Microsoft Teams

> Connect your agent to Microsoft Teams

## Overview

Microsoft Teams integration lets your agent respond inside Teams chats and channels - a natural fit for internal tooling and organizations already standardized on Microsoft 365.

<CardGroup cols={2}>
  <Card title="Enterprise Ready" icon="building">
    Built for Microsoft 365 organizations
  </Card>

  <Card title="Chats & Channels" icon="users">
    DMs, group chats, and @mentions in team channels
  </Card>

  <Card title="Quick Start Available" icon="bolt">
    Use Lua's shared bot with no Azure setup
  </Card>

  <Card title="Bring Your Own Bot" icon="key">
    Full control with your own Azure Bot registration
  </Card>
</CardGroup>

## Two ways to connect

<Tabs>
  <Tab title="Lua's Teams bot (quick start)">
    **Recommended for most teams**

    * No Azure account, Bot resource, or app registration — nothing to set up on Microsoft's side
    * Install Lua's ready-made Teams app and link your agent
    * Best for getting started quickly, or when you don't need your own app identity

    Available in the dashboard.
  </Tab>

  <Tab title="Bring your own bot (advanced)">
    **Full control**

    * Your own Azure Bot resource, App ID, and secret
    * Your own Teams app manifest and branding
    * For organizations that require their own Azure app registration

    Available in the dashboard.
  </Tab>
</Tabs>

## Connection Method 1: Use Lua's Teams bot (Quick Start)

<Info>
  The fastest way in — Lua hosts the bot for you. **No Azure subscription, no Bot resource, no app registration, no client secrets to manage.** You install one ready-made app and link your agent; that's the whole job.
</Info>

<Steps>
  <Step title="Open the dashboard">
    ```bash theme={null}
    lua admin
    ```

    Or visit [https://admin.heylua.ai](https://admin.heylua.ai).
  </Step>

  <Step title="Open your agent and add a channel">
    Click **Agents** in the main side navigation, select your agent's card, click the **+** (plus) icon to add a channel, then choose **Microsoft Teams**.

    <Frame>
      <img src="https://mintcdn.com/luaglobal/5airD3u2P6mv3Ovl/images/channels/admin-add-channel.png?fit=max&auto=format&n=5airD3u2P6mv3Ovl&q=85&s=ab13d8f9a731bc706b9e112cf4226701" alt="Add a channel" width="3016" height="1576" data-path="images/channels/admin-add-channel.png" />
    </Frame>

    *Screenshot: The agent's add-channel (+) control and the channel options*
  </Step>

  <Step title="Choose Use Lua's Teams bot">
    Pick **Use Lua's Teams bot**. No Azure credentials are required for this path.
  </Step>

  <Step title="Install the Lua Teams app">
    The dashboard gives you a Teams app package to install (or a direct install link). In Microsoft Teams, an admin uploads the app: **Apps → Manage your apps → Upload a custom app**, then selects the package Lua provided. If your tenant restricts custom app uploads, a Teams admin may need to approve it first in the Teams admin center.
  </Step>

  <Step title="Connect your agent">
    Installing the app doesn't yet link it to your agent — one quick step does. The dashboard gives you a **Connect** link. Open it: it starts a chat with the Lua bot and pre-fills a one-time connect message. Just **send** it, and the bot replies *"Connected to agent…"* — your organization is now linked to this agent.

    <Info>
      **Why this step exists:** Lua's bot is shared across many organizations, so this one-time link is how Lua learns which agent *your* organization belongs to. (Running your own bot instead? Then there's no connect step — see [Bring Your Own Azure Bot](/channels/teams-byo-azure-bot).)
    </Info>

    <Note>
      The connect link is single-use and expires after 24 hours. If it expires before you use it, regenerate it from the dashboard.
    </Note>
  </Step>

  <Step title="Start chatting">
    **@mention** the bot in a team channel, or send it a direct message, and your agent will reply.

    <Check>
      Done — with zero Azure setup. No subscription, no Bot resource, no secrets to rotate.
    </Check>
  </Step>
</Steps>

## Connection Method 2: Bring Your Own Bot (Advanced)

<Info>
  Use this path if your organization requires its own Azure app registration, or you want the bot to appear under your own name and branding.
</Info>

The short version:

1. In the [Azure Portal](https://portal.azure.com), create an **Azure Bot** (**Single Tenant**), set its **Messaging endpoint** to `https://wa.heylua.ai/teams/webhook`, and enable the **Microsoft Teams** channel.
2. Copy the bot's **App ID**, create a **client secret**, and note your **Tenant ID**.
3. In the Lua dashboard, choose **Bring your own bot**, paste those three values, and click **Connect** — your bot is now linked to your agent. Download the app package Lua generates, upload it to Teams, then **@mention** or DM the bot.

<Card title="Full step-by-step walkthrough" icon="arrow-right" href="/channels/teams-byo-azure-bot">
  Every click in Azure and Teams, with each concept explained, a values reference, and troubleshooting.
</Card>

## Files and images

Your agent can read images, documents, audio and video that users send it in Teams. Attachments are downloaded, stored on Lua's CDN, and passed to your agent the same way as on every other channel — so the model sees the actual file contents, not a link.

**Where it works:**

| Scope                         | Pasted image | File sent with the attachment button |
| ----------------------------- | ------------ | ------------------------------------ |
| Direct message with the agent | Yes          | Yes                                  |
| Channel / group chat          | Yes          | **No**                               |

Microsoft Teams does not deliver files uploaded with the attachment button to a bot outside a direct message, and gives the bot no indication one was sent. Images pasted directly into the message box come through everywhere. If someone shares a file with your agent in a channel, your agent will explain it can't see it and ask for a direct message.

<Note>
  The attachment button only appears once the Teams app has been updated. **If you added your agent to Teams before file support shipped, download the app package again from the dashboard and re-upload it** — Teams enables the attachment button only after the update is applied.
</Note>

**Limits:**

* Attachments over **25 MB** are declined — your agent tells the user rather than failing silently.
* Whether a given file type can actually be interpreted depends on the model your agent uses. Anything the model can't read natively is converted to text where possible; otherwise your agent says so. See [Model capabilities](/agents/models).

**Sending files to a user.** When your agent replies with a document, Teams shows the user a consent prompt in a direct message; accepting saves the file to their OneDrive and renders it as a native Teams file. In channels and group chats the document is delivered as a link instead, because Teams has no file-transfer API there.

## Notes & limitations

* **Reactive replies and warm follow-ups only.** Your agent replies wherever it's been messaged or @mentioned. There is no cold-start path — you can't message a Teams user who has never contacted your agent. See [Channel Capabilities](/channels/channel-capabilities) for the full outbound matrix.
* **Where the bot replies.** The bot responds in the same chat or channel it was messaged or @mentioned in — a DM gets a DM reply, a channel @mention gets a channel reply.
* **Tenant admin approval.** Depending on your Microsoft 365 tenant's app policies, uploading a custom Teams app (Lua's shared bot or your own manifest) may require a Teams admin to allow custom app uploads or approve the app in the Teams admin center.
* **Further reading:** Microsoft's [Azure Bot Service documentation](https://learn.microsoft.com/en-us/azure/bot-service/) and [Teams app manifest schema](https://learn.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema).

## Sending Proactive Messages

To message a Teams user your agent is already in conversation with, load the [`User`](/api/user) and call `user.send(...)`, or use [`Channels.send`](/api/channels) with `channel: 'teams'` and `to: { userId }`:

```typescript theme={null}
import { Channels } from 'lua-cli';

await Channels.send({
  channel: 'teams',
  to: { userId },
  text: 'Heads up — your report is ready.',
});
```

<Note>
  Teams is **warm-only** — you can only reach a user who already has a conversation with your agent. See [Proactive Messaging](/channels/proactive-messaging) for the model and per-channel rules.
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="Slack" icon="slack" href="/channels/slack">
    Add Slack support
  </Card>

  <Card title="Management" icon="wrench" href="/channels/cli-management">
    Manage all channels
  </Card>
</CardGroup>