> ## 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.

# Teams permissions

> Every permission the Lua bot asks for in Microsoft Teams, what each one is for, who consents to it, and what stops working without it

This page is written for the person who has to approve the Lua app in a Microsoft 365 tenant. It lists every permission the app declares, why the agent needs it, and what happens if it is left out. Nothing here grants the app more than a member of the chat already sees.

*Verified against lua-cli 3.36.0.*

## Two kinds of access

**Bot Framework.** The bot receives messages, replies, posts on its own, and reads the list of people in a chat through the Azure Bot service. None of this needs a permission in the manifest: it comes with the bot being installed. In a group chat or team channel the Bot Framework only delivers messages that mention the bot.

**Resource-specific consent.** The Teams app manifest can ask for permissions that apply to one chat or one team at a time. Whoever installs the app in a chat consents for that chat; a tenant admin can allow or block these for the whole tenant but never has to consent per chat. They are declared in the manifest under `authorization` → `permissions` → `resourceSpecific` and are tied to the app registration named in `webApplicationInfo`. This is the model Lua uses.

Lua does not ask for any tenant-wide Microsoft Graph permission. Those require a tenant administrator to consent once for every file, chat or user in the organization, and none of the agent's features need them.

## Permissions the app declares

All five are resource-specific consent, application type, declared in the Teams app manifest.

| Permission                  | Applies to    | What the agent does with it                                                                                                                                                                        | Without it                                                                                                     |
| --------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `ChatMessage.Read.Chat`     | Group chats   | Keeps the whole conversation, not only the messages that mention the bot, so it has the context when it is next addressed. Reads the messages sent before it was added, once, when it joins.       | The agent only sees messages that mention it and answers every one of them. "What did we discuss above" fails. |
| `ChatMember.Read.Chat`      | Group chats   | Knows who is in the chat before they have spoken, with names and email addresses, so it can name people and route a request.                                                                       | A person exists for the agent only once they speak.                                                            |
| `ChatSettings.Read.Chat`    | Group chats   | Reads the chat's topic so a renamed chat keeps its name in the admin dashboard. Teams sends no event when a chat is renamed.                                                                       | The chat is named after its members until the bot is removed and added again.                                  |
| `ChannelMessage.Read.Group` | Team channels | Same as `ChatMessage.Read.Chat`, for channel threads: every post and reply in the channel reaches the agent, and a thread's earlier replies are read once when the agent is first mentioned in it. | Only mentions arrive; a thread starts empty for the agent.                                                     |
| `TeamMember.Read.Group`     | Team channels | The team's member list with names and email addresses.                                                                                                                                             | Members are known only once they post.                                                                         |

What is deliberately not there:

* `ChatMessage.Send.Chat`, `ChannelMessage.Send.Group`, `TeamsActivity.Send.*`: replying and posting go through the Bot Framework and need no permission. Adding these grants nothing the agent uses.
* Any file permission (`Files.Read.All`, `Sites.Read.All`, `Sites.ReadWrite.All`): files attached in a group chat live in the sender's OneDrive, and reading them would need a tenant-wide permission with admin consent. The agent asks for the file in a direct message instead. See [Connect Microsoft Teams](/channels/teams#channel-behavior).

## Who consents, and when

| Step                                                              | Who                                                                |
| ----------------------------------------------------------------- | ------------------------------------------------------------------ |
| Publish or upload the app with the permissions in its manifest    | The app owner (Lua for the shared bot, you for your own bot)       |
| Allow resource-specific consent for chats and teams in the tenant | Your Teams admin; the default Microsoft setting allows it          |
| Consent for one chat or team                                      | The person who adds the bot to that chat or team, when they add it |

Permissions apply to a chat or team from the moment the bot is added with them. A bot that was already there before the permissions were added keeps its old grant until it is removed and added again, and publishing a new version of the app resets a team's grant the same way: until the app is re-added, only mentions reach the bot in that team.

## Applying a new version

When a version of the app adds a permission:

1. Open the app in the [Teams Developer Portal](https://dev.teams.microsoft.com), add the permission under **Permissions**, and increase the app version.
2. **Publish to org** and have the Teams admin approve it, or download the package and upload it under **Apps → Manage your apps → Upload a custom app**.
3. In every group chat and team where the bot already is, remove the bot and add it again. Chats the bot joins later get the new permissions on install.

The package the admin dashboard offers under **Download app package (.zip)** already declares the five permissions, for the shared bot and for your own.

## Where Graph fits

For the shared conversation features the agent reads Teams data through Microsoft Graph with the bot's own app identity, and a resource-specific permission is exactly what authorizes that read for one chat or team. This works for a bot you registered yourself, because your tenant knows your app. Lua's shared bot is registered in Lua's own tenant, so the Graph-backed features (chat topic, history before the bot joined) are only available on a bot you bring yourself; everything the Bot Framework delivers works on both.