# Slack

> Connect a Slack workspace to By Dawn, what the app asks Slack for and why, private channels, Slack Connect, the App Home, and disconnecting.

This page is for org admins. It shows you how to add By Dawn to a Slack workspace. Once it's added, people can create
tickets with `/saw`, file requests with @SAW or 🎫, sync threads with tickets, and preview ticket links. Each member
then links their own account (see [Connect your chat account](https://docs.bydawn.com/chat-accounts/)).

## Before you start

- You need to be an org admin in By Dawn.
- You need to be allowed to install apps in the Slack workspace. If your workspace requires approval for apps, a
  Slack admin approves By Dawn's request first.

## Connect

1. In By Dawn, open **Organization settings › Chat integrations** and choose **Connect** on **Slack**. If a workspace is
   already connected, the button reads **Add a workspace**.

2. Slack shows what By Dawn asks for (listed below). Pick the workspace and choose **Allow**.

3. You're back in By Dawn, and the workspace is listed as **Connected**, with who installed it and when.

The install is tied to your By Dawn session, so it can't be attached to a different organization. Finish it within 10
minutes of choosing **Connect**, or start again.

Next, a project admin binds channels (see [Bind a channel](https://docs.bydawn.com/chat-channels/)). Until a channel is bound, only
linked members can create tickets from it.

## What By Dawn asks Slack for

By Dawn asks for these permissions and no others. Each one is there for one reason:

| Permission | Why |
|---|---|
| `app_mentions:read` | Turn a message that mentions @SAW into a ticket. |
| `channels:history` | Read the one message someone reacted to with 🎫, or a reply in a thread linked to a ticket, in a public channel. With AI intake on, also the thread a request is in, or the few messages its author sent just before it. |
| `channels:read` | List public channels so a project admin can bind one, and tell a Slack Connect channel from an internal one. |
| `chat:write` | Post confirmations, cards and thread replies, and update a card in place. |
| `commands` | Serve the `/saw` command and the **Create SAW ticket** and **Link to SAW ticket** shortcuts. |
| `files:read` | Attach the files on a message to the ticket made from it. |
| `groups:history` | The same as `channels:history`, in private channels By Dawn has been added to. |
| `groups:read` | The same as `channels:read`, for private channels By Dawn has been added to. |
| `im:write` | Open a direct message to send a person their account-link prompt and their own notifications. |
| `links:read` | See links to By Dawn tickets posted in a channel, so they can be previewed. |
| `links:write` | Turn a By Dawn ticket link into a preview, and show its details. |
| `reactions:read` | Turn a message someone reacts to with 🎫 into a request. |
| `openid`, `profile` | When a member links: prove which Slack user they are, and read their id, workspace and name once. |

By Dawn hears every message in the channels it's in, because that's how Slack delivers replies in synced threads and
messages in request channels. A message outside a linked thread, in a channel that isn't a request channel, is dropped
as soon as it's read and never stored (see [What By Dawn reads and keeps](https://docs.bydawn.com/chat/#what-by-dawn-reads-and-keeps)).

## Using By Dawn in Slack

The [command reference](https://docs.bydawn.com/chat-commands/#slack) lists everything. In short:

- `/saw` opens the create form, and so do the **Create SAW ticket** shortcuts.
- `@SAW` or a 🎫 reaction files a request in a bound channel.
- **Link to SAW ticket** syncs a thread with a ticket you already have.
- A pasted ticket link becomes a preview with **Start worker**, **Comment**, **Assign to me**, **Assign…**, **Change
  status…** and **Open in SAW**.

### Private channels

By Dawn only sees private channels it has been invited to. Run `/invite @SAW` in the channel, and a project admin can then
bind it.

### Slack Connect

A channel shared with another organisation is marked **shared** when it's bound. People from the other organisation
can file requests and see ticket previews. They can't act on tickets, By Dawn never DMs them, and the merge button never
shows in that channel.

### The App Home

Open By Dawn in Slack's sidebar and the **Home** tab shows a linked member their open tickets, most recently updated first:

- **Waiting on you**: tickets where a person is needed;
- **Your work**: the rest.

Each row has **Open**, **Change status…** and **Comment**, and **Start worker** before a run starts. It reads with the
viewer's own access, because only they see it. Someone who hasn't linked sees a button to link instead. The
**Messages** tab is where By Dawn's DMs arrive.

### Reading limits before the Slack Marketplace listing

Until By Dawn is listed on the Slack Marketplace, Slack lets it read a channel's history only once a minute, 15 messages
at a time. This affects only AI intake, which reads the thread or the messages before a request. When several requests
arrive at once, they queue behind each other. Thread sync and everything else are unaffected, because they use the
messages Slack sends By Dawn.

## When Slack asks you to reinstall

When By Dawn gains a Slack feature that needs a new event or permission, Slack asks a workspace admin to approve the
change. The new feature works in that workspace once it's approved.

If Slack stops accepting By Dawn's access, for example because the app was removed or its token revoked, the workspace
shows **Needs reconnecting**. Nothing posts or syncs there until an admin chooses **Reconnect**.

## Disconnect

Choose **Disconnect** next to the workspace in **Organization settings › Chat integrations**. By Dawn uninstalls itself
from the workspace, and:

- unbinds every channel in it from its project, with the channels' subscriptions;
- unlinks every member's Slack account in it, and revokes what they let By Dawn do as them;
- stops syncing its threads and updating its cards;
- deletes the token Slack gave By Dawn.

Removing the By Dawn app from Slack's own app settings does the same. Comments already synced stay on their tickets.

> **Note:** By Dawn uses Slack's Events API over HTTP, never Socket Mode, so nothing needs to run inside your network.

## Where to go next

- [Bind a channel](https://docs.bydawn.com/chat-channels/).
- [Chat command reference](https://docs.bydawn.com/chat-commands/#slack).
- [Chat integrations](https://docs.bydawn.com/chat/): who may do what, and what By Dawn keeps.

Source: https://docs.bydawn.com/chat-slack/