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

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.

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

Install Ravenna

1. Open Ravenna settings

   Go to Settings > Integrations in your Ravenna workspace.

2. Add Microsoft Teams integration

   Find Microsoft Teams in the Chat section and click Connect.

3. 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
4. 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.

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.

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.

1. Open the Microsoft Teams integration

   In Settings > Integrations, open the Microsoft Teams integration you just connected.

2. Download the app package

   Click Download app package to get the ravenna-teams-v<version>.zip file.

   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.

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.

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.

1. Open the Teams admin center

   Go to admin.teams.microsoft.com and sign in with a Microsoft Teams admin account.

2. Go to Manage apps

   In the left navigation, expand Teams apps and click Manage apps.

3. Upload the Ravenna package

   Click Actions > Upload new app, then Upload and select the ravenna-teams-v<version>.zip file you downloaded from Ravenna.

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

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.

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.

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

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

3. Pick a channel

   Choose the channel where Ravenna should be installed. The bot will become a member of that channel.

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.

Connect channels

After installing the Ravenna app, connect Teams channels to Ravenna Channels to start receiving tickets.

1. @-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.

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

3. Select a workspace and Ravenna channel

   Pick the Ravenna workspace and the Channel to connect this Teams channel to. The card then confirms the connection.

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.

Learn how users can create tickets in connected Teams channels.

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

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.

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.

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 so non-admin users can connect afterwards.

Need help?

Having issues with your Microsoft Teams integration? Check our support page for troubleshooting help.