Slack Integration
Connect Slack to capture decisions from your team's conversations.
Features
- Real-time capture -
@alignto capture decisions instantly - Context extraction - Automatically includes surrounding conversation
- Thread support - Capture decisions from threaded discussions
- Discover - Scan historical messages for past decisions
Setup (Cloud)
- Go to Settings → Integrations in Align
- Click Connect Slack
- Click Allow to authorize Align in your workspace
- Select which channels Align can access
Start with a few channels and expand as your team gets comfortable.
Capturing Decisions
Basic Capture
Mention @align with the decision:
@align We decided to use PostgreSQL for the user service
With Context
Include rationale for richer snapshots:
@align We're going with PostgreSQL instead of MongoDB.
Reasons:
- Need strong consistency for financial data
- Team has more Postgres experience
- Better tooling for our stack
In Threads
Reply in a thread with @align to capture the full thread context:
Thread: "Should we use Redis or Memcached?"
Reply: @align Going with Redis for the pub/sub capabilities
Commands
| Trigger | Description |
|---|---|
@align <decision> | Capture a new decision |
@align help | Show available commands |
| React with 📌 or 🔖 | Capture the message you reacted to. Works in any channel Align is in, with no per-channel setup. Workspace admins can change which emoji do this |
Ambient suggestions - where Align notices a decision-shaped thread and offers an ephemeral "capture this?" prompt - are off by default and enabled per channel by an admin. Nothing is stored unless someone confirms. See Capture.
Best Practices
- Be specific - Include the "why" not just the "what"
- Capture early - Don't wait until decisions are forgotten
- Use threads - Keeps decision context together
- Tag participants - Mention people involved in the decision
Permissions
Connecting Slack asks for read scopes only. Align asks for a write scope later, when you
switch on the feature that needs it, and the consent screen names that feature. The lists below are
read from services/gateway/src/auth/connectorScopeSets.ts.
Read scopes (the first connect)
| Scope | Purpose |
|---|---|
channels:read, groups:read | List public channels, and private channels the bot has been added to |
channels:history | Read messages in public channels |
channels:join | Join the public channels you tick on first connect, so the first scan has something to read. Joining adds the bot as a member and writes no message |
groups:history | Read messages in private channels the bot has been added to |
app_mentions:read | Receive the event Slack sends when someone mentions @Align |
users:read | Map Slack users to Align users |
users:read.email | Read the email of the person who asks Align a question in chat, so the check runs as them |
im:read, mpim:read | Tell a direct message or group DM apart before Align replies there |
im:history, mpim:history | Read the DM or group DM that /align was run in |
reactions:read | Receive the reaction a channel uses to mark a thread as a decision, where that channel has opted in |
Write scopes, one feature at a time
| Feature | Scopes it adds | What Align does with them |
|---|---|---|
Replies and capture cards posted in Slack (slack_replies) | chat:write | Answer @Align and /align, post a capture card after a reaction, reply in a thread when a decision conflicts |
Direct messages (slack_dm_digest) | chat:write, im:write | Open a direct message to send the weekly review list or a ratification request |
The /align slash command and message shortcut (slack_slash_command) | commands | Let Slack deliver /align and "Align this decision" to Align |
An eyes reaction on a mention, so people know Align saw it (slack_seen_reaction) | reactions:write | Put an eyes reaction on a mention the moment Align sees it, before the reply is ready. Without it the reaction is skipped and the reply still arrives |
Until a feature is on, Align does not post that kind of message. Slack itself refuses a post
without chat:write, so a missing scope cannot be worked around.
Private channels are never joined, and the first-connect picker never lists them; Align reads one only if someone adds the bot to it, and asks before scanning it.
Existing workspaces keep what they granted. Only a new connect starts read-only. Slack only grants a newly added scope when the app is re-authorized, so switching a write feature on sends a workspace admin through the Slack install once more, and the consent keeps the scopes already granted. The Connectors page shows which write features are on.
app_mentions:read follows the same rule. A workspace that connected Slack before it was requested
receives plain message events but not @Align mentions, so the bot never replies. Reconnect Slack in
the Connectors page to grant it.
reactions:write is optional in practice. A workspace that connected Slack before it was requested
still works: Align skips the eyes reaction it puts on a mention. Reconnect Slack in the Connectors
page to get it.
Troubleshooting
Align doesn't respond
- Ensure the Align app is installed in your workspace
- Check that Align has access to the channel
- Verify the bot is not muted
Missing context
- Align captures the last ~50 messages for context
- Very long threads may be truncated
- Private channels require explicit access
Self-Hosted Setup
On Align cloud, Align's OAuth app is used. Self-hosted, you register your own Slack app. See OAuth apps.