Skip to main content
After this guide, your agent runs in Microsoft Teams under a bot you registered in your own Azure tenant, with your name and icon. Three values from Azure are the whole connection: the bot’s App ID, its client secret, and your tenant ID. Choose this over Lua’s shared bot when your organization requires its own app registration or its own branding, and whenever you want the Microsoft Graph features. Those features (the chat topic, the history from before the bot joined, reading which permissions a chat granted, and files attached in group chats and channels) need an app registration in your own tenant, so they are available on this path only. Budget 25 to 35 minutes; an Azure administrator and a Teams administrator may be two people. Verified against lua-cli 3.38.0. Before you begin
  • An Azure subscription with permission to create a resource and register an application in your Microsoft Entra ID directory. The free F0 tier is enough; the Teams channel costs nothing extra.
  • A Teams admin who can allow custom app uploads or approve an app for the organization.
  • An agent with a promoted production version; see Release an agent.
1

Provider console: create the Azure Bot

In the Azure Portal search for Azure Bot (publisher Microsoft) and select Create. Give it a bot handle (an internal name), pick the subscription and a resource group, choose Free (F0), set Type of App to Single Tenant, and leave Create new Microsoft App ID selected so Azure registers the bot’s identity for you. Select Review + create, then Create, then Go to resource.
2

Provider console: set the messaging endpoint

Under Settings → Configuration, set Messaging endpoint to the address Microsoft calls for every message and select Apply. It is the same for every organization.
3

Provider console: collect the three values

On the same page copy the Microsoft App ID. Select Manage Password to open the bot’s app registration; its Overview shows Application (client) ID (the App ID again) and Directory (tenant) ID (your tenant ID). Under Certificates & secrets → Client secrets, select New client secret, pick an expiry, and copy the Value column at once; Azure hides it when you leave the page. That value is the app password.
4

Provider console: enable the Teams channel

Back on the Azure Bot resource, open Settings → Channels, select Microsoft Teams, accept the terms, keep Microsoft Teams Commercial, and apply. Teams shows as running.
5

Dashboard: connect the bot to your agent

In the admin dashboard open Agents, select the agent, select + in the Channels section of its Overview tab, choose Microsoft Teams in Connect a channel, then Bring your own Azure Bot and Yes, I already have an Azure Bot. Enter the App ID, App password, and Tenant ID and select Connect; the wizard has no tenant-type switch and assumes the single-tenant bot from the first step. The channel is active immediately. The dialog that follows repeats the messaging endpoint to check against Azure and offers Download app package (.zip), a ready-made Teams app you can upload instead of building one in the next step.
6

Provider console: build the Teams app

In the Teams Developer Portal create a new app, fill in the required basic information (names, descriptions, developer, website, privacy and terms URLs), and under App features → Bot select your existing Azure Bot or paste its App ID. Tick the Personal, Team, and Group chat scopes. Under Permissions add the seven resource-specific permissions from Teams permissions. For group chats: ChatMessage.Read.Chat, ChatMember.Read.Chat, ChatSettings.Read.Chat, TeamsAppInstallation.Read.Chat. For team channels: ChannelMessage.Read.Group, TeamMember.Read.Group, TeamsAppInstallation.Read.Group. Together they let the agent keep the whole transcript of a group chat, see who is in it, read what was said before it joined, and know which permissions the chat granted. The package the dashboard offers already declares all seven. Add a 192×192 color icon and a 32×32 outline icon, then either Publish to org for admin approval or Download app package for a manual install.
7

Verify

In Teams, open Apps → Manage your apps → Upload a custom app and pick the package, or add the published app. Send the bot hello in a direct message; your agent answers. Mention it in a channel; it answers there.

​
Values and settings

​
Limits

  • One App ID and tenant pair per agent. A second connection for the same pair is refused with A Teams channel for this bot and tenant is already connected.
  • Inbound files: 25 MB. In a direct message they always reach the agent; in a group chat or channel they need the optional Files.Read.All below. See Connect Microsoft Teams for what Teams delivers where.
  • The client secret expires on the date you chose. When it does, the bot stops answering until you create a new secret and update the channel.

​
Permissions to set up next

Azure gives the agent its identity. Two more things decide what it can see once it is in a chat, and both are covered in full on Teams permissions.
  • The seven resource-specific permissions in the Teams app manifest. The package the admin dashboard offers already declares them. Whoever adds the bot to a group chat or a team consents for that chat or team, and no tenant administrator is involved. The grant is taken when the bot is added, so after publishing a new version of the app, remove the bot and add it again in each group chat and team.
  • The optional Files.Read.All Microsoft Graph permission. A Microsoft 365 administrator grants it once, with admin consent, on the app registration you created above, and it takes effect within about an hour with no re-add. It is what lets the agent open files people attach in group chats and channels, and the channel card shows No file access until it is granted. It is read-only; Lua never writes to a drive. See Optional tenant-wide permission for the exact steps in Microsoft Entra.
Because both sit on an app registration in your tenant, this is the only path on which the Microsoft Graph features work. With Lua’s shared bot the registration lives in Lua’s tenant, nothing in yours can be granted to it, and the channel card shows Graph unavailable.

​
Troubleshooting

Check the messaging endpoint is exactly https://wa.heylua.ai/teams/webhook and was applied, that the Microsoft Teams channel shows as running on the Azure Bot, and that the app password is the secret’s Value, not its ID.
Lua received a message for your App ID from a tenant other than the one you entered. Check the tenant ID against Directory (tenant) ID on the app registration; the bot is connected as single-tenant, so only that tenant can reach the agent.
The client secret expired. Create a new one under Certificates & secrets, copy its value, and update the app password on the channel in the admin dashboard.

​
Next steps

Connect Microsoft Teams

What Teams delivers to the agent, group chats, limits, and proactive sends.

Teams permissions

The seven manifest permissions, the optional file permission, and who consents.

Send proactive messages

Follow up with a person or a group conversation.