# Slack (capture feedback with an emoji)

Connect a Slack workspace to Usero and your team can capture feedback without leaving Slack. React to any message with an emoji
and it becomes a feedback item in your inbox. React with the wrench and Usero also drafts a GitHub pull request with a first pass
at the fix. You review the PR and merge it.

Connection is a Slack OAuth install, not a webhook or a personal token. You install the Usero app on your workspace, choose which
Usero project the feedback lands in, and Usero acts through that installation.

## What it does

- **Emoji capture.** React to a Slack message with the wrench (`:wrench:`) or pushpin (`:pushpin:`) and Usero records it as a
  feedback item, with the channel, the author, the thread, and a link back to the original message attached.
- **Wrench drafts a PR.** The wrench reaction captures the message and, if a GitHub repo is connected, opens a pull request with a
  first pass at the fix. The pushpin captures only.
- **Slash command.** `/usero <text>` captures a report you type directly, for feedback that was never a message to begin with.
- **No passive scraping.** Usero only reads a message when someone reacts to it or sends it via `/usero`. It does not watch your
  channels.

## Prerequisites

- A Usero account. The Slack install flow walks anonymous installers through signup before it binds the workspace to a project.
- Permission to install a Slack app on your workspace (or an admin who can approve it).
- For the wrench to draft a PR, a [connected GitHub repository](/docs/integrations/github). Without one, the wrench still captures
  the message; it just skips the PR.

## Connect Slack

1. Open your project, then go to **Integrations** (the URL is `usero.io/YOUR_CLIENT_ID/integrations`). To open your own
   integrations page, [go here](/integrations).
2. Find the **Slack** card and click **Connect Slack**.
3. You land on Slack's app authorization screen. Choose the workspace and approve the requested scopes.
4. Slack sends you back to Usero. The install is bound to the project you started from, and you land back on the integrations page
   with the Slack card showing as connected.

You can also start the install from the **Slack App Directory**. In that case Usero does not yet know which project to use, so
after you sign in (or sign up) it shows a short picker where you choose an existing project or create a new one for the workspace.
Each Slack workspace binds to one Usero project at a time; re-installing into a different project re-links it.

After connecting, the installer gets a welcome DM from Usero explaining the two emoji, with a **Connect a GitHub repo** button if
the project does not have one yet.

## How capture works (the two emojis)

Capturing is an emoji reaction. There are two, and they do different things:

- **`:wrench:` (capture and draft a PR).** Usero records the message as feedback and, if your repo is connected, opens a GitHub
  pull request with a first pass at the fix. The reactor sees a threaded reply: `Captured in usero. Drafting a PR...`. This is the
  reaction to reach for on an actionable bug or a small change request.
- **`:pushpin:` (capture only).** Usero records the message as feedback and stops. No PR. Use it for feedback worth keeping that is
  not ready to become code, or that you want to cluster with other reports first. You can still create a PR from it later in the
  dashboard.

The `/usero <text>` slash command captures a report you type, for example `/usero login button is broken on Safari`. It behaves
like the pushpin (capture only) and replies with a link to the captured item.

Capture is idempotent: reacting to the same message twice does not create a second feedback item.

## Private channels

For a **public** channel, the reaction is enough; Usero can read the message. For a **private** channel, invite the bot once with
`/invite @Usero` in that channel. If you react before inviting it, Usero DMs you to say it is not in the channel yet and to invite
it and react again, so the capture is never lost silently.

## Troubleshooting

**"I'm not in that channel yet" DM after reacting.** The message is in a private channel the bot has not joined. Run
`/invite @Usero` in that channel and react again.

**The wrench captured the message but no PR opened.** A PR needs a connected GitHub repo. Open the GitHub section of the project
and connect a repository (see the [GitHub integration docs](/docs/integrations/github)). The wrench still captures without one; it
just cannot draft a PR.

**The wrench captured but said the workspace is out of AI pull requests.** PR creation is metered by plan. The message is still
captured; you can upgrade in Usero, or create the PR next period. Capturing feedback is not metered, only drafting the PR is.

**The slash command times out or says the workspace is not connected.** The workspace finished the OAuth install but is not bound
to a project, or the install was removed. Re-run **Connect Slack** from the integrations page (or the Slack App Directory) and pick
a project.

**A reaction did nothing.** Only the wrench and pushpin reactions capture; other emoji are ignored. Reactions on non-message items
(files, etc.) and reactions on bot-authored messages are skipped on purpose.

**Removing Usero from Slack.** When a workspace admin uninstalls the app, Usero revokes its bot token and scrubs the Slack
identity pointers (author and reactor) off the feedback rows it holds. The feedback text and dashboard records stay; the
links back to the workspace are wiped.

## Next

- [Integrations overview](/docs/integrations)
- [Connect a GitHub repo (so the wrench can draft PRs)](/docs/integrations/github)
- [Find your clientId](/docs/find-your-client-id)