> 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

How to use the integration for Slack in Cortex

{% 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 %}

## Connecting an entity to a Slack channel

Slack channels can be associated with entities in Cortex. Connect them through the Cortex UI or via YAML. 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.

### Connecting via the Cortex UI

1. Go to an [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details.md).
2. In the upper-right corner, click **Configure entity**.
3. In the left entity menu, select **Communications**.
4. In the Slack channels section, click **Add**.
5. In the Slack side panel, do the following:
   *  From the **Channel name** dropdown, type in or select your Slack channel's name (required).
   * Under **Description**, add a description to help others understand the purpose of the Slack channel.
   * Optionally, toggle on **Notifications** to receive notifications about this entity to the selected Slack channel.
6. Click **Add**.

### Connecting via YAML

#### **Editing the YAML**

For any entity type, you can define Slack channels in its YAML by name or ID, and turn notifications on or off for each channel. Those channels then appear on the entity's details 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.

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.

**Defining by channel names**

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.

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

<table><thead><tr><th width="209.98828125">Field</th><th width="265.53515625">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**

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

<table><thead><tr><th width="209.640625">Field</th><th width="266.48828125">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=team-engineering
```

### Viewing Slack information in Cortex

Slack channels appear at the top of an entity's details page in the **Communications** block. Click a channel name to go directly to that channel in Slack.

<div align="left" data-full-width="false" data-with-frame="true"><figure><img src="https://826863033-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJW7pYRxS4dHS3Hv6wxve%2Fuploads%2FXXG9OgW5PadZpyVGX9UM%2Fcomms-block.png?alt=media&amp;token=b0da3c5b-0910-4381-a3d2-eef62f23d40c" alt="" width="563"><figcaption></figcaption></figure></div>

If a Slack channel is registered for an entity but isn't showing up on the entity's details page, check that the **Communications** block is enabled in the [entity's metadata sidebar](/ingesting-data-into-cortex/entities-overview/entities/details.md#configuring-the-entity-metadata-sidebar). If it's disabled, registered channels are hidden from view.

## Using the AI assistant

To use the AI assistant in Slack, you must be a member of your organization's Cortex workspace, and your Cortex account must be mapped to your Slack identity.

The AI assistant does two things: it answers questions in natural language, and it delivers notifications.

**Natural-language chat**

Mention `@Cortex` in a channel or direct message and ask a question in plain language, such as "Which services does my team own?" This works best for open-ended or analytical questions. Cortex responds in a thread. See Cortex's [prompt library](/get-started/cortex-ai-assistant/library.md) for more examples.

To ask a follow-up, reply in that same thread. Cortex keeps the context of the conversation, so you can drill down without repeating information. Context is scoped to the thread: a new top-level message starts a fresh conversation with no prior context.

The AI assistant is read-only. It can query Cortex, but it can't make changes or write data.

When you mention `@Cortex`, Cortex:

1. Interprets your question.
2. Determines which Cortex API endpoints to call.
3. Retrieves the relevant data from your Cortex workspace.
4. Returns a formatted response in Slack.

Each response includes reaction options. React with `:thumbs_up:` or `:thumbs_down:` to rate the answer. Cortex uses this feedback to improve future responses.

**Notifications**

The AI assistant also delivers Scorecard, Initiative, and weekly summary notifications to users and channels. See [Managing Slack notifications](#managing-slack-notifications) below.

### Adding the AI assistant to a Slack channel

You must add the AI assistant to a channel before you can use it there. Both public and private channels are supported.

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 AI Assistant is added to the channel.

### Available capabilities

The following API endpoints are accessed when chatting with Cortex:

<table data-full-width="false"><thead><tr><th width="205.5078125">Capability</th><th>Description</th></tr></thead><tbody><tr><td><strong>Entity details</strong></td><td>Look up ownership, metadata, and custom data for any entity</td></tr><tr><td><strong>Entity descriptors</strong></td><td>View and list entity descriptors (YAML definitions)</td></tr><tr><td><strong>Dependencies</strong></td><td>List incoming and outgoing dependencies for an entity</td></tr><tr><td><strong>Docs search</strong></td><td>Look up and access information in Cortex docs, as well as CQL formatting</td></tr><tr><td><strong>On-call</strong></td><td>Check who is currently on-call for an entity</td></tr><tr><td><strong>Scorecards</strong></td><td>List Scorecards, view scores, and get next-step recommendations</td></tr><tr><td><strong>Initiatives</strong></td><td>List and inspect Initiatives and their progress</td></tr><tr><td><strong>Relationships</strong></td><td>Explore entity relationships and relationship types</td></tr><tr><td><strong>Team details</strong></td><td>View team membership, sourcing, and contact channels</td></tr><tr><td><strong>Workspace context</strong></td><td>Query "my" entities and how they perform against Scorecards</td></tr><tr><td><strong>Eng Intelligence metrics / traces</strong></td><td>Query DORA metrics, incident trends, PR data, and other engineering performance indicators</td></tr><tr><td><strong>Deployments</strong></td><td>Search deployments across the workspace by environment, type, entity, and time range; list available deployment environments</td></tr></tbody></table>

## 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).

## Managing Slack notifications

Slack notifications are controlled at two levels:

* **Workspace settings** - In Cortex, admins (or users with the `Configure Workspace Notification Settings` permission) can enable or disable Slack as a delivery channel for each notification type. This determines which notifications are available to send via Slack across the workspace.
  * Note that if a notification type is disabled at the workspace level, users won't be able to opt into it in their personal settings.
* **Personal settings** - Individual users can then choose which of the available Slack notifications they want to receive in their own personal notification settings.

**How notifications are routed**

Notifications are delivered by the integration and are routed based on their type:

* **User-based notifications** are sent as direct messages to the relevant user.
* **Team-based notifications** are sent to the Slack channel associated with a team.
* **Entity-based notifications** are sent to the Slack channel associated with an entity.

Notifications can be delivered to private Slack channels, but the Cortex AI assistant must be a member of the channel for messages to come through.

Additionally, the AI assistant sends user-based and team-based weekly reports. The user-based weekly report summarizes how their entities are tracking against Scorecards and Initiatives. The team-based report delivers the same summary for entities owned by that team.

See [Notifications](/configure/settings/notifications.md) for more information.

## 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.