> For the complete documentation index, see [llms.txt](https://docs.cortex.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cortex.io/ingesting-data-into-cortex/integrations/slack/using-the-integration-for-slack-ai-assistant.md).

# Using the integration for Slack

{% hint style="info" %}
Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.
{% endhint %}

This article explains how to use the integration for Slack. For configuration instructions, see [Configuring the integration for Slack](/ingesting-data-into-cortex/integrations/slack.md).

{% hint style="info" %}
Cortex conducts a background sync of Slack identities every day at 10 a.m. UTC.
{% endhint %}

## Interacting with Cortex in Slack

{% hint style="info" %}
Interacting with Cortex in Slack requires the latest version of the [Cortex Slack app](/ingesting-data-into-cortex/integrations/slack.md#configuring-slack). If you installed the app before February 2025, you'll need to update it before you can chat with Cortex. Slack administrator permissions are required to perform the update.

To install, go to [Slack settings](https://app.getcortexapp.com/admin/integrations/slack) in Cortex. Delete the existing configuration and reinstall following the prompts.
{% endhint %}

You can interact with Cortex in Slack via the AI Assistant in the following ways:

* **Natural-language chat** - Mention `@Cortex` and ask a question in plain language (e.g. ***Which services does my team own?***). Best for open-ended or analytical questions, with context kept across a thread for follow-ups. Chat is read-only: it can query Cortex but can't make changes or write data.
  * **How it works** - When you mention `@Cortex` in a Slack channel or direct message, Cortex:
    1. Interprets your natural language query
    2. Determines which Cortex API endpoints to call
    3. Retrieves the relevant data from your Cortex workspace
    4. Returns a formatted response in Slack
* **Slash commands** - Use structured /cortex commands (e.g. `/cortex oncall <tag>`) for fast, specific lookups. See the [command list](#threading-and-conversation-context) below.
* **Notifications** - The same app delivers Scorecard, Initiative, and weekly-summary notifications to users and channels.

### Threading and conversation context

Threaded conversations let you ask follow-up questions that build on context from earlier in the same thread. How it works:

* **Start a conversation** - Mention `@Cortex` in any Slack channel or direct message with your initial question. Cortex responds in a thread.
* **Ask follow-ups in the thread** - Reply in the same thread with additional questions. Cortex retains context from the conversation, so you can drill down without repeating information.
* **Each thread is a separate conversation** - Context is scoped to the thread. Starting a new top-level message begins a fresh conversation with no prior context.

<table><thead><tr><th width="263.47265625">Command</th><th>Result</th></tr></thead><tbody><tr><td><code>/cortex dependencies &#x3C;tag></code></td><td>List all incoming and outgoing first-level dependencies</td></tr><tr><td><code>/cortex deploys &#x3C;tag></code></td><td>List recent deploys</td></tr><tr><td><code>/cortex docs &#x3C;tag></code></td><td>List all <a href="/pages/5cEJd1jQZq1Shqjz7YAg">documentation links</a></td></tr><tr><td><code>/cortex domain &#x3C;tag></code></td><td>List domain information, such as owners, on-call, links, and timeline events</td></tr><tr><td><code>/cortex entity &#x3C;tag></code></td><td>List information for any entity, combining the behavior of <code>service</code>, <code>team</code>, <code>domain</code> and <code>resource</code></td></tr><tr><td><code>/cortex help &#x3C;tag></code></td><td>Display the full list of commands</td></tr><tr><td><code>/cortex links &#x3C;tag></code></td><td>List all <a href="/pages/5cEJd1jQZq1Shqjz7YAg">links</a></td></tr><tr><td><code>/cortex links [type] &#x3C;tag></code></td><td>List all links of a type parameter, such as metrics or openapi</td></tr><tr><td><code>/cortex logs &#x3C;tag></code></td><td>List all <a href="/pages/5cEJd1jQZq1Shqjz7YAg">logs links</a></td></tr><tr><td><code>/cortex oncall &#x3C;tag></code></td><td>Find current on-call info</td></tr><tr><td><code>/cortex owners &#x3C;tag></code></td><td>List all owners and their email addresses</td></tr><tr><td><code>/cortex resource &#x3C;tag></code></td><td>List resource information, such as owners, on-call, links, and timeline events</td></tr><tr><td><code>/cortex runbooks &#x3C;tag></code></td><td>List all <a href="/pages/5cEJd1jQZq1Shqjz7YAg">runbook links</a></td></tr><tr><td><code>/cortex scores &#x3C;tag></code></td><td>List all Scorecard scores</td></tr><tr><td><code>/cortex search &#x3C;tag></code></td><td>Query for entities using <a href="/pages/cOhPloxZuPnDbOFFmoc4">Cortex search</a>:<br><br>For example:<br>- Search by tag with <code>key:value</code><br>- Search by group with <code>group:name</code></td></tr><tr><td><code>/cortex sentry &#x3C;tag></code></td><td>List recent Sentry issues</td></tr><tr><td><code>/cortex service &#x3C;tag></code></td><td>List service information, such as owners, on-call, links, and timeline events</td></tr><tr><td><code>/cortex team &#x3C;tag></code></td><td>List team information, such as owned entities, links, and timeline events</td></tr><tr><td><code>/cortex timeline &#x3C;tag></code></td><td>List recent timeline events</td></tr></tbody></table>

### Adding the AI Assistant to a private channel

To receive notifications in a private channel:

1. Open the Slack channel where you want to add the app.
2. Type `@Cortex` and press **Enter**.\
   Slack prompts you to take action.
3. Click **Add them**.\
   The Cortex app is added to the channel.

### Cortex notifications via Slack

The AI Assistant notifies you according to your workspace and personal notification settings. See [Managing Slack notifications](/ingesting-data-into-cortex/integrations/slack.md#managing-slack-notifications) for more information.

## Connecting an entity to a Slack channel

Slack channels must be associated with entities in Cortex. Connect them in an [entity descriptor](/ingesting-data-into-cortex/entities-overview/entities.md#defining-entities-via-yaml-file) (for GitOps workflows) or through the Cortex UI. Slack channels can also be added as [external documentation links](/ingesting-data-into-cortex/entities-overview/entities/external-docs.md) on an entity, even without configuring the integration.

{% hint style="info" %}
If a Slack channel is registered for an entity but isn't showing up on the entity page, check that the **Communications** section is enabled in the entity's sidebar configuration. If it's disabled, registered channels are hidden from view.
{% endhint %}

### Connecting via the Cortex UI

1. Navigate to an entity's details page.
2. In the upper-right corner, click **Configure entity**.
3. Select the **Slack channels** tab, then click **Add**.
4. In the side pane, configure the Slack channel details:
   * **Channel name** - Type in or select your Slack channel's name.
   * **Description** - Add a description to help others understand the purpose of the Slack channel.
   * **Notifications** - If enabled, you will receive notifications to this Slack channel.
5. At the bottom of the side pane, click **Add**.

### Connecting via entity descriptor

#### **Editing the entity descriptor**

For any entity type, you can use the entity descriptor to define Slack channels (by name or ID) and toggle notifications on or off for each one. Defined channels are then accessible directly from the entity's page in Cortex.

#### **When to define by channel name vs. channel ID**

Defining by name is more easily recognizable to users when viewing the entity's YAML. However, if a Slack channel's name is likely to change, it's better to define by ID as it won't break the entity's Slack link in Cortex.

{% hint style="info" %}
Slack channels registered by ID alone in `x-cortex-slack` automatically resolve to their channel names in the entity sidebar. If no cached name is available, the channel ID is shown as a fallback.
{% endhint %}

**Defining by channel names**

{% hint style="info" %}
It's recommended to register Slack channels by ID, rather than by name, as channel names may change over time. When you register a channel by ID, Cortex resolves the channel name automatically for display in the entity view.
{% endhint %}

```yaml
x-cortex-slack:
  channels:
  - name: team-engineering
    notificationsEnabled: true
    description: Hangout spot for the engineering team.
```

<table><thead><tr><th width="205.5546875">Field</th><th width="401.875">Description</th><th align="center">Required</th></tr></thead><tbody><tr><td><code>name</code></td><td>Slack channel name.</td><td align="center"><i class="fa-check">:check:</i></td></tr><tr><td><code>notificationsEnabled</code></td><td>Boolean to enable or disable notifications in Slack.</td><td align="center"><i class="fa-check">:check:</i></td></tr><tr><td><code>description</code></td><td>Description of the Slack channel.</td><td align="center"><i class="fa-x">:x:</i></td></tr></tbody></table>

**Defining by channel IDs**

{% hint style="info" %}
It's recommended to register Slack channels by ID, rather than by name, as channel names may change over time. When you register a channel by ID, Cortex resolves the channel name automatically for display in the entity view.
{% endhint %}

```yaml
x-cortex-slack:
  channels:
  - id: ABCDEF123
    notificationsEnabled: true
    description: Hangout spot for the engineering team.
```

<table><thead><tr><th width="205.68359375">Field</th><th width="397.484375">Description</th><th align="center">Required</th></tr></thead><tbody><tr><td><code>id</code></td><td>Slack channel ID</td><td align="center"><i class="fa-check">:check:</i></td></tr><tr><td><code>notificationsEnabled</code></td><td>Boolean to enable or disable notifications in Slack</td><td align="center"><i class="fa-check">:check:</i></td></tr><tr><td><code>description</code></td><td>Description of the Slack channel</td><td align="center"><i class="fa-x">:x:</i></td></tr></tbody></table>

**Connect channels to entities without configuring the integration for Slack**

You can connect Slack channels to entities without configuring the Slack integration. Note that this method only provides a link to Slack from the entity; it won't include any features of the Slack integration, such as ownership tracking, notifications, Slack Bot, and the ability to use CQL to query Slack data.

Use [Slack's redirect link](https://api.slack.com/reference/deep-linking#deep-linking-into-your-slack-app) format, `https://slack.com/app_redirect?channel={channel_name}`, to add the link to an entity YAML, under the `x-cortex-slack` block. Make sure to replace `channel_name` with your Slack channel's name.

```yaml
x-cortex-slack:
  channels:
  - name: https://slack.com/app_redirect?channel=channel_name
```

## Creating Scorecard rules and writing CQL queries with the Slack integration <a href="#create-scorecard-rules" id="create-scorecard-rules"></a>

See examples below.

<details>

<summary>Check if Slack channel is set</summary>

Checks if an entity has a registered Slack channel in its entity descriptor.

**Definition:** `slack (==/!=) null`

**Example**

For a Scorecard focused on onboarding entities, you can define a rule to make sure each entity has a registered Slack channel:

```
slack != null
```

Defining a rule to make sure a Slack channel is set is a good way to make sure that users can reach out to entity owners for more information or if an issue arises.

</details>

<details>

<summary>Number of Slack channels</summary>

Counts the number of Slack channels registered for a given entity.

**Definition:** `slack.channels().length`

**Example**

Similar to `slack != null`, you can use this expression to write a rule checking that entities are linked to a Slack channnel:

```
slack.channels().length > 0
```

This rule makes sure that there is at least one Slack channel set.

</details>

<details>

<summary>Total number of members across Slack channel</summary>

Counts the total number of members across all registered Slack channels.

**Definition:** `slack.numOfMembers()`

**Example**

You can use this expression in the Query Builder to find entities linked to empty Slack channels:

```
slack.numOfMembers() < 1
```

If an entity is linked to an empty Slack channel, it might indicate a gap in your notification process.

</details>

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer).

## Viewing Slack integration logs

{% hint style="info" %}
This feature is available in Cortex cloud.
{% endhint %}

Integration logs provide visibility into the activity between Cortex and Slack, making them a useful first stop when troubleshooting. You can use them to investigate failed notifications, confirm that webhooks are being delivered, and verify that recent configuration changes are working as expected.

1. From the main sidebar, select **Integrations**.
2. Locate Slack, then click **Settings**.
3. Select the **Logs** tab. Note that logs are retained for 7 days.

See [Troubleshooting with integration logs](/ingesting-data-into-cortex/integrations.md#troubleshooting-with-integration-logs) for more information.