> For the complete documentation index, see [llms.txt](https://docs.pharos.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pharos.ai/configuration-guide/integrations/slack.md).

# Slack

Configure the Slack integration in Pharos Admin for notification channels.

The Slack integration enables Pharos to send real-time notifications directly to Slack channels when issues are created or updated. Notifications appear where your team already works, with rich formatting and direct links to Pharos records.

{% hint style="info" %}
For an overview of Slack capabilities, channel strategies, and best practices, see [Slack Notifications](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/alerting/notification-channels/slack.md).
{% endhint %}

***

## Accessing Slack Settings

1. Open the **Pharos** app
2. Navigate to **Pharos Admin**
3. Select **Integrations** from the left-hand menu
4. Click **Slack**

![Slack Settings — integration disabled, toggle in off position](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-eb92c6a47ead9a9cb50c011a9f295c38bc038980%2Fslack-settings-disabled.png?alt=media)

***

## Prerequisites

Before configuring Slack, ensure you have:

| Requirement         | Details                                                                                                                                                                                                   |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Slack workspace** | Admin or appropriate permissions to add apps                                                                                                                                                              |
| **Channel access**  | Ability to create or access the channels where notifications will post                                                                                                                                    |
| **OAuth app**       | Pharos provides a pre-configured app. If your Slack workspace blocks unlisted third-party apps, see [Custom Slack App](https://docs.pharos.ai/configuration-guide/integrations/slack/slack-custom-app.md) |

***

## Authentication

Pharos connects to Slack via OAuth.

### Step 1: Initiate the Connection

1. Toggle **Enable Slack Integration** to on
2. Click **Login to Slack**
3. You'll be redirected to Slack's authorization page
4. Select the Slack workspace to connect
5. Review and approve the requested permissions
6. You'll be redirected back to Pharos with the connection established

![Slack Settings — integration enabled, showing OAuth Token field and Login to Slack button](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-edc8addb515d4ee450e596554501d409ccb1138b%2Fslack-settings-enabled.png?alt=media)

After clicking **Login to Slack**, you'll see the Slack authorization page where you select a workspace and review the permissions Pharos requests:

![Slack OAuth consent — select workspace, review permissions, and click Allow](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-b171bf29fa3455193d2cf33698d4221a96a73a28%2Fslack-oauth-consent.png?alt=media)

### Required OAuth Scopes

When configuring a custom Slack app or reviewing the Pharos app's permissions, ensure these OAuth scopes are requested:

| Scope               | Description                                            | Required |
| ------------------- | ------------------------------------------------------ | -------- |
| `chat:write`        | Post messages to channels and threads                  | Yes      |
| `chat:write.public` | Send messages to channels the app isn't a member of    | Yes      |
| `channels:read`     | List public channels for channel selection             | Yes      |
| `groups:read`       | List private channels (if posting to private channels) | Yes      |
| `users:read`        | Get user information (for @mentions and display names) | Yes      |
| `im:read`           | List direct messages                                   | Yes      |
| `im:write`          | Send direct messages                                   | Yes      |

**Minimum scope set:** `chat:write`, `chat:write.public`, `channels:read`, `groups:read`, `users:read`, `im:read`, `im:write` — this is the full scope set the Pharos app requests; there is no separate reduced scope for public-channel-only use.

{% hint style="info" %}
Pharos does not request channel or group message history, and group direct messages (multi-person DMs) aren't supported by the shipped app.
{% endhint %}

{% hint style="info" %}
If using Pharos's pre-configured Slack app, the exact scopes requested are shown during the OAuth authorization step. This table is a reference for permission auditing. If you're configuring a [Custom Slack App](https://docs.pharos.ai/configuration-guide/integrations/slack/slack-custom-app.md), use the focused scope list on that page — it matches what the Pharos-provided app requests.
{% endhint %}

{% hint style="info" %}
**Notification Sender:** The user who authenticates becomes the "sender" of all Slack notifications. Messages appear as if sent by that user. Consider using a dedicated "Pharos Bot" or service account so notifications aren't tied to a personal account.
{% endhint %}

### Step 2: Verify the Connection

* After completing the OAuth flow, the **OAuth Token** field should display a masked token value
* The toggle remains in the **on** position

***

## Channel Mapping

After authentication, notification rules specify which Slack channel to post to. You don't configure channels in the integration settings — you configure them in the **notification action** attached to each rule.

![Slack notification action — Subject, Channel, and Body fields with merge fields and Insert Field button](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-a088f03f54cae62094e9b7f26838c17135ef8165%2Fslack-notification-action.png?alt=media)

The **Channel(s)** field takes the Slack channel name (without the `#` prefix). The **Subject** and **Body** fields support merge fields to pull data from the Pharos issue.

**Create dedicated channels** for Pharos notifications. Use separate channels for sandbox vs. production:

* **Production:** `#production-errors`, `#prod-critical`
* **Sandbox:** `#sandbox-errors`, `#uat-errors`

### What Notifications Look Like in Slack

Messages appear from the Pharos app with the subject line, links back to Salesforce records, and any details included in the body template:

![Slack notification — monitoring event with direct links to the event and related log records](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-d693457055ffa6ea0c694447e9d1923c18a8082a%2Fslack-message-event.png?alt=media)

Notifications that include error details give developers enough context to begin investigating without leaving Slack:

![Slack notification — detailed error with full error message, stack trace, and Salesforce link](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-405d0a51b70bbc6190351559ed1a61780752d1b6%2Fslack-message-error.png?alt=media)

***

## Sandbox and Post-Refresh Considerations

When you refresh a sandbox from production:

1. Run the [Quick Start](https://docs.pharos.ai/configuration-guide/quick-start.md) wizard with the **Sandbox Refresh** option
2. Re-authenticate the Slack integration in the sandbox
3. Update your notification rules to use sandbox-appropriate channels (e.g., `#sandbox-errors` instead of `#production-errors`)

Notification rules are deactivated during sandbox refresh to prevent sending notifications from sandbox to production channels.

***

## Re-authenticating

If the OAuth token becomes invalid or the connection stops working:

1. Return to Integrations → Slack
2. Click **Login to Slack** to re-authenticate
3. Complete the OAuth flow again
4. Verify a new token appears in the OAuth Token field

Re-authentication may be needed if the authenticating user is deactivated or if the Slack app is uninstalled and reinstalled.

***

## Troubleshooting

| Issue                       | Cause                                          | Resolution                                                            |
| --------------------------- | ---------------------------------------------- | --------------------------------------------------------------------- |
| Notifications not appearing | Integration disconnected or rule misconfigured | Verify connection status; check notification rule filters and channel |
| "Channel not found"         | Bot not in channel or channel doesn't exist    | Invite the Slack app to the channel; verify channel name              |
| Rate limit errors           | Too many messages (e.g., log-level alerts)     | Use issue-level alerts instead of log-level; reduce alert frequency   |
| Messages from wrong user    | Personal account used for auth                 | Re-authenticate with a dedicated bot or service account               |

## Related

* [Notification Rules](https://docs.pharos.ai/configuration-guide/notifications.md) — Route issues to your Slack channels
* [Custom Slack App](https://docs.pharos.ai/configuration-guide/integrations/slack/slack-custom-app.md) — Use your own Slack app when workspace policies block unlisted apps
* [Slack Notifications](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/alerting/notification-channels/slack.md) — Channel strategies and best practices
