# 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 with Cortex. 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 %}

## Using the Cortex AI Assistant in Slack

{% hint style="info" %}
The Cortex AI Assistant requires the latest version of the Cortex Slack app. If you installed the app before February 2025, you'll need to update it before you can use the AI Assistant. 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 %}

After configuring the Slack integration, you can use commands to interact with the AI Assistant in your Slack workspace. The AI Assistant also powers notifications that are sent via Slack.

The AI Assistant is a Slack app called 'Cortex'. Use it with Slack in public or private channels, or via DM. Tag Cortex (type `@Cortex`) and ask a question.

You can also use the commands below in Slack to quickly query entity metadata and Scorecard scores. The `<tag>` refers to the entity's [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities.md#cortex-tag).

<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="https://lucene.apache.org/core/2_9_4/queryparsersyntax.html">Lucene queries</a>.<br><br>For example:<br>- Search by tag with <code>key:value</code><br>- Use wildcards: <code>foo*</code>, <code>foo:bar*</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 ensure you receive notifications in a private channel, make sure you have added it to that channel:

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

### AI Assistant notifications

The AI Assistant sends you notifications based on which notifications are configured for your workspace and based on your 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 an 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: A description for this Slack channel.
```

<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: This is a description for this Slack channel
```

<table><thead><tr><th width="205.68359375">Field</th><th width="397.484375">Description</th><th>Required</th></tr></thead><tbody><tr><td><code>id</code></td><td>Slack channel ID</td><td>Yes</td></tr><tr><td><code>notificationsEnabled</code></td><td>Boolean to enable or disable notifications in Slack</td><td>Yes</td></tr><tr><td><code>description</code></td><td>Description of the Slack channel</td><td>No</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](https://docs.cortex.io/ingesting-data-into-cortex/integrations#troubleshooting-with-integration-logs) for more information.

## Privacy policy <a href="#privacy-policy" id="privacy-policy"></a>

Cortex retains basic Slack metadata like user IDs for the period necessary to fulfill the purposes outlined in our [Privacy Policy](https://www.cortex.io/legal/privacy-policy) unless a longer retention period is required or permitted by law, or where the Customer Agreement requires or permits specific retention or deletion periods.

To request to access, transfer, or delete data, you can reach out to the Cortex support team.


---

# 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/ingesting-data-into-cortex/integrations/slack/using-the-integration-for-slack-ai-assistant.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.