Using the integration for Slack

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.

This article explains how to use the integration for Slack. For configuration instructions, see Configuring the integration for Slack.

Cortex conducts a background sync of Slack identities every day at 10 a.m. UTC.

Interacting with Cortex in Slack

Interacting with Cortex in Slack 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 chat with Cortex. Slack administrator permissions are required to perform the update.

To install, go to Slack settings in Cortex. Delete the existing configuration and reinstall following the prompts.

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

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

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 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 (for GitOps workflows) or through the Cortex UI. Slack channels can also be added as external documentation links on an entity, even without configuring the integration.

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.

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.

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.

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

Field	Description	Required
name	Slack channel name.
notificationsEnabled	Boolean to enable or disable notifications in Slack.
description	Description of the Slack channel.

Defining by channel IDs

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.

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

Field	Description	Required
id	Slack channel ID
notificationsEnabled	Boolean to enable or disable notifications in Slack
description	Description of the Slack channel

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

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

Creating Scorecard rules and writing CQL queries with the Slack integration

See examples below.

Check if Slack channel is set

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.

Number of Slack channels

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.

Total number of members across Slack channel

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.

See more examples in the CQL Explorer.

Viewing Slack integration logs

This feature is available in Cortex cloud.

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 for more information.