> 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/slack-custom-app.md).

# Custom Slack App

Create and connect a custom Slack application for Pharos when your workspace prohibits non-listed third-party apps.

Some Slack workspace admins disallow installation of third-party apps that aren't in the official Slack marketplace. Because the Pharos Slack app is currently unlisted, those workspaces cannot connect to it directly. The supported workaround is to **create a custom Slack app inside your own workspace** and configure Pharos to authenticate against it instead of the Pharos-provided app.

{% hint style="info" %}
For the standard Slack integration setup (using the Pharos-provided app), see [Slack](https://docs.pharos.ai/configuration-guide/integrations/slack.md). Use this page only when the standard flow is blocked by your Slack admin's policies.
{% endhint %}

***

## Why Use a Custom App?

The most common reason is that your Slack workspace admin restricts apps to those listed in the Slack marketplace for security and compliance. The Pharos Slack app is functional and lightweight (it sends messages and reads channel lists — no bot interpretation, no custom forms), but it is not yet listed.

If that policy applies to your workspace, you have two options:

| Option                           | Effort | When to Use                                                                                                                    |
| -------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------ |
| **Temporary policy lift**        | Low    | Smaller orgs where the admin can briefly disable the non-listed-app restriction during the OAuth connection, then re-enable it |
| **Custom Slack app** (this page) | Medium | Larger orgs where the policy cannot be lifted, even temporarily                                                                |

***

## Will the Custom App Be Visible to Other Users?

No. A custom Slack app stays private to your workspace by default. Listing the app on the public Slack marketplace is a separate process that is **not required** for Pharos to function. The app you create here only ever serves your workspace.

***

## Prerequisites

| Requirement                    | Details                                                                                                                                                               |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Slack workspace admin**      | Permission to create and install apps in the workspace                                                                                                                |
| **Pharos Admin access**        | System Administrator or equivalent in Salesforce                                                                                                                      |
| **Pharos integration enabled** | The standard [Slack integration](https://docs.pharos.ai/configuration-guide/integrations/slack.md) toggle must be on so Pharos has somewhere to store the credentials |

***

## Step 1: Create the Custom App in Slack

{% stepper %}
{% step %}

### Open the Slack App Directory

From your Slack workspace, open **Workspace Settings** → **Configure apps** to land on the App Directory for your workspace.
{% endstep %}

{% step %}

### Create a new app

In the App Directory, choose to **Create New App** → **From scratch**. Give the app a name (e.g., `Pharos`) and select your workspace as the development workspace.
{% endstep %}

{% step %}

### Add OAuth scopes

Open the new app's settings and navigate to **OAuth & Permissions**. Under **Bot Token Scopes**, add the scopes from the [OAuth Scopes List](#oauth-scopes-list) below.
{% endstep %}

{% step %}

### Install the app to your workspace

Still on **OAuth & Permissions**, click **Install to Workspace**. Approve the OAuth prompt to install the app into your own workspace. After approval, Slack returns a **Bot User OAuth Token** — keep this page open, you'll also need the **Client ID** and **Client Secret** in the next step.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
Your Slack admin can perform these steps on your behalf. The relevant Slack documentation is [Creating an app](https://api.slack.com/start/quickstart) — share that link if needed.
{% endhint %}

***

## OAuth Scopes List

Add the following Bot Token Scopes when configuring the app's **OAuth & Permissions** in Slack:

| OAuth Scope         | Description                                                             |
| ------------------- | ----------------------------------------------------------------------- |
| `channels:read`     | View basic information about public channels in the workspace           |
| `chat:write`        | Send messages as the Pharos app                                         |
| `chat:write.public` | Send messages to channels the app isn't a member of                     |
| `groups:read`       | View basic information about private channels the app has been added to |
| `im:read`           | View basic information about direct messages the app has been added to  |
| `im:write`          | Start direct messages with people                                       |
| `users:read`        | View people in the workspace                                            |

{% hint style="info" %}
These scopes match the permissions the Pharos-provided Slack app requests. They give Pharos exactly what it needs to deliver notifications — no more, no less.
{% endhint %}

***

## Step 2: Configure Pharos to Use the Custom App

Once the custom app is installed in your workspace, give Pharos the credentials so it can authenticate against your app instead of the Pharos-provided one. This is a two-part action: store the **Client ID** and **Client Secret** in a Pharos custom setting, then run the OAuth login from Pharos Admin.

{% stepper %}
{% step %}

### Locate the Client ID and Client Secret

In your Slack app's settings, open **Basic Information** → **App Credentials**. Copy the **Client ID** and **Client Secret** — you'll paste both into Pharos.
{% endstep %}

{% step %}

### Populate the Client ID and Secret in Pharos

In Salesforce Setup, navigate to **Custom Settings** → **Pharos Settings** (managed package custom setting). Edit the org-level record and populate the **Slack App Client Id** and **Slack App Client Secret** fields with the values from your custom app, then save.

{% hint style="info" %}
Until both values are saved here, the **Login to Slack** flow in Pharos Admin will use the Pharos-provided app. Populating these fields tells Pharos to use **your** custom app for the OAuth handshake.
{% endhint %}
{% endstep %}

{% step %}

### Authenticate from Pharos Admin

Navigate to **Pharos Admin** → **Integrations** → **Slack**. With the **Enable Slack Integration** toggle on, click **Login to Slack**. The OAuth flow now runs against your custom app — approve the consent screen, and Pharos receives a token from your workspace's app.

After completion, the **OAuth Token** field in Pharos shows a masked token, confirming the connection is established via your custom app.
{% endstep %}
{% endstepper %}

***

## Verifying the Connection

The setup is complete when:

* The Pharos Settings custom setting has **Slack App Client Id** and **Slack App Client Secret** populated
* The Pharos Slack integration page shows a masked OAuth token
* A test [notification rule](https://docs.pharos.ai/configuration-guide/notifications.md) successfully posts to a channel where your custom app has been invited

For private channels, remember to invite the custom app using `/invite @YourAppName` — the same constraint applies as with the Pharos-provided app.

***

## Re-authenticating

If the OAuth token becomes invalid or your Slack admin rotates the app's credentials:

1. Generate new credentials in your custom app's **Basic Information** page if they were rotated
2. Update **Slack App Client Id** / **Slack App Client Secret** in the Pharos Settings custom setting
3. In **Pharos Admin** → **Integrations** → **Slack**, click **Reset**, then **Login to Slack** to re-authenticate

***

## Troubleshooting

| Issue                                          | Cause                                                                | Resolution                                                                                                                                           |
| ---------------------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| OAuth flow still shows the Pharos-provided app | Slack App Client Id / Secret not saved on Pharos Settings            | Populate both fields and save before clicking **Login to Slack**                                                                                     |
| "Invalid client\_id" during consent            | Client ID copied incorrectly or app deleted in Slack                 | Verify the Client ID in your Slack app's **Basic Information** matches the **Slack App Client Id** value in the Pharos Settings custom setting       |
| Notifications not posting to channel           | App not invited to the channel                                       | In Slack, run `/invite @YourAppName` in the target channel                                                                                           |
| Cannot find the channel in the dropdown        | Workspace has many channels and Slack API throttles the channel list | Use the **channel ID** instead — see [Slack — Channel Selection](https://docs.pharos.ai/configuration-guide/integrations/slack.md#channel-selection) |
| Admin policy still blocks installation         | Workspace prohibits *all* custom apps, not just unlisted ones        | Escalate to the Slack admin; this scenario requires a policy change                                                                                  |

***

## Related

* [Slack](https://docs.pharos.ai/configuration-guide/integrations/slack.md) — Standard Slack integration with the Pharos-provided app
* [Notifications](https://docs.pharos.ai/configuration-guide/notifications.md) — Create rules that post to your Slack channels
* [Slack channel capabilities](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/alerting/notification-channels/slack.md) — How Pharos uses Slack at the platform level
* [Slack: Creating an app](https://api.slack.com/start/quickstart) — Slack's documentation for app creation
* [Slack: OAuth scopes](https://api.slack.com/scopes) — Full reference of available Slack OAuth scopes
