Slack

Capabilities

• Phase change notifications (e.g. "Task moved to Review")
• Review request routing to specific channels or users
• Project milestone alerts (all tasks in Handoff phase)
• Daily or weekly digest of design progress
• Interactive messages with action buttons (approve, request changes)

Authentication

The Slack integration uses OAuth 2.0 (V2). When registering Hierarch as a Slack app:

App Configuration

Required Bot Token Scopes

Optional Scopes

OAuth Flow

The Slack OAuth flow follows the standard V2 pattern:

1. User clicks "Connect Slack" in Hierarch settings
2. Redirect to:
   https://slack.com/oauth/v2/authorize
     ?client_id=YOUR_CLIENT_ID
     &scope=chat:write,channels:read,groups:read,users:read,users:read.email
     &redirect_uri=https://hierarch.vercel.app/api/auth/callback/slack
     &state=[random_state_token]

3. User authorizes the Hierarch app in their workspace
4. Slack redirects to the callback URL with an authorization code
5. Hierarch's serverless function exchanges the code:
   POST https://slack.com/api/oauth.v2.access
     client_id, client_secret, code, redirect_uri

6. Response includes bot_token (xoxb-) and team info
7. Token stored server-side in Supabase, associated with the user

Data Hierarch Reads

• Channel list (public and private the bot can see) for the notification channel picker
• User list for @mention routing on feedback requests
• User email addresses to match Slack identities with Hierarch accounts

Hierarch does not read message history, files, or any channel content. The integration is outbound-only: Hierarch pushes to Slack and does not pull from it.

Data Hierarch Writes

• Notification messages in designated channels
• Direct messages for feedback requests (if user opts in)
• Interactive message attachments with action buttons

All messages are posted by the Hierarch bot. The bot only posts to channels it has been explicitly added to. Users control which events trigger notifications through the Hierarch settings panel.

Notification Events

Users configure which events send Slack notifications in the settings panel:

Message Format

Slack messages use Block Kit for rich formatting. Example notification for a phase change:

{
  "channel": "C0123DESIGN",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*Homepage Redesign* moved to *Review*\nProject: Marketing Site Refresh"
      }
    },
    {
      "type": "context",
      "elements": [
        {
          "type": "mrkdwn",
          "text": "Phase: Iterate → Review · <https://hierarch.vercel.app|Open in Hierarch>"
        }
      ]
    }
  ]
}

Slack API Methods

Hierarch uses these Slack Web API methods: