> ## Documentation Index > Fetch the complete documentation index at: https://docs.particle.pro/llms.txt > Use this file to discover all available pages before exploring further. # Deliver alerts to Slack > Post alert matches to a Slack channel: connect a workspace, attach a channel to an alert, and see what the message looks like. export const DashboardLink = ({children}) => { return {children}; }; export const APIKeysLink = ({children}) => { return {children}; }; An alert can post each match to a Slack channel as a richly formatted message — the episode, the matched dialogue, an AI summary, and a link to listen — instead of (or alongside) email and webhooks. Setting one up is three steps: Install the Particle Slack app into your workspace from the dashboard. This is a one-time OAuth step per workspace and produces a reusable connection. Add a `SLACK` notification channel that references the connection and the channel to post in. Every match the alert produces is posted to that channel by the Particle app. ## Before you start * **Plan** — Slack delivery is part of the alerts feature, so it requires a **Team**, **Business**, or **Enterprise** plan, the same as [creating alerts](/alerts/create#before-you-start). * **A connected workspace** — Connecting a workspace is an OAuth install done by a signed-in user in the dashboard; it can't be done with an API key. See [Connect a workspace](#1-connect-a-workspace). * **An API key** — Once a workspace is connected, you reference it from an alert with a standard `X-API-Key`, bound to the same project. Create one on the API keys page. ## 1. Connect a workspace In the dashboard, open your project's settings and find the Slack integration, then click **Connect Slack**. You're redirected to Slack to choose the workspace and approve the Particle app. The app requests permission to list channels and post messages. Slack returns you to the dashboard with the workspace connected. The connection is reusable — one workspace serves every alert in the project. The Particle app can post to any **public** channel without being invited. To post to a **private** channel, invite the app to that channel in Slack first (`/invite @Particle`), then it will appear in the channel list. ## 2. Find the connection and channel IDs To attach Slack to an alert over the API, you need the connection's `id` and the target channel's `slack_channel_id`. Both come from the API. ```bash List the project's Slack connections theme={"dark"} curl "https://api.particle.pro/v1/projects/$PARTICLE_PROJECT_ID/slack/connections" \ -H "X-API-Key: $PARTICLE_API_KEY" ``` ```json Response (200) theme={"dark"} { "data": [ { "id": "Sk7n2Lp9Qm4xZ", "project_id": "Vb3xN1aPq8", "surface": "PLATFORM", "slack_team_id": "T01234ABC", "slack_team_name": "Acme Inc", "slack_app_id": "A01234XYZ", "scope": "chat:write,chat:write.public,channels:read,groups:read", "installed_at": "2026-06-16T15:00:00Z" } ] } ``` ```bash List the channels a connection can post to theme={"dark"} curl "https://api.particle.pro/v1/projects/$PARTICLE_PROJECT_ID/slack/connections/Sk7n2Lp9Qm4xZ/channels" \ -H "X-API-Key: $PARTICLE_API_KEY" ``` ```json Response (200) theme={"dark"} { "data": [ { "slack_channel_id": "C01234XYZ", "name": "press-mentions" }, { "slack_channel_id": "C09876ABC", "name": "competitive-intel" } ] } ``` The channels endpoint refreshes the list from Slack on each call, so if you just created a channel or invited the app to a private one, call it again to pick up the change. Public channel IDs start with `C`; private channel IDs start with `G`. ## 3. Attach the channel to an alert Slack is a notification channel like any other. Add an entry to an alert's `notifications` array with `type: "SLACK"`, the connection's `id` as `slack_connection_id`, and the channel's `slack_channel_id`. You can mix it with `EMAIL` and `WEBHOOK` channels on the same alert. ```bash theme={"dark"} curl -X POST "https://api.particle.pro/v1/projects/$PARTICLE_PROJECT_ID/alerts" \ -H "X-API-Key: $PARTICLE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "title": "Nvidia mentions on podcasts", "kind": "ENTITY_MENTION", "delivery_cadence": "REALTIME", "entities": [ { "entity_type": "COMPANY", "entity_id": "3CensCwu5G2oKCFgPrNf89" } ], "notifications": [ { "type": "SLACK", "slack_connection_id": "Sk7n2Lp9Qm4xZ", "slack_channel_id": "C01234XYZ" } ] }' ``` You can also add a Slack channel to an existing alert with `PATCH /v1/alerts/{id}`. Remember that `notifications`, when present in a `PATCH`, **replaces the whole set** — include every channel you want to keep. See [Create and manage alerts](/alerts/create#update-pause-and-delete). `slack_channel_name` is optional — the server fills it in from the connection's channel list, so you don't need to send it. The channel must be one the connection can see (from the [channels endpoint](#2-find-the-connection-and-channel-ids)), and the connection's `surface` must match the alert's. A connection created from the platform dashboard is `PLATFORM`, and an alert created with an API key is `PLATFORM`, so they match by default. An unknown connection, an unlisted channel, or a surface mismatch returns [`validation_error`](/errors/validation_error). ## What the Slack message looks like Realtime matches post one message per match, built with Slack Block Kit: * A **headline** — `Nvidia mentioned on Acquired` for a mention, or `Sam Altman appeared on Lex Fridman Podcast as Guest` for a speaker appearance. * An **episode card** with the episode title linked, the podcast name, and the podcast's cover art. * A row of **metadata chips**: mention/line count, the relevance verdict (`On-Target` / `Incidental`), the podcast's popularity badge, and its political leaning — whichever apply. * An **AI summary** of the match, when it's ready. * Up to **two transcript excerpts**, each with the speaker, timestamps, the matched line highlighted, and a **Listen to the clip** link into the audio. * Three buttons: **Open in Particle** (the full result page), **Manage alert**, and **Disable this alert**. A `DAILY` or `WEEKLY` alert posts a single digest message instead: matches grouped by podcast (up to five podcasts, a couple of episodes each), with the per-match excerpt and clip link. The weekly digest adds an overall sentiment and a short "this week at a glance" recap. The difference between the two alert kinds shows up in the wording: `ENTITY_MENTION` messages count *mentions*, while `PODCAST_SPEAKER` messages note the speaker's *role* (`GUEST`, `PANELIST`, `CORRESPONDENT`, `AUDIENCE`, or `SOUNDBITE_SPEAKER`) and count *lines spoken*. ## Delivery and reliability * **Realtime matches post as they're detected,** by the Particle app's bot, using its OAuth token — there's no secret for you to manage. * **Failed posts are retried.** A transient Slack error is retried automatically. * **Token-level revocation stops delivery for every alert** — if the app is removed from the workspace or its OAuth token is otherwise revoked (`token_revoked`, `account_inactive`, `missing_scope`), the connection is marked revoked and disappears from the list. Reconnect from the dashboard to resume. * **Channel-level failures drop only that message** — if the channel is archived or the bot is kicked from a private channel (`is_archived`, `not_in_channel`), that single post is dropped (not retried), but the connection stays active and keeps delivering elsewhere. Re-invite the app to the private channel (`/invite @Particle`) or unarchive the channel to resume delivery to it. * **Deleting a connection** stops delivery for every alert that referenced it; those alerts simply skip the Slack channel and keep firing their other channels. ## Manage connections ```bash List a project's connections theme={"dark"} curl "https://api.particle.pro/v1/projects/$PARTICLE_PROJECT_ID/slack/connections" \ -H "X-API-Key: $PARTICLE_API_KEY" ``` ```bash Refresh and list a connection's channels theme={"dark"} curl "https://api.particle.pro/v1/projects/$PARTICLE_PROJECT_ID/slack/connections/Sk7n2Lp9Qm4xZ/channels" \ -H "X-API-Key: $PARTICLE_API_KEY" ``` ```bash Delete a connection (soft delete; referencing alerts skip it) theme={"dark"} curl -X DELETE "https://api.particle.pro/v1/projects/$PARTICLE_PROJECT_ID/slack/connections/Sk7n2Lp9Qm4xZ" \ -H "X-API-Key: $PARTICLE_API_KEY" ``` There's no secret to rotate — the connection authenticates with the OAuth token granted at install. To change scopes or recover from a revoked install, reconnect the workspace from the dashboard. The full request and response schema for each endpoint is in the API reference: | Method & path | Reference | | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | `GET /v1/projects/{projectId}/slack/connections` | [List Slack connections for a project](/api-reference/slack-connections/list-slack-connections-for-a-project) | | `GET /v1/projects/{projectId}/slack/connections/{id}/channels` | [List channels for a Slack connection](/api-reference/slack-connections/list-channels-for-a-slack-connection) | | `DELETE /v1/projects/{projectId}/slack/connections/{id}` | [Delete a Slack connection](/api-reference/slack-connections/delete-a-slack-connection) | ## Related * [Create and manage alerts](/alerts/create) — create an alert and attach notification channels * [Webhooks](/alerts/webhooks) — deliver matches to your own endpoint as a signed JSON POST * [Alerts overview](/alerts/overview) — alert kinds, delivery cadence, and the match model