> For the complete documentation index, see [llms.txt](https://docs.harmony.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.harmony.io/integrations/collaboration/teams.md). # Microsoft Teams Microsoft Teams is a collaboration platform that combines workplace chat, video meetings, file storage, and application integration. Connecting Teams to Harmony transforms your channels into an intelligent IT helpdesk with autonomous ticket resolution, AI-powered responses, and seamless workflow automation. Harmony is available inside Microsoft Teams as a fully embedded app, so your support agents and end users can access Harmony's complete interface - including the AI agent, ticket management, and approval workflows - without leaving Teams. #### What the Microsoft Teams integration enables | Capability | Description | | ----------------------------- | ------------------------------------------------------------------------------------------------ | | Autonomous Help Desk | Transform Teams channels into an AI-powered help desk with autonomous ticket resolution | | Team Inbox | Centralize all IT tickets in a dedicated channel for support agents to triage and collaborate | | Automation workflows | Trigger workflows, receive notifications, and execute IT actions directly from Teams | | Adaptive Cards | Interactive rich cards for ticket updates, approvals, and status changes | | Message Actions | Convert any message into a ticket using the Teams message context menu | | AI Responses | Get intelligent answers from Harmony's AI trained on your knowledge base and IT procedures | | Embedded App | Access Harmony's full interface inside Teams via native iframe with single sign-on | | AI Agent in Teams | Interact with Harmony's AI agent directly inside Teams - no context switching required | | Bell Notifications | Receive activity feed notifications that deep-link directly to the relevant conversation or task | | Create Teams from Workflows | Provision new Microsoft Teams teams on demand using the Create Team workflow block | | Submit Tickets via `/Harmony` | Create Service Desk tickets from any Teams channel without leaving Teams | | User Mentions | @mention users in Teams conversations handled by Harmony | *** #### Prerequisites Before connecting Microsoft Teams to Harmony, ensure you have: 1. **Microsoft 365 Admin access** or permissions to install Teams applications 2. **Microsoft Entra ID connected** to Harmony as your identity provider 3. **A Harmony account** with admin access to manage integrations {% hint style="warning" %} You must connect Microsoft Entra ID to Harmony before setting up the Teams integration. Entra ID provides user authentication and identity management for Teams. {% endhint %} *** #### Step 1: Connect Microsoft Entra ID 1. **Navigate to Integrations** 1. Log into your Harmony dashboard 2. Navigate to **Settings → Integrations** 3. Find **Microsoft Entra ID** under **Identity & Access Management** 4. Click **Connect** ![Navigate to Microsoft Entra ID integration in Harmony dashboard](/files/VYg3IjiysNoYr3fASSLx) 2. **Authorize Entra ID** 1. You'll be redirected to Microsoft to authorize the connection 2. Sign in with your Microsoft 365 admin account 3. Review the requested permissions 4. Click **Accept** to authorize 5. You'll be redirected back to Harmony ![Microsoft Entra ID authorization dialog](/files/Hv0qYiXkrDKwSOWNmKWw) 3. **Verify Connection** Confirm that Microsoft Entra ID shows **Connected** status before proceeding to Teams setup. *** #### Step 2: Connect Microsoft Teams 1. **Navigate to Teams Integration** 1. In your Harmony dashboard, navigate to **Settings → Integrations** 2. Find **Microsoft Teams** under **Collaboration** 3. Click **Connect** ![Navigate to Microsoft Teams integration in Harmony dashboard](/files/Vy3YgX2xxXYQjybFCk1O) 2. **Authorize in Microsoft** 1. You'll be redirected to Microsoft to authorize Teams integration 2. Review the requested permissions (see [Permissions](#permissions-explained) below) 3. Click **Accept** to authorize the connection 4. You'll be redirected back to Harmony ![Microsoft Teams authorization dialog with permissions](/files/Hv0qYiXkrDKwSOWNmKWw) *** #### Step 3: Upload Harmony App to Teams The Harmony app must be uploaded to your Microsoft Teams environment by a Teams administrator. 1. **Upload to Teams Admin Center** 1. Navigate to the [Microsoft Teams admin center](https://admin.teams.microsoft.com/policies/manage-apps) 2. Click the **Actions** dropdown button 3. Select **+ Upload new app** 4. Upload the Harmony Teams app package when prompted 5. Follow the on-screen instructions and click **Upload** to complete the installation ![Upload Custom App Dialog](/files/ZvOAnaopIU2yuGhETCFz)

The app will be available to users within a few minutes, but organization-wide deployment may take several hours.

*** #### Add Harmony to Channels After uploading the Harmony app, you can add Harmony to your Teams channels: 1. **Add Harmony Bot to Channel** 1. In Harmony dashboard, click **Settings** in the sidebar 2. Navigate to **Desks** and select your desk 3. Click on **Notifications** 4. Click **+ Add destination** under **Ticket notifications** 5. Select **Microsoft Teams** from the dropdown 6. Choose your Teams channel and configure the ticket events you want to receive notifications for 7. Click **Save** ![Configure Teams channel notifications in Harmony dashboard](/files/cMl9lG2tw5Ld619hY1iY) When selecting a channel, Harmony shows all available channels across your connected Teams workspaces, so you can route notifications to exactly the right place. *** #### Harmony Inside Microsoft Teams Harmony is available as a fully embedded app within Microsoft Teams, giving your team access to the complete Harmony interface without leaving Teams. **Single sign-on and identity** Harmony authenticates automatically using your Microsoft Azure AD (AAD) identity. No separate login is required. Your Teams user profile is used to identify you within Harmony, linking your Teams account to your Harmony workspace seamlessly. The authentication flow uses a dedicated token exchange mechanism that validates your Microsoft Azure AD credentials and converts them into standard Harmony session tokens. Sessions are refreshed automatically before they expire, and early requests are blocked until authentication is fully established - reducing interruptions caused by token timeouts or session errors. This makes sign-in stable and resilient with no action needed on your end. **Direct message experience** Users who reach out to Harmony via direct message in Teams are automatically directed to the Agent tab, landing in the right place immediately without extra navigation. Support conversations via Teams DMs are fully supported, with reliable message parsing and proper handling of bot DM interactions. **Submitting tickets with `/Harmony`** You can create Service Desk tickets without leaving Microsoft Teams by typing `/Harmony` in any channel. This opens a form where you can fill in the details of your request and submit it directly to your support team. Harmony automatically surfaces available channels across all your connected Teams workspaces, so routing your request to the right place is simple. *** #### AI Agent in Microsoft Teams Harmony's AI agent is available directly inside Microsoft Teams via a native Copilot custom engine agent. Employees can start and continue support conversations with the Harmony AI agent without leaving Teams. Key capabilities of the Teams AI agent experience: * **Conversational AI support in Teams**: Employees interact with the Harmony AI agent directly from within Teams, with full conversation history maintained across sessions so the agent has context for ongoing interactions. * **Automatic employee identification**: The agent identifies the Teams user automatically, so no separate account linking is required. * **Threaded conversations**: Each support request is handled in its own thread, keeping discussions organized and easy to follow. * **Real-time status updates**: The agent displays a processing indicator while preparing a response, then replaces it with the final answer once ready. * **Message filtering**: Incoming messages are filtered to ensure only relevant requests are routed to the agent. * **Copilot activity notifications**: You receive notifications directly in Teams threads when Harmony's AI Copilot is active in a conversation. Notifications are deduplicated so you won't see repeated messages for the same activity, and ownership validation ensures notifications reach only the correct participants. *** #### Bell Notifications with Deep Links You can receive activity notifications directly in the Microsoft Teams activity feed (bell icon) that deep-link to the relevant conversation or task in the Harmony portal. When a key ticket event occurs, a bell notification appears in Teams so you never miss an important update. Notifications are sent for the following events: * **New task (approval request)** - notifies you when an approval task is assigned to you, deep-linking to My Tasks * **Agent response** - notifies you when an agent replies to a ticket, deep-linking directly to the conversation thread * **Ticket status change** - notifies you of updates to ticket status, keeping you informed as requests progress *** #### Create Microsoft Teams Teams from Workflows You can provision new Microsoft Teams teams on demand directly from a Harmony workflow using the **Create Team** block. This lets you fully automate team provisioning as part of your support or onboarding flows with no manual steps required in the Teams admin console. * **Create Team block**: Add a Create Team step to any workflow to provision a new Microsoft Teams team on demand. * **Template variable support**: Use dynamic template variables in channel and team name settings, so team names can be personalised or derived from conversation data at runtime. * **Duplicate name handling**: If a team with the same name already exists, Harmony handles the conflict gracefully so your workflow continues without errors. You can also configure a custom base URL for the Agent Workflows Orchestrator within your Teams integration. This lets you control where agent workflow requests are routed - useful for self-hosted or region-specific orchestration setups. *** #### User Mentions in Teams You can mention users directly within Microsoft Teams conversations handled by Harmony. When a user is mentioned using the standard @mention format in Teams, Harmony correctly recognises and processes the mention, ensuring conversations and handoffs work as expected. This brings Teams in line with other supported channels and makes collaboration within Teams-based support workflows more seamless. *** #### Notifications and Ticket Updates Harmony surfaces ticket activity and support events directly in your Teams channels, keeping your team informed without leaving Teams: * **Private notifications** are delivered to the right individuals or channels * **Ticket updates** including status changes and new activity are surfaced in real time * **Replies are threaded** directly within Teams channels for clean, contextual conversations * **Agent workflow events** appear alongside regular ticket activity, so automated actions and AI-driven updates are visible in context * **SLA alerts** are delivered straight into the chosen channel, ensuring the right people are notified at the right time * **Teams messages and replies** are properly linked to their corresponding notifications, so agents see a complete and accurate conversation thread * **Agents are correctly identified** in Teams conversations, making it clear which messages were sent by a support agent versus an end user * **Duplicate and spam notifications** triggered by Teams ticket updates are suppressed, so agents are not flooded with redundant alerts when conversations are active in Teams *** #### Permissions Explained Harmony requests the following Microsoft Teams permissions: | Permission | Why we need it | | ------------------------- | ----------------------------------------------------------------------------------------------------------------- | | `ChannelMessage.Read.All` | To read messages in channels where Harmony is added | | `ChannelMessage.Send` | To post responses and ticket updates in channels | | `Chat.Read` | To read direct messages sent to Harmony bot | | `Chat.ReadWrite` | To send responses in direct message conversations | | `User.Read.All` | To identify users and personalize responses | | `TeamSettings.Read.All` | To read team and channel information | | `Files.Read.All` | To access file attachments in ticket requests | | `TeamsActivity.Send` | To send activity feed notifications (bell icon) to users for ticket updates, approvals, and time-sensitive alerts | *** #### Troubleshooting
Harmony app not appearing in Teams **Possible causes:** * App not uploaded to Teams admin center * Organization's app policies block custom apps * App hasn't propagated to all users yet **Solutions:** 1. Verify app was uploaded successfully in Teams admin center 2. Check **Teams apps → Permission policies** allow custom apps 3. Wait 15-30 minutes for app to propagate 4. Have users refresh Teams (Ctrl+R or Cmd+R)
Bot doesn't respond to messages **Possible causes:** * Teams integration not connected in Harmony * Not @mentioning the bot in channels **Solutions:** 1. Verify **Settings → Integrations → Microsoft Teams** shows **Connected** 2. Ensure you're @mentioning **@Harmony** in channel messages
Cannot create tickets in DMs **Possible causes:** * Using @mention instead of commands in DMs * Bot not added to personal apps **Solutions:** 1. In DMs, use `/harmony [request]` instead of @mentions 2. Use message actions: right-click message → **Create Harmony Ticket** 3. Have users add Harmony bot from Teams app store
Adaptive cards not displaying **Possible causes:** * Teams client version too old * Card schema compatibility issue **Solutions:** 1. Update Microsoft Teams to the latest version 2. Try accessing Teams via web browser 3. Contact Harmony support with Teams version info
Authentication issues or sign-in errors **Possible causes:** * Session token expired before refresh could complete * Azure AD credentials not resolving to a Harmony account **Solutions:** 1. Reload the Harmony app inside Teams (Ctrl+R or Cmd+R) 2. Ensure your Microsoft Azure AD account is linked to your Harmony workspace 3. Contact Harmony support if sign-in errors persist - include your Teams version and the error message you see
*** #### Best Practices
Start with a Pilot Channel Before rolling out organization-wide: * Choose one IT support channel for testing * Gather feedback from early users * Roll out to additional channels based on success
Educate End Users Help users understand how to interact with Harmony: * Create a quick reference guide * Explain the difference between channels (@ mention) and DMs (commands) * Share example questions and requests * Highlight the Create Ticket message action and the `/Harmony` command for quick ticket submission * Set expectations for response times
Monitor and Optimize Regularly review integration performance: * Check ticket creation patterns * Monitor resolution rates * Identify common user questions * Collect user feedback on AI responses
*** #### Getting Help Need assistance? Here's how to get support: * **In-app Help**: Use the help button on the sidebar to reach us * **Support Team**: Contact with your workspace details *** #### Data & Privacy
Key privacy principles For information about how Harmony handles your data, see our [Privacy Policy](https://harmony.io/privacy). * **Channel support**: Harmony is only supported in public channels * **Encryption**: All data transmission is encrypted using industry-standard protocols * **Revocation**: Integration can be revoked at any time from your Microsoft 365 admin center or Harmony settings * **Compliance**: Harmony complies with Microsoft's security and compliance standards
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.harmony.io/integrations/collaboration/teams.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.