Overview
This is the complete, click-by-click walkthrough for the bring-your-own-bot path: you create a bot in Microsoft Azure under your own app registration, point it at Lua, and connect it to your agent. Choose this path if your organization requires its own Azure app registration, or you want the bot to appear under your own name and branding.Just want the fastest route with no Azure setup? Use Lua’s shared Teams bot instead — no Azure account, no app registration. This page is only for teams that want to run their own bot.
Before you start
Two roles are involved. It’s fine if that’s two different people — each step notes who does what.An Azure subscription
With permission to create a resource and register an app in your Microsoft Entra ID (formerly Azure AD) directory. Usually an IT / cloud administrator.
A Teams administrator
To allow a custom app to be uploaded, or to approve it for the whole organization. Good to line up early.
Your Lua login
Access to the Lua admin dashboard for the agent you want to put in Teams.
Cost: an Azure Bot’s free pricing tier (F0) is enough — the Microsoft Teams channel is included at no charge.
How the pieces fit together
You’re building a small chain:Azure Bot (identity + message router) → its messaging endpoint points at Lua → a Teams app wraps the bot so people can add it → the Lua dashboard ties the bot to your agent.
Part 1 — Create the Azure Bot
Done in the Azure Portal. This creates the bot’s identity, points it at Lua, and turns on Teams.Open the Azure Portal and start a new Azure Bot
Go to portal.azure.com and sign in with your work account. In the top search bar type Azure Bot, then select Azure Bot (publisher: Microsoft). On the product page, click Create.
Fill in the Create an Azure Bot form
Work down the fields:Click Review + create, then Create. When deployment finishes, click Go to resource.
- Bot handle — a unique name for the resource, e.g.
contoso-lua-bot. This is an internal label; it isn’t the name users see in Teams. - Subscription — pick your Azure subscription.
- Resource group — choose an existing one or click Create new (a resource group is just a folder for related Azure resources, e.g.
rg-lua-teams). - Pricing tier — click Change plan if needed and choose Free (F0).
- Type of App — choose Single Tenant. Your bot serves only your own organization — this is the correct, recommended choice.
- Creation type — leave Create new Microsoft App ID selected. Azure creates the app registration (the bot’s identity) for you.
What “Microsoft App ID” is: choosing Create new Microsoft App ID makes Azure register an application in your Entra ID directory alongside the bot. That app registration is the bot’s login identity, and its Application (client) ID is what everyone calls the App ID — you’ll copy it into Lua shortly.
Set the Messaging endpoint (point the bot at Lua)
In the left menu open Settings → Configuration. Find the Messaging endpoint field and paste exactly:Then click Apply.
The messaging endpoint is the address Microsoft calls every time someone messages your bot. Setting it to Lua’s URL is what makes messages reach your agent. It’s the same for everyone — no per-organization part.
Copy your App ID and Tenant ID
Still on Settings → Configuration, copy the Microsoft App ID and keep it safe — that’s one of the three values Lua needs.To get the Tenant ID, click the Manage Password link next to the App ID — this opens the bot’s app registration. On its Overview page both are labelled precisely:
- Application (client) ID = your App ID
- Directory (tenant) ID = your Tenant ID
Another place to find the Tenant ID: search Microsoft Entra ID (or “Azure Active Directory”) in the top bar → Overview → Tenant ID. It’s a single GUID that identifies your whole organization’s directory — the same value everywhere.
Create the client secret (the bot's password)
You should now be on the app registration (from Manage Password). In the left menu open Certificates & secrets → the Client secrets tab → New client secret.
- Description — e.g.
Lua Teams bot. - Expires — pick a duration (e.g. 24 months). Note this date.
Turn on the Microsoft Teams channel
Go back to the Azure Bot resource (not the app registration). Open Settings → Channels and click the Microsoft Teams icon.
- Accept the Terms of Service.
- Leave the default Microsoft Teams Commercial option selected.
- Click Apply / Save.
Azure is done. The bot exists, points at Lua, and speaks Teams — and you’ve collected the three values Lua needs: App ID, App password (secret Value), and Tenant ID.
Part 2 — Connect the bot in the Lua dashboard
This links the bot to your agent — and hands you a ready-to-install Teams app package.Open your agent's Channels
Sign in to the Lua admin dashboard, open Agents, choose the agent you want in Teams, and open its Channels. Click Connect (the + / add-channel control) and choose Microsoft Teams.
Choose Bring your own Azure Bot
When asked how you want to connect, pick Bring your own Azure Bot. (The other option, Use Lua’s Teams bot, skips Azure entirely but runs under Lua’s identity.)
Paste the three Azure values
Enter the values from Part 1, then click Connect:
- App ID — the Application (client) ID.
- App password — the client secret Value.
- Tenant ID — the Directory (tenant) ID.
This is where the bot links to your agent — no connect link needed. Your Azure Bot has its own unique App ID, so these three values are the connection. The moment you click Connect, Lua stores an active route — (your App ID + Tenant ID) → this agent — and you’re linked. There’s no in-chat “connect” step like Lua’s shared bot uses.Because the identity comes entirely from Azure, you can complete this step before you’ve built or installed the Teams app — the bot’s identity and the Teams app (the wrapper people add) are separate. The route is live immediately, but nothing reaches the bot until its messaging endpoint points at Lua and the Teams app is installed (Parts 3–4).
Download your app package and confirm the endpoint
After connecting, Lua shows a short setup panel that:
- Lets you download the Teams app package — a
.zipwith your bot’s App ID already baked in. This is the easy route in Part 3. - Reminds you the Azure messaging endpoint must be
https://wa.heylua.ai/teams/webhook, which you already set.
.zip handy — you’ll upload it to Teams next.Part 3 — The Teams app package
The bot needs a Teams “app” wrapper so people can add it. There are two ways to get one — pick either.Use the package Lua generated
Recommended · easiest. In Part 2 you downloaded a ready-made
.zip with your App ID already inside. Nothing more to build — skip straight to Part 4 and install it.Build your own in the Teams Developer Portal
Alternative. Choose this if you want your own name, icons, and description, or to publish it to your organization’s app catalog. Steps below.
Bot vs. Teams app: the Azure Bot is the engine. The Teams app is the wrapper Teams users actually add — it carries the name, icon, and a pointer to your bot. Both packages produce the same result: a Teams app pointing at your bot’s App ID.
Option B — build it in the Teams Developer Portal
Create a new app
Go to dev.teams.microsoft.com, sign in with your Microsoft 365 account, open Apps → New app, give it a name, and click Add.
The App ID shown here is the Teams app ID — a different GUID from your bot’s App ID. That’s expected; they’re two different things.
Fill in Basic information
Complete the required fields: short and long name and description, developer/company name, website, and privacy + terms of use URLs. Teams requires these before it will let you publish or download.
Add the Bot feature and link your Azure Bot
Open App features → Bot. Under “Identify your bot”, choose Select an existing bot and pick the Azure Bot you created — or choose Enter a bot ID manually and paste your bot’s App ID (the Microsoft App ID from Part 1).Under scopes, tick all three so the bot works everywhere:
- Personal — direct messages
- Team — @mentions in channels
- Group chat — group conversations
Add icons (optional but recommended)
Under Branding / Icons, upload a color icon (192×192 px) and an outline icon (32×32 px, transparent). This is what your team sees in Teams.
Publish or download
Open Publish and pick one:
- Publish to org — submits the app to your Teams admin; once approved it appears in Built for your org for everyone to add. Best for a real rollout.
- Download app package — gives you a
.zipto install manually (same as the Lua-generated one). Best for a quick test.
Part 4 — Install and test in Teams
Make sure custom apps can be uploaded
Many tenants block custom app uploads by default. If the upload option is greyed out, a Teams admin enables it in the Teams admin center → Teams apps → Setup policies → Upload custom apps. If you published to org in Part 3 instead, the admin approves it under Teams apps → Manage apps.
Upload the app package
In Microsoft Teams, open Apps (left rail) → Manage your apps → Upload an app → Upload a custom app, and select the
.zip from Part 2 or 3.Add the bot where you want it
Add it to yourself (a personal chat with the bot), to a team/channel, or to a group chat — matching the scopes you enabled.
Say hello
Direct message the bot, or @mention it in a channel. Your Lua agent replies — you’re live.
How the bot behaves: it replies where it’s spoken to (a DM gets a DM reply; a channel @mention gets a channel reply). It responds when messaged and can follow up in an existing conversation, but it can’t cold-message someone who has never contacted it. See Proactive Messaging for the details.
Reference
Everything you copy or set, in one place.| What Lua asks for | Where it comes from (Azure) | Its exact label |
|---|---|---|
| App ID | App registration → Overview | Application (client) ID |
| App password | App registration → Certificates & secrets | Client secret → Value |
| Tenant ID | App registration → Overview (or Entra ID → Overview) | Directory (tenant) ID |
| Setting | Value |
|---|---|
| Azure Bot — Type of App | Single Tenant |
| Azure Bot — Messaging endpoint | https://wa.heylua.ai/teams/webhook |
| Azure Bot — Channel | Microsoft Teams (Commercial) |
| Teams app — Bot scopes | Personal · Team · Group chat |
| Teams app — Icons | Color 192×192 · Outline 32×32 |
Troubleshooting
The bot never replies
The bot never replies
- Re-check the messaging endpoint is exactly
https://wa.heylua.ai/teams/webhook(no trailing space) and that you clicked Apply. - Confirm the Microsoft Teams channel shows as Running on the Azure Bot.
- Confirm the three values in Lua are correct — a mistyped App password is the most common cause.
'Upload a custom app' is greyed out
'Upload a custom app' is greyed out
Your tenant blocks custom app uploads. A Teams admin turns it on in Teams admin center → Teams apps → Setup policies → Upload custom apps, or approves the app after you Publish to org.
It worked, then suddenly stopped
It worked, then suddenly stopped
Your client secret expired. Create a new secret (Part 1, step 5), copy the new Value, and update the App password in the Lua dashboard.
Next steps
Microsoft Teams overview
The shared-bot quick start and the big picture for Teams.
Proactive messaging
How your agent follows up in existing conversations.