# Bind a channel

> Bind a Slack, Discord or Teams channel to a By Dawn project, choose who can file requests there, subscribe it to updates, and sync its threads with tickets.

This page is for project admins. It shows you how to bind a chat channel to a project. After that, requests filed in
the channel land on the project's board, the updates you choose post to the channel, and threads stay in step with
their tickets.

A channel that isn't bound takes no requests. Only linked members can create tickets from it, and they choose the
project each time.

## Before you start

- You need to be a project admin or an org admin.
- An org admin has connected the platform in **Organization settings › Chat integrations** (see
  [Chat integrations](https://docs.bydawn.com/chat/#how-it-fits-together)).
- By Dawn has to be in the channel:
  - **Slack:** public channels are listed. For a private channel, invite the app first (`/invite @SAW`).
  - **Discord:** the server's text and announcement channels the bot can see are listed.
  - **Microsoft Teams:** the channels of each team the By Dawn app is installed in are listed.

## Bind it

1. Open **Project settings › Chat channels** and choose **Bind a channel**.

2. Pick the **Workspace** (a Slack workspace, Discord server or Teams tenant), then the **Channel**.

3. Fill in the rest:
   - **Default repo**: the repo a worker started from this channel works in. **Project default** uses the project's
     own.
   - **Requests from the channel**: who can file requests here (see [Intake modes](#intake-modes)).
   - **Request template**: the details a request from this channel must give (see [Request
     templates](#request-templates)).
   - **Default team**: the [team](https://docs.bydawn.com/teams/) that owns the tickets filed from the channel. With **No default team**,
     "Tickets filed from the channel go to the filer's team, or the project's default team." It lists the teams that
     work in the project, so attach one under the project's **Teams** first.

4. Choose **Bind #channel**.

A channel binds to one project. To have a channel hear about a second project, bind another channel in that project.

### Intake modes

| Mode | What it does |
|---|---|
| **Off** | Nobody files requests from the channel. Linked members can still create tickets and act. |
| **@SAW and 🎫** | Mentioning @SAW, or reacting to a message with 🎫, files it as a request. This is where a new binding starts. |
| **Every message** | Every new top-level message becomes a request. Thread replies, edits and bot posts don't. |

The 🎫 reaction and **Every message** work in Slack only for now. Discord can't read channel messages yet, so a
Discord channel takes requests through `/saw create` and **Create SAW ticket** instead.

When a request is filed, By Dawn answers in its thread with a card showing the request's status. The card follows the
ticket as it moves. Only the person who asked can **Close request** from it.

### Request templates

A template names the details a request must give. **None** files requests as written, with nothing asked for.

| Template | Asks for (required in bold) | Sets priority |
|---|---|---|
| Bug report | **What happened**, What should have happened, **Steps to reproduce**, Where | High |
| Feature request | **The problem**, What would solve it, Who asked, and why now | Medium |
| Task | **What to do**, **Done when** | Medium |
| Question | **The question**, What I have tried | Low |

The create form asks each field and won't submit until the required ones are filled. A request filed straight from a
message is filed at once. If the message doesn't already answer a required field under that heading, By Dawn asks in the
thread with **Complete your request**. The answers are added to the ticket as a comment from the person who asked.

## Who files what

People in a bound channel don't need a By Dawn account to ask for something:

- **A linked member** files as themselves, and can act on the ticket.
- **Anyone else** (an unlinked teammate, a guest, someone from another organisation in Slack Connect or a Teams shared
  channel) files a request. By Dawn records their chat name and id as where the request came from. They never become a
  By Dawn member, can't act on the ticket, and are never sent a DM.

A channel shared with another organisation is marked **shared** in the list. People there can file requests, and the
merge button never shows there. [Who may do what](https://docs.bydawn.com/chat/#who-may-do-what) has the full table.

## A channel's default customer

When your organization uses [Customers](https://docs.bydawn.com/customers/), a channel can belong to one customer, such as a Slack Connect
channel you share with Acme. Pick it under **Default customer** when you bind the channel, or later in the channel's
row. **No default customer** leaves requests without one.

- **A request filed in the channel** becomes a request from that customer, with the message as its quote and the
  person's chat name as who asked.
- **A linked member** filing from the channel picks the **Customer** in the create form. It starts on the channel's
  customer, and **No customer** files without one.

If the customer is deleted, the channel's requests are filed without one until you pick another. By Dawn never looks up a
chat user's email address to find their company: the channel's customer is the only match.

## Subscriptions

A subscription posts chosen events to the channel. Under the channel's **Subscriptions**, choose **Subscribe**, then
pick at least one event:

| Group | Events |
|---|---|
| Tickets | Ticket created, Status changed, Ticket completed |
| Agent runs | Agent needs input, Agent stalled, PR opened, CI failed, Agent shipped |
| Cycles & releases | Cycle started, Cycle completed, Release shipped |

Narrow it with **Labels**, **Status**, **Assignee** (including **Unassigned**), **Priority** and **Team** (the
teams that work in the project). Every filter you set
must match, and within one filter any value matches. A subscription with no filters covers every ticket in the
project. The ticket filters don't apply to cycle and release events.

A channel can have several subscriptions. Each event posts once per channel, even if more than one subscription
matches it. In Discord you can also manage them from the channel with `/saw subscribe`.

## Synced threads

A thread synced with a ticket carries the conversation both ways:

- **A reply in the thread** becomes a comment on the ticket. A linked member's reply is posted as them. Anyone else's
  is posted with the channel's authority, but only on a request that channel filed. Otherwise the reply stays in chat,
  and By Dawn tells the person privately, once per thread.
- **A comment in By Dawn** is posted into the thread, and the ticket's completion is announced there.

A thread is synced when its ticket was created from it. In Slack you can also link an existing thread with **Link to
SAW ticket**, from a message's ⋯ menu. One thread can track several tickets, and a ticket can have several threads.

Synced threads work in Slack and Microsoft Teams. Discord threads don't sync yet.

## Ticket previews

When someone pastes a link to a By Dawn ticket, By Dawn shows a preview of it in Slack and Teams. A preview reads with the
**channel's** authority, not the poster's, because everyone in the channel sees it. So a ticket only previews in a
channel bound to its own project, and never when that project is restricted. Every other By Dawn link stays a plain link
with **Open in SAW**.

## Merge from chat

**Merge from chat**, at the bottom of **Chat channels**, lets a run card's **Approve and merge** button merge this
project's pull requests. It's off by default. Even when it's on, a member also needs the **Merge** scope on their link,
a role that may merge, and the project's GitHub merge policy to allow it. See [Merging from
chat](https://docs.bydawn.com/chat/#merging-from-chat).

## Unbind

Choose **Unbind** on the channel's row. The channel stops filing requests into the project, and its subscriptions are
deleted. Threads already linked to tickets keep syncing.

> **Note:** In Teams, removing the By Dawn app from a team doesn't unbind its channels. Unbind them here, or By Dawn keeps trying to post
> there.

## Where to go next

- [Chat command reference](https://docs.bydawn.com/chat-commands/): what people in the channel can run.
- [Slack](https://docs.bydawn.com/chat-slack/) and [Discord](https://docs.bydawn.com/chat-discord/).

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