> 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/slack.md).
# Slack
{% hint style="info" %}
**Path:** `/settings/integrations` (find Slack under Collaboration)
{% endhint %}
#### About Slack
Slack is a team collaboration platform that brings together messaging, file sharing, and integrations in one unified workspace. Connecting Slack to Harmony transforms your channels into an intelligent IT helpdesk with autonomous ticket resolution, AI-powered responses, and seamless workflow automation.
#### What the Slack integration enables
| Capability | Description |
| -------------------- | ------------------------------------------------------------------------------------------------------- |
| Autonomous Help Desk | Transform Slack channels or DMs 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 Slack |
| Slash Commands | Use `/harmony` from any channel or DM to instantly create tickets and execute commands |
| AI Responses | Get intelligent answers from Harmony's AI trained on your knowledge base and IT procedures |
| Copilot in Threads | Access the Copilot agent inside replicated Slack threads for AI-assisted support alongside human agents |
| Native Catalog Forms | Submit Service Catalog requests using interactive, purpose-built Slack UI components |
| Channel Management | Create, archive, and invite users to Slack channels directly from agent workflows |
***
#### Prerequisites
Before connecting Slack to Harmony, ensure you have:
1. **Slack Workspace Admin access** or permissions to install applications
2. **A Harmony account** with admin access to manage integrations
{% hint style="info" %}
Standard Slack workspace members can install apps, but your organization's app approval policy may require admin approval.
{% endhint %}
***
#### Connect Slack to Harmony
**Step 1: Initiate the Connection**
1. **Navigate to Integrations**
1. Log into your Harmony dashboard
2. Click **Settings** in the sidebar
3. Click **Integrations** in the settings menu
4. Click **Slack** under the **Collaboration** section to begin the OAuth flow
2. **Authorize in Slack**
You'll be redirected to Slack's authorization page.
**Important**: Ensure you have the correct Slack workspace selected in the top-right corner before proceeding.
1. Review the requested permissions (see [Permissions](#permissions-explained) below)
2. Select a channel to connect to Harmony initially
3. Click **Allow** to authorize the connection
At this point, Slack should be successfully connected to Harmony.
**Re-authorizing an Existing Connection**
If Harmony requires updated permissions, you no longer need to uninstall and reinstall the app. Instead:
1. Navigate to **Settings → Integrations → Slack**
2. Click the **Reauthorize** button
3. Complete the OAuth flow in the popup window
You will see a success or failure notification once the process completes, so you always know whether the connection was established successfully. This avoids any disruption to your existing Slack-based support workflows.
{% hint style="info" %}
If you have an existing Slack connection and are prompted to re-authenticate, use the **Reauthorize** button rather than uninstalling the app. This applies whenever Harmony's expanded permission set needs to be applied to your workspace.
{% endhint %}
***
#### Configure Slack as Your IT Help Desk
After connecting Slack, you'll land on the Slack configuration page in Harmony where you can configure how Harmony operates in your channels.
**Configure Your Connected Channel**
Once you've connected Slack, configure how Harmony should operate in the channel:
1. **Enable the Channel**
1. Click **Settings** in the sidebar
2. Navigate to **Desks** in the settings menu
3. Select your desk and click **Notifications**
4. Click **Add destination** and select **Slack**
5. Configure the notification events and select your Slack channel
2. **Test the Integration**
1. Go to your Slack channel
2. Type a test message like "Help with password reset"
3. Harmony should respond to your request
**Connect Additional Channels**
You can connect more channels in two ways:
**Method 1: Through notification settings**
1. Navigate to **Settings → Desks → Notifications**
2. Click **Add destination** and select **Slack**
3. Choose a different channel from the dropdown
4. Configure the notification events for the new channel
**Method 2: Using @mention in Slack**
1. Go to any Slack channel where you want to add Harmony
2. Type `@Harmony` to mention the app
3. Click the **Add them** button when prompted
4. Configure the notification settings in Harmony
***
#### Notify Assigned Admins in Slack Threads
You can automatically mention an assigned admin in the Slack thread where their ticket originated, the moment the ticket is assigned to them. This works whether the ticket came from a public channel or a direct conversation with the Harmony app.
To enable this behaviour per desk:
1. Navigate to **Settings > Desks > \[Your Desk] > Notifications > Ticket Events**
2. Enable the **Notify admin on assignment** checkbox
This setting is optional and configurable independently for each desk.
***
#### Copilot Agent in Slack Threads
When a conversation is replicated to a Slack channel, Harmony's Copilot agent is available inside that thread to provide AI-powered assistance alongside your human agents. The Copilot agent is accessible to all platform roles except employee-level users, ensuring the right people have AI assistance where they need it.
***
#### Automate Slack Channel Management in Workflows
You can create, archive, and invite users to Slack channels directly from your agent workflows using three dedicated workflow blocks:
| Workflow Block | What it does |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Create a channel** | Spins up a new public or private Slack channel as part of any workflow, with your choice of name and visibility |
| **Archive a channel** | Safely decommissions a channel when it's no longer needed; archiving an already-archived channel is handled gracefully with no errors |
| **Invite users to a channel** | Adds one or more team members to an existing channel using employee records from Harmony |
{% hint style="info" %}
The Archive Slack Channel action automatically joins the channel if Harmony's bot is not already a member before archiving, so the action works regardless of current bot membership. If archiving fails for any reason, the bot leaves the channel to avoid unexpected membership state.
{% endhint %}
***
#### Service Catalog Forms in Slack
You can submit Service Catalog requests directly in Slack using native, interactive form fields. Each field renders as a purpose-built Slack UI component, making it faster and easier to fill out requests without leaving your workflow.
**Supported field types**
| Catalog field type | Slack component |
| ------------------ | ------------------------------------------- |
| Single choice | Dropdown select |
| Multiple choice | Multi-select dropdown |
| Date picker | Native Slack date picker |
| Text input | Single-line plain text input |
| Paragraph | Multiline plain text input |
| User picker | Typeahead dropdown with name and work email |
| Asset selector | Asset browser dropdown |
| File attachment | Native Slack file upload |
**User picker fields**
When a form includes a user selector, employees can search for and select colleagues by name or email using a dropdown with typeahead filtering. Each person's display name is shown alongside their work email to help disambiguate common names. Both single-user and multi-user selection are supported, matching how the field is configured in the catalog.
**File attachments**
You can attach files when submitting Service Catalog forms directly from Slack, giving you a more complete submission experience without leaving the conversation.
**Asset selector**
Users interacting with Harmony through Slack can browse and select assets from your Service Catalog without leaving the conversation. This brings Slack interactions in line with what is already available on other surfaces.
{% hint style="info" %}
The asset selector requires the updated Slack app version and will be fully available once the Slack app submission is approved.
{% endhint %}
**Form reliability and constraints**
Harmony enforces Slack's field and modal constraints automatically, so forms render consistently and are less likely to fail silently. The following limits are applied:
| Element | Limit |
| ------------------------------ | ---------------- |
| Modal titles | 24 characters |
| Submit and close button labels | 24 characters |
| Field labels | 2,000 characters |
| Field hints and placeholders | 150 characters |
***
#### Approval Requests in Slack
When a V3 approval card appears in Slack and you click **Deny**, a modal opens where you can enter a reason before confirming the denial. Previously, clicking Deny submitted the denial immediately without prompting for context.
* The reason modal appears for all V3 Slack approval cards
* Submitting the modal sends the denial with your reason attached
* The reason is recorded in the workflow output and visible in the resolved reason field
* Cancelling the modal leaves the approval in a pending state - no accidental denials
***
#### Human Agent Identity in Slack Notifications
When a support agent responds to a ticket from within Harmony, the Slack notification appears under that agent's name and profile photo - making it immediately clear who sent the message, just like a native Slack message.
* The agent's profile photo is pulled from their Slack account
* If no Slack photo is available, Harmony falls back to their Harmony profile photo
* Gravatars are intentionally deprioritized in the fallback order to ensure accurate, personal identity is shown
***
#### Live Agent Progress Indicators
While Harmony's Service Desk Agent is working on a request, a live status indicator appears beneath the bot as soon as your message is received. The indicator updates in real time to reflect what the agent is doing at each step:
* An immediate acknowledgement appears the moment your message is received
* The status updates dynamically, for example: "Searching knowledge base for: legal documentation"
* The indicator clears automatically once the agent's final response is ready
***
#### User Mentions in Slack
The Service Desk Agent can mention users directly in Slack using @. The agent correctly resolves display names so that mentions are properly recognised by Slack, keeping the right people in the loop.
{% hint style="info" %}
Mentions are supported in channel conversations handled by the Service Desk Agent. In Slack-based ticket threads, if you ask Harmony to tag or notify someone, it will clearly explain that mentions are not supported in that context and that the request will be added as a ticket comment instead.
{% endhint %}
***
#### Permissions Explained
Harmony requests the following Slack permissions:
| Permission | Why we need it |
| ------------------ | ----------------------------------------------------------- |
| `chat:write` | To post messages and responses in channels and DMs |
| `channels:read` | To list and access channels where Harmony is added |
| `channels:history` | To read message history for context and ticket creation |
| `users:read` | To identify users and personalize responses |
| `commands` | To enable `/harmony` slash commands |
| `im:write` | To send direct messages to users |
| `im:history` | To read DM history for ticket context |
| `reactions:write` | To add reaction emojis for ticket status (✅ resolved, etc.) |
| `files:read` | To access attachments in ticket requests |
{% hint style="info" %}
Harmony's Slack integration now uses an expanded set of approved Slack marketplace scopes to support all current and upcoming Slack-powered features. If you have an existing connection, you may be prompted to re-authenticate. Use the **Reauthorize** button in **Settings → Integrations → Slack** to apply updated permissions without reinstalling the app.
{% endhint %}
***
#### Troubleshooting
Harmony doesn't respond to messages
**Possible causes:**
* You need to @mention Harmony in the channel
* Harmony lacks permissions in the channel
**Solutions:**
1. Ensure you're @mentioning Harmony in the channel
2. Re-invite Harmony to the channel: Type `@Harmony` and click **Add them**
Tickets aren't being created
**Possible causes:**
* Messages don't meet ticket creation criteria
* Integration connection expired
**Solutions:**
1. Try explicitly creating a ticket with `/harmony [your request]`
2. Reconnect the integration: **Settings → Integrations → Slack → Reconnect**
Slack permissions need to be updated
If you see a message indicating that Harmony requires new or updated permissions:
1. Navigate to **Settings → Integrations → Slack**
2. Click **Reauthorize**
3. Complete the OAuth flow in the popup window
You do not need to uninstall the Harmony Slack app. Uninstalling can disrupt your existing support workflows.
***
Need help? Contact [**support@harmony.io**](mailto:support@harmony.io) for assistance with your Slack integration.
***
#### Data & Privacy
Key privacy principles
For information about how Harmony handles your data, see our [Privacy Policy](https://harmony.io/privacy).
* Harmony only accesses channels where explicitly invited
* All data transmission is encrypted using industry-standard TLS
* Message content is processed to provide AI responses and ticket management
* Integration can be revoked at any time from Slack workspace settings or Harmony
---
# 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/slack.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.