> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getinboxzero.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Microsoft Teams Integration Setup

> Set up the Teams bot for Inbox Zero assistant chat.

This guide is for self-hosted deployments that want to enable Teams chat with the Inbox Zero assistant.

## What Teams currently supports

* AI assistant chat in **direct messages** with the Inbox Zero bot
* Account linking with one-time `/connect <code>` commands
* Direct-message delivery for meeting briefs, follow-up reminders, email digests, filing alerts, and rule notifications configured from **Channels**

Currently not supported on Teams:

* Delivery into Teams channels; automated notifications are delivered in the linked bot DM
* One-click draft editing and sending inside Teams; review or send those drafts in Inbox Zero

## 1. Create an Azure Bot resource

1. Go to [portal.azure.com](https://portal.azure.com)
2. Click **Create a resource**, search for **Azure Bot**, and select it
3. Click **Create** and fill in:
   * **Bot handle**: a unique identifier for your bot
   * **Subscription**: your Azure subscription
   * **Resource group**: create new or use existing
   * **Pricing tier**: F0 (free) for testing
   * **Type of App**: Single Tenant (recommended) or Multi Tenant
   * **Creation type**: Use existing Microsoft App ID or create a new one
4. Click **Review + create**, then **Create**

You can reuse the same Microsoft App ID you already use for Outlook OAuth. We recommend a separate app registration for Teams bot traffic so bot credentials and permissions are isolated from email OAuth.

## 2. Get your app credentials

From your new Bot resource:

1. Go to **Configuration**
2. Copy **Microsoft App ID** — this is your `TEAMS_BOT_APP_ID`
3. Click **Manage Password** (next to Microsoft App ID)
4. In the App Registration page, go to **Certificates & secrets**
5. Click **New client secret**, add a description, choose an expiry, click **Add**
6. Copy the **Value** immediately (it's only shown once) — this is your `TEAMS_BOT_APP_PASSWORD`
7. Go to **Overview** and copy **Directory (tenant) ID** — this is your `TEAMS_BOT_APP_TENANT_ID`

## 3. Set the messaging endpoint

1. In your Azure Bot resource, go to **Configuration**
2. Set **Messaging endpoint** to:

```text theme={null}
https://<your-domain>/api/teams/events
```

3. Click **Apply**

## 4. Enable the Teams channel

1. In your Azure Bot resource, go to **Channels**
2. Click **Microsoft Teams**
3. Accept the terms of service
4. Click **Apply**

## 5. Create and upload the Teams app package

Create a `manifest.json` file with your bot details:

```json theme={null}
{
  "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.16/MicrosoftTeams.schema.json",
  "manifestVersion": "1.16",
  "version": "1.0.0",
  "id": "<your-app-id>",
  "packageName": "com.yourcompany.inboxzero",
  "developer": {
    "name": "Your Company",
    "websiteUrl": "https://your-domain.com",
    "privacyUrl": "https://your-domain.com/privacy",
    "termsOfUseUrl": "https://your-domain.com/terms"
  },
  "name": {
    "short": "Inbox Zero",
    "full": "Inbox Zero Assistant"
  },
  "description": {
    "short": "Manage email with Inbox Zero for Microsoft Teams",
    "full": "Manage email with your Inbox Zero AI assistant in Microsoft Teams. An active Inbox Zero account is required. Sign up or get started at https://your-domain.com. For help, visit https://your-domain.com/docs/essentials/channels or contact support@your-domain.com. AI-generated content may be inaccurate and should be reviewed before use. Report objectionable AI-generated content to support@your-domain.com."
  },
  "icons": {
    "outline": "outline.png",
    "color": "color.png"
  },
  "accentColor": "#FFFFFF",
  "bots": [
    {
      "botId": "<your-app-id>",
      "scopes": ["personal"],
      "supportsFiles": false,
      "isNotificationOnly": false,
      "commandLists": [
        {
          "scopes": ["personal"],
          "commands": [
            { "title": "connect", "description": "Link an Inbox Zero account with a connect code" },
            { "title": "switch", "description": "List or switch linked Inbox Zero accounts" },
            { "title": "help", "description": "Show help and supported commands" },
            { "title": "cleanup", "description": "Help clean up your inbox" },
            { "title": "summary", "description": "Summarize what needs attention" },
            { "title": "draftreply", "description": "Draft a reply to an urgent email" },
            { "title": "followups", "description": "Show emails that need a follow-up" }
          ]
        }
      ]
    }
  ],
  "permissions": ["identity", "messageTeamMembers"],
  "validDomains": ["your-domain.com"]
}
```

Replace `<your-app-id>` with your `TEAMS_BOT_APP_ID` and `your-domain.com` with your actual domain.

You'll also need two matching icon files: a 32×32 `outline.png` and a 192×192 `color.png`. The outline icon must use a white symbol on a transparent background, contain no extra padding, and depict the same symbol as the color icon. Zip those three files together.

**To install for testing (sideloading):**

1. In Teams, click **Apps** in the sidebar
2. Click **Manage your apps** → **Upload an app**
3. Click **Upload a custom app** and select your zip file

**For organization-wide deployment:**

1. Go to the [Teams Admin Center](https://admin.teams.microsoft.com)
2. Go to **Teams apps** → **Manage apps**
3. Click **Upload new app** and select your zip file
4. Use **Setup policies** to control who can access the app

## 6. Set environment variables

Set these in `apps/web/.env` (or your deployment env):

```bash theme={null}
TEAMS_BOT_APP_ID=
TEAMS_BOT_APP_PASSWORD=
TEAMS_BOT_APP_TENANT_ID=      # required for the single-tenant Teams bot
```

If `TEAMS_BOT_APP_ID`, `TEAMS_BOT_APP_PASSWORD`, or `TEAMS_BOT_APP_TENANT_ID` is missing, the Teams connect option is hidden in the UI and `/api/teams/events` returns `503`.

## 7. Connect a user account from Inbox Zero

Each Inbox Zero email account links to a Teams user via a connect code:

1. In Inbox Zero, go to **Settings** → **Connected Apps**
2. Click **Connect Teams**
3. Copy the generated command: `/connect <code>`
4. Open a DM with the Inbox Zero bot in Teams
5. Send the command

After linking, the user can chat with the assistant in that DM.

## 8. Validate end-to-end

Quick checks:

1. `POST /api/teams/events` returns `200` for valid bot activity
2. Before linking, `Hello` returns account setup guidance and `/help` lists supported commands
3. An unknown slash command points the user to `/help`
4. Sending `/connect <code>` in the bot DM links the account
5. `/summary`, `/cleanup`, `/draftreply`, and `/followups` return useful responses after linking

If linking fails, generate a new code — codes are one-time and expire after 10 minutes.

<Tip>
  You can also set up most of this integration with the Azure CLI (`az`) instead of clicking through the Azure portal. If you already have `az` installed and are logged in, an agentic coding tool like Claude Code or Codex can usually create the Entra app registration, client secret, resource group, Azure Bot resource, messaging endpoint, and Teams channel for you. You will still need to complete the browser-authenticated steps yourself, such as accepting Teams channel terms if prompted and uploading/installing the Teams app package.

  Example prompt:

  ```text theme={null}
  Use Azure CLI to set up the Microsoft Teams integration for Inbox Zero. Create a single-tenant Entra app registration with a client secret, create an Azure Bot resource on the F0 tier, point it at https://<your-domain>/api/teams/events, enable the Teams channel, and then tell me exactly which environment variables and manual Azure/Teams UI steps are left for me to complete.
  ```
</Tip>