docs: prefer slack app alert guidance (#1350)

Author: thebiglabasky

examples/advanced-project-js/src/__checks__/utils/alert-channels.js

@@ -2,7 +2,7 @@ const { URL } = require('node:url')
 
 const {
   EmailAlertChannel,
-  SlackAlertChannel,
+  SlackAppAlertChannel,
   WebhookAlertChannel,
 } = require('checkly/constructs')
 
@@ -25,11 +25,8 @@ const emailChannel = new EmailAlertChannel('email-channel-1', {
   ...sendDefaults,
 })
 
-const slackChannel = new SlackAlertChannel('slack-channel-1', {
-  url: new URL(
-    'https://hooks.slack.com/services/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'
-  ),
-  channel: '#ops',
+const slackChannel = new SlackAppAlertChannel('slack-channel-1', {
+  slackChannels: ['#ops'],
   ...sendDefaults,
 })
 

examples/advanced-project/src/__checks__/utils/alert-channels.ts

@@ -1,7 +1,7 @@
 import { URL } from 'node:url'
 import {
   EmailAlertChannel,
-  SlackAlertChannel,
+  SlackAppAlertChannel,
   WebhookAlertChannel
 } from 'checkly/constructs'
 
@@ -25,9 +25,8 @@ export const emailChannel = new EmailAlertChannel('email-channel-1', {
   ...sendDefaults
 })
 
-export const slackChannel = new SlackAlertChannel('slack-channel-1', {
-  url: new URL('https://hooks.slack.com/services/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'),
-  channel: '#ops',
+export const slackChannel = new SlackAppAlertChannel('slack-channel-1', {
+  slackChannels: ['#ops'],
   ...sendDefaults
 })
 

packages/cli/src/ai-context/README.md

@@ -22,7 +22,7 @@ Agent Skills are a standardized format for giving AI agents specialized knowledg
 - Create and manage API checks, Browser Checks, URL monitors, and other monitors
 - Set up Playwright-based Browser and Multistep checks and Playwright Check Suites
 - Configure Heartbeat Monitors for cron jobs and scheduled tasks
-- Define alert channels (email, Slack, phone, webhooks, etc.)
+- Define alert channels (email, Slack App, phone, webhooks, etc.)
 - Build dashboards and status pages
 - Follow monitoring-as-code best practices with the Checkly CLI
 

packages/cli/src/ai-context/context.ts

@@ -45,7 +45,7 @@ export const REFERENCES = [
   },
   {
     id: 'configure-alert-channels',
-    description: 'Email (`EmailAlertChannel`), Phone (`PhoneCallAlertChannel`), Slack (`SlackAlertChannel`), and Slack App (`SlackAppAlertChannel`) alert channels',
+    description: 'Email (`EmailAlertChannel`), Phone (`PhoneCallAlertChannel`), Slack App (`SlackAppAlertChannel`), and other alert channels',
   },
   {
     id: 'configure-supporting-constructs',
@@ -276,11 +276,6 @@ const playwrightChecks = new PlaywrightCheck("multi-browser-check", {
     exampleConfigPath: 'resources/alert-channels/phone-call/test-user.check.ts',
     reference: 'https://www.checklyhq.com/docs/constructs/phone-call-alert-channel/',
   },
-  SLACK_ALERT_CHANNEL: {
-    templateString: '<!-- EXAMPLE: SLACK_ALERT_CHANNEL -->',
-    exampleConfigPath: 'resources/alert-channels/slack/general.check.ts',
-    reference: 'https://www.checklyhq.com/docs/constructs/slack-alert-channel/',
-  },
   SLACK_APP_ALERT_CHANNEL: {
     templateString: '<!-- EXAMPLE: SLACK_APP_ALERT_CHANNEL -->',
     exampleConfigPath: 'resources/alert-channels/slack-app/alerts-ops-alice.check.ts',

packages/cli/src/ai-context/references/configure-alert-channels.md

@@ -7,7 +7,9 @@ Here are some examples of how to create different types of alert channels.
 
 All available alerts are described in the [Checkly docs](https://www.checklyhq.com/docs/constructs/overview/).
 
-*Important*: Don't make up email addresses, phone numbers, Slack URLs or similar static values. Scan the project to discover a valid configuration or ask what the values should be.
+*Important*: Don't make up email addresses, phone numbers, Slack channel names or similar static values. Scan the project to discover a valid configuration or ask what the values should be.
+
+For new Slack notifications, prefer `SlackAppAlertChannel`. It uses the Checkly Slack App and only needs Slack `#channel` names or `@user` handles in `slackChannels`.
 
 ## Email Alert Channel
 
@@ -17,10 +19,6 @@ All available alerts are described in the [Checkly docs](https://www.checklyhq.c
 
 <!-- EXAMPLE: PHONE_CALL_ALERT_CHANNEL -->
 
-## Slack Alert Channel
-
-<!-- EXAMPLE: SLACK_ALERT_CHANNEL -->
-
 ## Slack App Alert Channel
 
 <!-- EXAMPLE: SLACK_APP_ALERT_CHANNEL -->

packages/cli/src/constructs/alert-channel.ts

@@ -122,9 +122,9 @@ export class AlertChannelRef extends Construct {
  *   sendDegraded: false
  * })
  *
- * // Slack alert channel with SSL monitoring
- * const slackAlert = new SlackAlertChannel('team-slack', {
- *   url: 'https://hooks.slack.com/services/...',
+ * // Slack App alert channel with SSL monitoring
+ * const slackAlert = new SlackAppAlertChannel('team-slack', {
+ *   slackChannels: ['#alerts'],
  *   sslExpiry: true,
  *   sslExpiryThreshold: 7  // Alert 7 days before SSL expiry
  * })

packages/cli/src/constructs/check.ts

@@ -191,8 +191,8 @@ export interface CheckProps {
    * const emailChannel = new EmailAlertChannel('team-email', {
    *   address: 'team@example.com'
    * })
-   * const slackChannel = new SlackAlertChannel('team-slack', {
-   *   url: 'https://hooks.slack.com/...'
+   * const slackChannel = new SlackAppAlertChannel('team-slack', {
+   *   slackChannels: ['#alerts']
    * })
    *
    * // Reference the channels in your check

skills/checkly/README.md

@@ -22,7 +22,7 @@ Agent Skills are a standardized format for giving AI agents specialized knowledg
 - Create and manage API checks, Browser Checks, URL monitors, and other monitors
 - Set up Playwright-based Browser and Multistep checks and Playwright Check Suites
 - Configure Heartbeat Monitors for cron jobs and scheduled tasks
-- Define alert channels (email, Slack, phone, webhooks, etc.)
+- Define alert channels (email, Slack App, phone, webhooks, etc.)
 - Build dashboards and status pages
 - Follow monitoring-as-code best practices with the Checkly CLI