> 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**: a Global Administrator or Privileged Role Administrator to accept the permissions in Steps 1 and 2, and a Global Administrator or Teams Administrator to upload the app in Step 3 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 Provider** and click its card 4. Enter an **Instance name** (it is prefilled; you can keep it) and click **Connect** ![Navigate to Microsoft Entra ID integration in Harmony dashboard](https://1160081901-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fow5hkvoGYRymkbqRTEvW%2Fuploads%2Fgit-blob-d804b249411c1b0df2f015b55d22680db520b668%2Fteams-entra-id-integrations.png?alt=media) 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 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** and click its card 3. Enter an **Instance name** (it is prefilled; you can keep it) and click **Connect** ![Navigate to Microsoft Teams integration in Harmony dashboard](https://1160081901-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fow5hkvoGYRymkbqRTEvW%2Fuploads%2Fgit-blob-4402dc792a3834fabc67c5c5d89ad6a600f61606%2Fteams-integration-navigate.png?alt=media) 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](https://1160081901-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fow5hkvoGYRymkbqRTEvW%2Fuploads%2Fgit-blob-2738fed574bf60533568dc80c1393031524a7aff%2Fteams-entra-id-authorization.png?alt=media) *** #### 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. In Harmony, open **Settings → Integrations**, click the **Microsoft Teams** card and click **Download App** to download the Harmony Teams app package 2. Navigate to the [Microsoft Teams admin center](https://admin.teams.microsoft.com/policies/manage-apps) 3. Click the **Actions** dropdown button 4. Select **+ Upload new app** 5. Upload the Harmony Teams app package when prompted 6. Follow the on-screen instructions and click **Upload** to complete the installation ![Upload Custom App Dialog](https://1160081901-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fow5hkvoGYRymkbqRTEvW%2Fuploads%2Fgit-blob-7a072584bfaf06a393e79d034ff8e9941624de9b%2Fupload-dialog.png?alt=media)

The app becomes available to users in your organization after a few 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. Select the team and channel, then choose the ticket events you want to receive notifications for. Changes are saved automatically. ![Configure Teams channel notifications in Harmony dashboard](https://1160081901-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fow5hkvoGYRymkbqRTEvW%2Fuploads%2Fgit-blob-658c10708790b67524adac7dfe174dfdc78f21a1%2Fteams-add-channel.png?alt=media) 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 Entra ID 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 Entra ID 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. * **Genie activity notifications**: You receive notifications directly in Teams threads when Harmony Genie 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. *** #### 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 | | `Chat.ReadWrite.All` | To read direct message history between users and the Harmony bot | | `Chat.Create` | To create chats with users | | `User.Read.All` | To identify users and personalize responses | | `User.Read` | To sign in and read the profile of the admin who connects | | `Group.Read.All` | To list the teams in your organization | | `Team.ReadBasic.All` | To read team names and descriptions | | `Team.Create` | To create teams from the **Create Team** workflow block | | `TeamMember.Read.All` | To read the members of teams | | `TeamMember.ReadWrite.All` | To add people to teams as members or owners, for example the additional owner of a team created by the **Create Team** block | | `Channel.ReadBasic.All` | To list team channels so you can pick notification destinations | | `Channel.Create` | To create channels from Harmony | | `AppCatalog.Read.All` | To find the Harmony app in your organization's app catalog | | `TeamsAppInstallation.ReadWriteSelfForTeam.All` | To add the Harmony app to the teams it sends channel notifications to | | `TeamsAppInstallation.ReadWriteSelfForUser.All` | To add the Harmony app for users so it can message them directly | When the Harmony app is installed in Teams, it also receives two resource-specific permissions from its app package: `TeamsActivity.Send.User`, to send activity feed notifications (bell icon) to users for ticket updates, approvals, and time-sensitive alerts, and `ChannelMessage.Read.Group`, to receive the messages posted in the channels of teams where Harmony is added. *** #### 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 that **Org-wide app settings** (under **Actions** on **Teams apps → Manage apps**) and **Teams apps → Permission policies** allow custom apps 3. Wait a few hours for the 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 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 * Microsoft Entra ID credentials not resolving to a Harmony account **Solutions:** 1. Reload the Harmony app inside Teams (Ctrl+R or Cmd+R) 2. Ensure your Microsoft Entra ID 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 the Microsoft Entra admin center (Enterprise applications) 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` 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 what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.