Skip to main content
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.38.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 asks for no tenant-wide Microsoft Graph permission by default. Those require a tenant administrator to consent once for every file, chat or user in the organization. One is optional: Files.Read.All, which lets the agent open files people attach in group chats and channels. See Optional tenant-wide permission.

​
Permissions the app declares

All seven are resource-specific consent, application type, declared in the Teams app manifest. 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.
  • Sites.Read.All, Sites.ReadWrite.All, Files.ReadWrite.All: the optional file permission below is the read-only Files.Read.All; nothing wider is needed and nothing is ever written to a drive.

​
Optional tenant-wide permission

Teams does not deliver a file attached with the paperclip, or dragged into a group chat or channel, to a bot. That is a documented Microsoft limitation, not something the manifest can ask for. Lua works around it through Microsoft Graph: it reads Graph’s copy of the message to learn which file was attached, then downloads the file through Graph. That read needs a Microsoft Graph application permission that applies to the whole tenant, so it is not part of the manifest and is off by default. Without it the agent is told that such files do not reach it and says so; pasted images and files sent in a direct message work regardless. To grant it, a Microsoft 365 administrator opens Microsoft Entra and follows these steps on the app registration behind your own Azure Bot. The shared Lua bot’s registration lives in Lua’s tenant, so it cannot be granted this in yours.
  1. App registrations, then open the app registration behind the bot.
  2. API permissions.
  3. Add a permission.
  4. Microsoft Graph.
  5. Application permissions.
  6. Tick Files.Read.All, then Add.
  7. Grant admin consent.
It applies to every chat and channel the bot is in within about an hour, and the bot does not need to be removed and added again.

​
Who consents, and when

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, 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 seven permissions, for the shared bot and for your own.

​
What the agent knows about its own access

Any of these permissions can be missing in a given chat: the bot was added before the permission existed, the app was updated and not re-added, or the tenant blocks resource-specific consent. The agent is told rather than left to guess.
  • When the bot is added to a chat or team, and every ten minutes while people talk to it, Lua reads which permissions that chat or team granted. With TeamsAppInstallation.Read.Chat (or .Group) this is a direct read; without it Lua uses what the turn itself proved, and never claims a permission is missing on that basis alone.
  • When something is missing the agent’s instructions for that turn say so, in one or two sentences, with the fix: for a chat permission, “the person who added you needs to remove and re-add the app”; for file access, “a Microsoft 365 administrator must grant the Teams app the file permission”. Nothing is added when the grant set is complete.
  • The same reading is visible in the admin dashboard: the agent’s Group chats tab shows a Limited permissions label on the conversation with the missing permission names, and the channel card shows Graph unavailable when the tenant does not know the bot’s app at all.
  • Agent code reads it as Lua.request.conversation.access.
For Lua’s shared bot in your tenant, the Graph reads are not possible (see below), so the agent is told nothing about permissions and the dashboard shows Graph unavailable; with your own bot the whole picture is available. The channel card also shows No file access until the optional file permission above is granted.

​
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 are only available on a bot you bring yourself: the chat topic, the history from before the bot joined, reading which permissions a chat granted, and files attached in group chats and channels. Everything the Bot Framework delivers works on both bots: mentions, replies, the roster through the bot service, files sent in a direct message, and pasted images.