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

# Bring Your Own Azure Bot

> Create your own Microsoft Azure Bot and connect it to your Lua agent for Microsoft Teams — every step, click by click.

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

<Note>
  Just want the fastest route with no Azure setup? Use **[Lua's shared Teams bot](/channels/teams)** instead — no Azure account, no app registration. This page is only for teams that want to run their own bot.
</Note>

The whole flow is short once you see the shape: **create the bot in Azure → hand its three values to Lua → install the Teams app.** Budget about 25–35 minutes.

## Before you start

Two roles are involved. It's fine if that's two different people — each step notes who does what.

<CardGroup cols={3}>
  <Card title="An Azure subscription" icon="cloud">
    With permission to create a resource and register an app in your Microsoft Entra ID (formerly Azure AD) directory. Usually an IT / cloud administrator.
  </Card>

  <Card title="A Teams administrator" icon="user-shield">
    To allow a custom app to be uploaded, or to approve it for the whole organization. Good to line up early.
  </Card>

  <Card title="Your Lua login" icon="key">
    Access to the Lua admin dashboard for the agent you want to put in Teams.
  </Card>
</CardGroup>

<Info>
  **Cost:** an Azure Bot's free pricing tier (**F0**) is enough — the Microsoft Teams channel is included at no charge.
</Info>

## How the pieces fit together

You're building a small chain:

<Info>
  **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.
</Info>

Two of those produce values you'll copy into Lua — the bot's **App ID**, its **password (client secret)**, and your **Tenant ID**.

One thing worth knowing up front: because your bot's App ID is **unique to you**, handing those three values to Lua is *all it takes* to link the bot to your agent — there's no in-chat confirmation step, and you can even do it **before the Teams app exists**. The bot's identity (from Azure) and the Teams app (the wrapper people install) are separate things. More on this in Part 2.

## Part 1 — Create the Azure Bot

Done in the [Azure Portal](https://portal.azure.com). This creates the bot's identity, points it at Lua, and turns on Teams.

<Steps>
  <Step title="Open the Azure Portal and start a new Azure Bot">
    Go to [portal.azure.com](https://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**.
  </Step>

  <Step title="Fill in the Create an Azure Bot form">
    Work down the fields:

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

    <Info>
      **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.
    </Info>

    Click **Review + create**, then **Create**. When deployment finishes, click **Go to resource**.
  </Step>

  <Step title="Set the Messaging endpoint (point the bot at Lua)">
    In the left menu open **Settings → Configuration**. Find the **Messaging endpoint** field and paste exactly:

    ```
    https://wa.heylua.ai/teams/webhook
    ```

    Then click **Apply**.

    <Info>
      **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.
    </Info>
  </Step>

  <Step title="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**

    <Note>
      **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.
    </Note>
  </Step>

  <Step title="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.

    Click **Add**. A row appears with a **Value** and a **Secret ID**.

    <Warning>
      **Copy the Value now.** Copy the **Value** column immediately (not the Secret ID) — Azure hides it forever the moment you leave the page. If you miss it, delete the secret and create a new one. This Value is the **App password** Lua asks for.
    </Warning>

    <Warning>
      **Set a renewal reminder.** When the secret **expires**, the bot stops replying until you create a new one and update it in Lua. Add a calendar reminder a couple of weeks before the expiry date you chose.
    </Warning>
  </Step>

  <Step title="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**.

    Teams should now show as a connected channel with status *Running*.

    <Check>
      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**.
    </Check>
  </Step>
</Steps>

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

<Steps>
  <Step title="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**.
  </Step>

  <Step title="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.)
  </Step>

  <Step title="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.

    <Info>
      **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).
    </Info>
  </Step>

  <Step title="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 `.zip` with 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.

    Keep this `.zip` handy — you'll upload it to Teams next.
  </Step>
</Steps>

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

<CardGroup cols={2}>
  <Card title="Use the package Lua generated" icon="bolt">
    **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.
  </Card>

  <Card title="Build your own in the Teams Developer Portal" icon="screwdriver-wrench">
    **Alternative.** Choose this if you want your own name, icons, and description, or to publish it to your organization's app catalog. Steps below.
  </Card>
</CardGroup>

<Info>
  **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.
</Info>

### Option B — build it in the Teams Developer Portal

<Steps>
  <Step title="Create a new app">
    Go to [dev.teams.microsoft.com](https://dev.teams.microsoft.com), sign in with your Microsoft 365 account, open **Apps → New app**, give it a name, and click **Add**.

    <Note>
      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.
    </Note>
  </Step>

  <Step title="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.
  </Step>

  <Step title="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

    Save.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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 `.zip` to install manually (same as the Lua-generated one). Best for a quick test.
  </Step>
</Steps>

## Part 4 — Install and test in Teams

<Steps>
  <Step title="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**.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Say hello">
    **Direct message** the bot, or **@mention** it in a channel. Your Lua agent replies — you're live.

    <Note>
      **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](/channels/proactive-messaging) for the details.
    </Note>
  </Step>
</Steps>

## Reference

Everything you copy or set, in one place.

```
https://wa.heylua.ai/teams/webhook
```

| 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="'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*.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Sign-in or authorization error right after setup">
    Occasionally a freshly created bot needs a minute for its identity to propagate across Microsoft. Give it a few minutes and try again.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Microsoft Teams overview" icon="comments" href="/channels/teams">
    The shared-bot quick start and the big picture for Teams.
  </Card>

  <Card title="Proactive messaging" icon="paper-plane" href="/channels/proactive-messaging">
    How your agent follows up in existing conversations.
  </Card>
</CardGroup>