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

# Setup

> Connect your Microsoft 365 tenant to Ravenna with admin consent to enable ticket creation, AI agents, and team collaboration in Microsoft Teams.

Connect your Microsoft 365 tenant to Ravenna to enable ticket creation, AI agents, and team collaboration directly in Microsoft Teams.

## Prerequisites

<Warning>
  You must be a **Microsoft 365 global administrator** (or another role with admin consent rights) to install the Ravenna Teams app. The OAuth flow requires tenant‑wide admin consent for the Microsoft Graph permissions Ravenna uses to resolve users and channels.
</Warning>

You also need permission to **sideload or pin custom apps** in Microsoft Teams. If custom app upload is disabled tenant‑wide, ask your Teams administrator to enable it (or distribute the Ravenna app via your tenant's [Teams admin center](https://admin.teams.microsoft.com/policies/manage-apps)).

## Install Ravenna

<Steps>
  <Step title="Open Ravenna settings">
    Go to **Settings > Integrations** in your Ravenna workspace.
  </Step>

  <Step title="Add Microsoft Teams integration">
    Find **Microsoft Teams** in the Chat section and click **Connect**.
  </Step>

  <Step title="Authorize the connection">
    You'll be redirected to the Microsoft identity platform:

    1. Sign in with your Microsoft work account
    2. Review the requested permissions
    3. Click **Accept** to grant tenant‑wide admin consent
  </Step>

  <Step title="Complete setup">
    After authorization, you'll be redirected back to Ravenna with the integration connected. Ravenna extracts your Azure AD tenant ID and stores it on the integration for routing inbound messages.
  </Step>
</Steps>

<Info>
  Ravenna uses the **Microsoft identity platform** (Azure AD / Entra ID) for OAuth and the **Bot Framework** for inbound and outbound messaging. Both share a single Entra app registration on Ravenna's side.
</Info>

## Download the app package

Before the Ravenna app can appear in Microsoft Teams, publish it to your tenant. Ravenna generates the Teams app package on demand: a `.zip` file containing the app `manifest.json` and icons that Microsoft Teams needs to install the Ravenna bot.

<Steps>
  <Step title="Open the Microsoft Teams integration">
    In **Settings > Integrations**, open the **Microsoft Teams** integration you just connected.
  </Step>

  <Step title="Download the app package">
    Click **Download app package** to get the `ravenna-teams-v<version>.zip` file.

    <Note>
      The download link is short-lived (a presigned URL that expires after a few minutes). If the download fails or you need the file again later, click **Download app package** again to generate a fresh link.
    </Note>
  </Step>
</Steps>

<Note>
  The app package is **environment-specific but identical for every customer within an environment**. It points at Ravenna's shared bot for your region, not at a per-tenant bot. You don't need to rebuild or re-download the package when your Ravenna configuration changes; only download a new copy when Ravenna publishes a new manifest version.
</Note>

## Sideload the package in Microsoft Teams

Upload the downloaded `.zip` in the Microsoft Teams admin center to make the Ravenna app available in your organization.

<Steps>
  <Step title="Open the Teams admin center">
    Go to [admin.teams.microsoft.com](https://admin.teams.microsoft.com) and sign in with a Microsoft Teams admin account.
  </Step>

  <Step title="Go to Manage apps">
    In the left navigation, expand **Teams apps** and click **Manage apps**.
  </Step>

  <Step title="Upload the Ravenna package">
    Click **Actions > Upload new app**, then **Upload** and select the `ravenna-teams-v<version>.zip` file you downloaded from Ravenna.
  </Step>

  <Step title="Approve and publish">
    Once the app is uploaded, review it in **Manage apps**, set its status to **Allowed**, and, if your org requires it, publish it to your users through an app setup or permission policy.
  </Step>
</Steps>

<Note>
  Sideloading a custom app in the Teams admin center requires that **custom app uploading** is enabled for your Microsoft 365 tenant. If the upload option is greyed out, ask your Microsoft 365 administrator to enable it in the Teams admin center's app setup policies.
</Note>

## Install the Teams app

After the Ravenna app is approved in the Teams admin center, install it inside Microsoft Teams so the bot can receive messages and post into channels.

<Steps>
  <Step title="Get the Ravenna app">
    Search for **Ravenna** in the Teams app store, or find it in your organization's app catalog where you published the sideloaded package.
  </Step>

  <Step title="Add to a team">
    Click **Add to a team** and select the team you want to connect. You must be a **team owner** to grant the resource-specific consent (RSC) permissions Ravenna needs to receive all channel messages, not just @-mentions. The key RSC permission is `ChannelMessage.Read.Group`; without it the bot will only ever see messages that explicitly @-mention it.
  </Step>

  <Step title="Pick a channel">
    Choose the channel where Ravenna should be installed. The bot will become a member of that channel.
  </Step>
</Steps>

<Note>
  Resource-specific consent (RSC) is granted **per team at install time**, not tenant-wide. You must repeat the install step for each team where you want Ravenna to receive messages.
</Note>

## Connect channels

After installing the Ravenna app, connect Teams channels to Ravenna <Tooltip headline="Channels" tip="Channels organize tickets by team, topic, or workflow. Each channel has its own settings, integrations, and routing rules." cta="Learn about Channels" href="/documentation/platform/channels">Channels</Tooltip> to start receiving tickets.

<Steps>
  <Step title="@-mention the Ravenna bot">
    In the Teams channel you want to connect, post a message that @-mentions **@Ravenna**. The bot replies with an Adaptive Card asking whether you want to set up this channel as a request channel or as a triage channel.
  </Step>

  <Step title="Choose the channel type">
    Click **Set up as request channel** to create tickets from messages here, or **Set up as triage channel** to mirror tickets from across the workspace into this channel.
  </Step>

  <Step title="Select a workspace and Ravenna channel">
    Pick the Ravenna workspace and the [Channel](/documentation/platform/channels) to connect this Teams channel to. The card then confirms the connection.
  </Step>
</Steps>

<Info>
  The connect flow only fires when you @-mention the bot in a channel that doesn't have a Ravenna channel mapped yet. Regular messages in an unmapped channel are ignored so the bot doesn't butt in on unrelated conversations.
</Info>

<Callout icon="link" color="#6B7280">
  Learn how users can [create tickets](/integrations/microsoft-teams/creating-tickets) in connected Teams channels.
</Callout>

## User synchronization

Ravenna provisions Teams users on demand from Microsoft Graph the first time they interact with the bot. Internal users (matching your organization's verified domains) are provisioned as **Members**; external users are provisioned as **Guests**.

**Users are synchronized when they:**

* Post a message in a connected request channel
* DM the Ravenna bot
* Submit an Adaptive Card form
* React to a message with a configured reaction emoji

**Users are not synchronized when they:**

* Only read messages
* Are listed in a team's roster but never interact with Ravenna

Only users who actively engage with Ravenna are created in your workspace.

## Tenant routing

Each Microsoft Teams integration is scoped to one Azure AD tenant. Ravenna routes inbound Bot Framework activities to the correct integration by reading the tenant ID from the activity's `channelData.tenant.id`. You can connect at most one Microsoft Teams integration per tenant, per Ravenna organization.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The bot doesn't reply when I @-mention it">
    **Cause**: The Ravenna app may not be installed in the team, or the app installation is missing RSC permissions.

    **Solution**:

    * Confirm the Ravenna app is installed to the team (not just the channel).
    * Re-install the app. RSC permissions are granted per team at install time.
    * Ask a team owner to perform the install if you don't have owner permissions.
  </Accordion>

  <Accordion title="The bot only sees @-mentions, not every message">
    **Cause**: The team is missing the `ChannelMessage.Read.Group` resource-specific consent permission.

    **Solution**:

    * Re-install the Ravenna app to the team. RSC permissions are granted at install time and can't be added retroactively without re-install.
    * Make sure a team owner approves the install. Only owners can grant RSC.
  </Accordion>

  <Accordion title="OAuth flow fails with a consent error">
    **Cause**: The signing-in user doesn't have rights to grant tenant-wide admin consent.

    **Solution**:

    * Ask a Microsoft 365 global administrator (or a user with the Cloud Application Administrator role) to complete the connect flow.
    * Alternatively, an admin can pre-consent to the Ravenna app in [Enterprise applications](https://entra.microsoft.com/) so non-admin users can connect afterwards.
  </Accordion>
</AccordionGroup>

## Need help?

<Callout icon="link" color="#6B7280">
  Having issues with your Microsoft Teams integration? Check our [support page](/integrations/microsoft-teams/support) for troubleshooting help.
</Callout>