> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cymph.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Slack

> Send execution and task notifications from Cymph into a Slack channel.

## What Cymph uses it for

Cymph connects to Slack to **send notifications** — when a playbook execution changes state, or when a task is assigned to someone. Messages are posted to a channel you choose.

Slack is a notification target only. Cymph does not read your message history, and Slack is neither a content source nor a deployment target — playbooks cannot be deployed to it.

## Notification events

| Event                   | Sent when                                        |
| ----------------------- | ------------------------------------------------ |
| **Execution started**   | A playbook execution begins                      |
| **Execution completed** | An execution finishes successfully               |
| **Execution failed**    | An execution ends in failure                     |
| **Execution canceled**  | An execution is cancelled                        |
| **Task assigned**       | A task within an execution is assigned to a user |

All notifications for a single execution are posted as **replies in one thread**, so a run occupies one conversation in the channel rather than four separate messages.

## Requirements

| Field         | Description                                        |
| ------------- | -------------------------------------------------- |
| **Bot token** | A Slack bot user OAuth token (begins with `xoxb-`) |

There is no instance URL — Cymph connects to Slack's API at `https://slack.com/api`.

## App setup

1. Create a Slack app at [api.slack.com/apps](https://api.slack.com/apps) for your workspace.
2. Under **OAuth & Permissions**, add the bot token scopes listed below.
3. Install the app to your workspace and copy the **Bot User OAuth Token**.
4. **Invite the bot to every channel you want Cymph to post in** — see the warning below.

## Permissions

Add these as **Bot Token Scopes**:

| Scope           | Why Cymph needs it                                  |
| --------------- | --------------------------------------------------- |
| `chat:write`    | Post notification messages                          |
| `channels:read` | List public channels so you can pick a destination  |
| `groups:read`   | List private channels so you can pick a destination |

If you only ever post to public channels, `groups:read` can be omitted — private channels simply will not appear in the picker.

<Warning>
  Adding the scopes is not enough on its own: the bot must also be **a member of the destination channel**. Slack rejects `chat.postMessage` with `not_in_channel` for any channel the app has not been invited to, public ones included. In Slack, open the channel and run `/invite @YourAppName`.
</Warning>

<Tip>
  If a notification fails with a scope error, Cymph reports both what your token was granted and what the call required — for example `Slack API error: missing_scope (granted: chat:write; accepted: channels:read)`. That message tells you exactly which scope to add.
</Tip>

## What Cymph reads and writes

| Purpose                                  | Slack API method         |
| ---------------------------------------- | ------------------------ |
| Test the connection                      | `POST auth.test`         |
| List channels for the destination picker | `GET conversations.list` |
| Send a notification                      | `POST chat.postMessage`  |

Channel enumeration covers public and private channels, follows Slack's pagination to the end, and reads only each channel's name, ID, privacy flag, membership flag, and member count. Archived channels are filtered out of the picker.

Cymph never reads message content and never deletes or edits messages after posting.

## Testing the connection

**Test Connection** calls `auth.test` and reports:

| Message                                                       | Meaning                                                                                                               |
| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Valid Slack configuration for *workspace* as *user***       | The token was accepted; the workspace and bot identity are echoed back so you can confirm you connected the right one |
| **Authorization failed**                                      | The token was rejected — usually revoked, or from a different workspace                                               |
| **Slack API error: missing\_scope (granted: …; accepted: …)** | The token is valid but lacks a required scope                                                                         |
| **Connection timed out**                                      | No response within the timeout                                                                                        |

<Note>
  A successful test confirms the token and its scopes, but **not** channel membership. If notifications never arrive despite a green test, the bot has almost certainly not been invited to the destination channel.
</Note>

## Related

Per-user email notification preferences are separate and live in [Notification settings](/settings/notifications).