# Self-managed Slack

This guide explains how to configure the Slack integration for a [Cortex self-managed](/self-managed.md) account. It requires a Slack app, which needs to be configured in your own Slack workspace when using Cortex Self-Managed.

If you are looking for instructions on configuring a Slack integration for your Cortex cloud workspace, please see [Integrations > Slack](/ingesting-data-into-cortex/integrations/slack.md).

## Setup instructions[​](https://docs.cortex.io/docs/self-managed/guides/slack#setup-instructions) <a href="#setup-instructions" id="setup-instructions"></a>

### Create the app[​](https://docs.cortex.io/docs/self-managed/guides/slack#create-the-app) <a href="#create-the-app" id="create-the-app"></a>

Use the following manifest to create a new Slack app in your workspace. Make sure to replace the URLs found in `[]` with the [URLs you set up](/self-managed.md) for your self-managed Cortex instance.

```
_metadata:
  major_version: 1
  minor_version: 1
display_information:
  name: Cortex
  description: Manage your microservices
  background_color: "#d21285"
features:
  app_home:
    home_tab_enabled: false
    messages_tab_enabled: true
    messages_tab_read_only_enabled: false
  bot_user:
    display_name: cortex
    always_online: true
  slash_commands:
    - command: /cortex
      url: https://[Cortex Backend URL]/api/internal/v1/slack/slash-command
      description: Cortex slash commands
      usage_hint: runbooks, docs, on-call, logs
      should_escape: false
oauth_config:
  redirect_urls:
    - https://[Cortex Frontend URL]/slack/redirect
  scopes:
    bot:
      - app_mentions:read
      - channels:join
      - channels:read
      - chat:write
      - chat:write.customize
      - chat:write.public
      - commands
      - im:history
      - reactions:read
      - users:read
      - users:read.email
settings:
  org_deploy_enabled: false
  socket_mode_enabled: false
```

{% hint style="warning" %}
If your Cortex Self-Managed installation is not available from the public internet, the Slack Slash commands integration will not work, as Slack needs to be able to hit the Cortex API when a command is run.
{% endhint %}

### Connect your Cortex instance[​](https://docs.cortex.io/docs/self-managed/guides/slack#connect-your-cortex-instance) <a href="#connect-your-cortex-instance" id="connect-your-cortex-instance"></a>

You'll need to configure your on-prem deployment to be able to talk your Slack App.

1. Create a k8s secret and add the secret in your `values.yaml` file for the Helm chart. You may already have a secret set up if you had configured a persistent store previously, so be sure to verify in your Helm chart.
2. Add the follow key/values to the secret. Note that Kubernetes will base64-encode these values:
   * `SLACK_CLIENT_ID`
   * `SLACK_CLIENT_SECRET`
   * `SLACK_SIGNING_SECRET`
   * `SLACK_SLASH_COMMAND_TOKEN` (“Verification Token” seen in the Slack App page)
3. Restart your Cortex backend deployment.

### Install the app[​](https://docs.cortex.io/docs/self-managed/guides/slack#install-the-app) <a href="#install-the-app" id="install-the-app"></a>

Once your backend has restarted, you're ready to install the app.

Note: Make sure you're logged in on your Cortex application before triggering this install.

Navigate to `https://slack.com/oauth/v2/authorize?client_id=[CLIENT ID]&scope=chat%3Awrite%2Ccommands%2Cchannels%3Ajoin%2Cchannels%3Aread%2Cusers%3Aread%2Cusers%3Aread.email&redirect_uri=[REDIRECT URL set in the manifest, URL ENCODED]`. It may spin forever on this page, if you refresh you should see that it’s installed.

You'll know that it's set up correctly if there's a Team ID number visible in Settings → Slack in your Cortex app.

## FAQ and Troubleshooting

**What if I use a different secret manager?**

If you use something other than the K8s secret manager, you don't need to base64-encode your credentials.

**Where do I set my credentials?**

You only need to set credentials in the backend.

**Why are my slash commands failing?**

If the backend is not publicly reachable (e.g., it's behind a firewall or on a private network), the commands will fail. Make sure the backend URL specified in your slash command configuration is publicly accessible. Slack must be able to reach the Cortex API at the `/api/internal/v1/slack/slash-command` endpoint in order to process slash commands.


---

# Agent Instructions: 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:

```
GET https://docs.cortex.io/self-managed/features/integrations/slack.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.