--- title: "Microsoft Teams integration | Grafana Cloud documentation" description: "Configure and use the Grafana Assistant Microsoft Teams integration to interact with Assistant directly from Teams channels." --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # Microsoft Teams integration > Note > > Grafana Assistant Microsoft Teams integration is currently in [private preview](/docs/release-life-cycle/). Grafana Labs offers support on a best-effort basis, and breaking changes might occur prior to the feature being made generally available. The Microsoft Teams integration connects your Teams workspace to Grafana Assistant. You can interact with Assistant directly in Teams channels, direct messages, and group chats to ask questions about your observability data, build queries, and investigate incidents without leaving Teams. ## What you’ll achieve - Connect your MS Teams instances to Grafana Cloud. - Ask questions and query telemetry data from Teams channels and direct messages. - Investigate incidents and find dashboards using natural language. ## Before you begin To install the Assistant app for Microsoft Teams, you must: - have an Admin role in Grafana Cloud - be a Global Administrator or Application Administrator in your MS teams workspace After the workspace is connected, all users in your Grafana Cloud stack can interact with Assistant in Teams by linking their individual accounts. ## Set up the integration ### Step 1: Add the preview MS Teams app (admin) 1. [Download the Grafana MS Teams preview app](https://storage.googleapis.com/grafana-assistant-msteam-app/grafana-msteams-preview.zip). 2. In Microsoft Teams, go to **Apps** in the left sidebar and select **Manage your apps**. 3. Click **Upload an app** and select **Upload a custom app**. 4. Select the downloaded `.zip` file and click **Add**. 5. Click **Add** again to confirm and install the app. ### Step 2: Connect your workspace (admin) A Grafana admin must connect your Microsoft Teams workspace to Grafana Cloud before anyone can use the integration. 1. In Grafana Cloud, navigate to **Assistant** > **Settings** > **External connections** > **Microsoft Teams**. 2. Click **Connect Microsoft Teams**. 3. You are redirected to Microsoft to grant admin consent for the Grafana Assistant bot. 4. Sign in with an account that has Global Administrator or Application Administrator permissions in your Microsoft Teams workspace. 5. Review the requested permissions and click **Accept**. 6. Microsoft redirects you back to Grafana, and the workspace connection is established automatically. > Note > > You can connect one Microsoft Teams workspace per Grafana Cloud stack. ### Step 3: Link your account (each user) Each user must link their Microsoft Teams identity to their Grafana account before the bot can respond to their messages. 1. In Microsoft Teams, open a direct message with the **Grafana Assistant** bot. 2. Send any message to the bot. 3. The bot replies with an **Account Setup Required** card. Click **Link Your Account**. 4. You are redirected to the Grafana Assistant settings page. Review the displayed Teams account details and click **Confirm Setup**. Your Microsoft Teams account is now linked to your Grafana account. > Note > > The setup link expires after 15 minutes. If the link has expired, send another message to the bot to receive a fresh link. ## How requests are processed Microsoft Teams sends messages to Grafana Assistant through Microsoft Bot Framework. Grafana Cloud maps each message to the connected Grafana Cloud stack and the sender’s linked Grafana user, applies that user’s Grafana role and data source permissions, and processes the request. If model inference is required, Grafana Cloud calls the configured model provider. Microsoft Teams doesn’t connect directly to the model provider. Responses return to Microsoft Teams through Microsoft Bot Framework. ### Disconnect or unlink **To disconnect the entire workspace** (admin only): 1. Navigate to **Assistant** > **Settings** > **External connections** > **Microsoft Teams**. 2. Click **Disconnect Workspace**. This removes the workspace connection for all users. Individual account links are also removed. **To unlink your personal account**: 1. Navigate to **Assistant** > **Settings** > **External connections** > **Microsoft Teams**. 2. Click **Unlink Account**. You can re-link your account at any time by messaging the bot again. ## Use Assistant ### Channels In Teams channels, mention the Grafana Assistant bot to start a conversation. The bot responds in a thread to keep conversations organized. > @Grafana show me CPU usage for the last hour The bot only responds when explicitly mentioned with `@Grafana`. Thread context is preserved so you can continue a conversation with follow-up mentions in the same thread. ### Direct messages In a direct message with the bot, send your question directly without any mention. Every message in the conversation starts or continues the same assistant context. > show me error rates in the last 30 minutes ### Group chats In group chats that include the bot, send any message and the bot responds. Like direct messages, no explicit mention is required. ### Query your data Ask questions about your metrics and logs using natural language. > @Grafana show me CPU usage for the last hour ### Find dashboards Locate existing dashboards relevant to your query without searching through folders. > @Grafana what dashboards do we have for database monitoring? ### Investigate incidents Ask Assistant to analyze spikes or anomalies to help uncover root causes. > @Grafana what’s causing the high latency? ### Build query syntax Get help with writing PromQL, LogQL, or TraceQL queries. > @Grafana help me build a query for error rates ### Approve tool actions Some Assistant actions require your explicit approval before they run. When the Assistant needs to confirm an action, it pauses and posts an approval card in the Teams conversation. The card lists the action and the parameters it will use. - Click **Approve** to allow the action to proceed. - Click **Deny** to cancel the action. If a response includes multiple pending actions, you can approve or deny them individually or use **Approve all** or **Deny all** to decide in bulk. The Assistant resumes after you respond. If you don’t respond, the action remains pending until the conversation times out. ## Access and permissions Grafana Assistant in Microsoft Teams uses the permissions of your linked Grafana user. Requests issued by a user adhere to that user’s Grafana stack role and data source permissions. When multiple users participate in a Teams channel thread, each message is processed using the permissions of the individual user who sent it. ### Required permissions During workspace connection, your Global Administrator or Application Administrator must grant admin consent for the following Microsoft Graph API application permissions: Expand table | Permission | Purpose | |---------------------------------|-----------------------------------------------------------------------------------------------------------------------------| | `ChannelMessage.Read.All` | Read messages in Teams channels so Assistant can receive and respond to channel conversations. | | `Chat.Read.All` | Read messages in one-to-one and group chats so Assistant can receive and respond to direct and group-chat conversations. | | `User.Read.All` | Resolve the Microsoft Teams user’s Azure AD Object ID to their email address so it can be matched to their Grafana account. | | `TeamsAppInstallation.Read.All` | Read the Teams apps installed in your tenant to verify the Grafana Assistant app is present. | | `TeamSettings.Read.All` | Read team settings to support channel and workspace-level context when responding to messages. | | `User.Read` | Allow users to sign in and let Assistant read their basic profile and company information while they are signed in. | The first five permissions are application-level permissions and require admin consent. `User.Read` is a delegated permission used when a user signs in. No permissions beyond those listed above are requested. ### Bot Framework permission The Grafana Assistant bot authenticates with the Microsoft Bot Framework using its registered App Registration credentials. This acquires a service token scoped to `https://api.botframework.com/.default`, which is used exclusively to send messages back to Teams on behalf of the bot. This permission is managed by Microsoft and does not require additional admin consent beyond installing the bot app. ## Usage limits & Pricing MS Teams integration will be free to use during preview stages. Once released, any usage will be tied to the linked Grafana user. Assistant usage through Microsoft Teams is subject to Microsoft’s Bot Framework rate limits and internal Grafana Assistant rate limits.