> ## Documentation Index
> Fetch the complete documentation index at: https://mako-docs.devinagiffy.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Slack Setup

> Connect Hitler to your Slack workspace

## Overview

Hitler integrates with Slack to provide:

* **Sign in with Slack** - Employees authenticate using their Slack identity
* **Bot interactions** - Create tasks, log moods, and more via DM or channel mentions
* **Notifications** - Receive task reminders and check-in prompts

## Prerequisites

<Check>Slack workspace admin permissions</Check>
<Check>Hitler organization created</Check>

## Installation

### Step 1: Navigate to Integrations

1. Log in to [app.hitler.app](https://app.hitler.app)
2. Go to **Settings → Integrations**
3. Find the Slack card

<Frame>
  <img src="https://mintcdn.com/pranavinagiffynews/m4rmCx9w5QZOQ6hw/images/integrations-page.svg?fit=max&auto=format&n=m4rmCx9w5QZOQ6hw&q=85&s=553edae53c87265adb98f14266c0fee2" alt="Integrations Page" width="600" height="300" data-path="images/integrations-page.svg" />
</Frame>

### Step 2: Click "Add to Slack"

This initiates the OAuth flow with Slack.

<Warning>
  You must be a Slack workspace admin to install apps. If you're not an admin, share this page with
  your Slack administrator.
</Warning>

### Step 3: Authorize Permissions

Hitler requests the following permissions:

| Permission          | Purpose                                         |
| ------------------- | ----------------------------------------------- |
| `app_mentions:read` | View messages that directly mention the bot     |
| `channels:history`  | View messages in public channels the bot is in  |
| `chat:write`        | Send messages as the bot                        |
| `commands`          | Add slash commands (e.g. `/hitler`)             |
| `groups:history`    | View messages in private channels the bot is in |
| `im:history`        | View messages in DMs with the bot               |
| `im:read`           | View basic info about DMs the bot is in         |
| `im:write`          | Start direct messages with people               |
| `mpim:history`      | View messages in group DMs the bot is in        |
| `team:read`         | View workspace name, email domain, and icon     |
| `users:read`        | View people in the workspace                    |

<Info>
  Hitler uses **Socket Mode** (WebSocket connection), so you don't need ngrok or a public URL.
  All permissions listed above are Bot Token Scopes.
</Info>

### Step 4: Confirm Installation

After authorization, you'll be redirected back to the Hitler onboarding page with a success confirmation.

You'll also receive a **welcome DM** from the Hitler bot in Slack:

> Hey! Hitler is now connected to your workspace. You can start chatting with me right here — try saying "hello" or "what are my tasks?"

### Step 5: Test the Connection

On the onboarding page, you can click **Send Test Message** to verify the bot can send you DMs. This helps confirm everything is working before you proceed.

The Slack integration card will now show:

* **Connected** status
* Workspace name
* Connection date

## User Sign-In

Once Slack is connected, team members can sign in using Slack:

1. Go to [app.hitler.app/login](https://app.hitler.app/login)
2. Click **Sign in with Slack**
3. Authorize with their Slack account
4. If new user → Complete profile setup
5. If existing user → Redirected to dashboard

<Note>Users must belong to a Slack workspace that has Hitler installed to sign in with Slack.</Note>

## Bot Usage

### Invite the Bot

Before the bot can respond in a channel, invite it:

```
/invite @Hitler
```

For DMs, simply message the bot directly.

### Basic Commands

| Command                      | Description          |
| ---------------------------- | -------------------- |
| `@Hitler help`               | List all commands    |
| `@Hitler task <description>` | Create a task        |
| `@Hitler mood`               | Log today's mood     |
| `@Hitler tasks`              | View your tasks      |
| `@Hitler stats`              | View your statistics |

See [Bot Commands](/integrations/bot-commands) for the full list.

## Configuration

### Customize Check-in Time

By default, mood check-ins are sent at 9:00 AM in each user's timezone.

To change this:

1. Go to **Settings → Notifications**
2. Set your preferred check-in time
3. Save changes

### Enable/Disable Features

Admins can toggle specific bot features:

* Daily mood check-ins
* Task reminders
* Weekly summaries

## Two Slack Apps (Dev + Production)

We strongly recommend creating **two separate Slack apps** — one for local development and one for production. This prevents dev testing from sending messages to real users and keeps credentials isolated.

|                        | Development App                                 | Production App                                             |
| ---------------------- | ----------------------------------------------- | ---------------------------------------------------------- |
| **App Name**           | `Hitler Dev`                                    | `Hitler`                                                   |
| **Socket Mode**        | Enabled                                         | Enabled                                                    |
| **OAuth Redirect URL** | `http://localhost:3000/api/auth/slack/callback` | `https://api.mako.devinagiffy.xyz/api/auth/slack/callback` |
| **Workspace**          | Your dev/test workspace                         | Your production workspace                                  |
| **Used by**            | `pnpm dev` (local)                              | Docker deployment on VPS                                   |

### Create Each App

For **both** apps, follow these steps:

1. Go to [api.slack.com/apps](https://api.slack.com/apps) → **Create New App** → **From scratch**
2. Name it (`Hitler Dev` or `Hitler`) and select the target workspace

### Enable Socket Mode

1. Go to **Settings → Socket Mode** → Enable
2. Generate an **App-Level Token** with `connections:write` scope
3. Copy the token (`xapp-1-...`)

### Add Bot Scopes

Go to **OAuth & Permissions → Bot Token Scopes** and add all of the following:

| Scope               | Purpose                                         |
| ------------------- | ----------------------------------------------- |
| `app_mentions:read` | View messages that directly mention the bot     |
| `channels:history`  | View messages in public channels the bot is in  |
| `chat:write`        | Send messages as the bot                        |
| `commands`          | Add slash commands (e.g. `/hitler`)             |
| `groups:history`    | View messages in private channels the bot is in |
| `im:history`        | View messages in direct messages with the bot   |
| `im:read`           | View basic info about DMs the bot is in         |
| `im:write`          | Start direct messages with people               |
| `mpim:history`      | View messages in group DMs the bot is in        |
| `team:read`         | View workspace name, email domain, and icon     |
| `users:read`        | View people in the workspace                    |

### Subscribe to Events

Go to **Event Subscriptions → Subscribe to bot events** and add:

| Event Name         | Description                                             | Required Scope      |
| ------------------ | ------------------------------------------------------- | ------------------- |
| `app_home_opened`  | User opened the bot's App Home tab                      | —                   |
| `app_mention`      | Someone mentions the bot in a channel                   | `app_mentions:read` |
| `message.channels` | A message was posted in a public channel the bot is in  | `channels:history`  |
| `message.groups`   | A message was posted in a private channel the bot is in | `groups:history`    |
| `message.im`       | A message was posted in a DM with the bot               | `im:history`        |
| `message.mpim`     | A message was posted in a group DM the bot is in        | `mpim:history`      |

### Set OAuth Redirect URL

Go to **OAuth & Permissions → Redirect URLs** and add:

* **Dev app**: `http://localhost:3000/api/auth/slack/callback`
* **Prod app**: `https://api.mako.devinagiffy.xyz/api/auth/slack/callback`

### Install to Workspace

Click **Install to Workspace** and authorize. Copy the **Bot User OAuth Token** (`xoxb-...`).

### Configure Environment Variables

**Development** (`.env` in project root):

```bash theme={null}
SLACK_APP_TOKEN=xapp-1-your-dev-app-token
SLACK_SIGNING_SECRET=your-dev-signing-secret
SLACK_CLIENT_ID=your-dev-client-id
SLACK_CLIENT_SECRET=your-dev-client-secret
```

**Production** (`.env` on your VPS):

```bash theme={null}
SLACK_APP_TOKEN=xapp-1-your-prod-app-token
SLACK_SIGNING_SECRET=your-prod-signing-secret
SLACK_CLIENT_ID=your-prod-client-id
SLACK_CLIENT_SECRET=your-prod-client-secret
```

<Info>
  The Hitler Slack bot uses **Socket Mode** (WebSocket connection), so you don't need ngrok or a
  public URL for local development.
</Info>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Bot not responding">
    1. Ensure the bot is installed (check Settings → Integrations)
    2. Invite the bot to the channel: `/invite @Hitler`
    3. Check you're mentioning correctly: `@Hitler` (not `@hitler`)
  </Accordion>

  <Accordion title="Bot won't start locally">
    **"You must provide an appToken"** error:

    * Set `SLACK_APP_TOKEN` in your `.env` (starts with `xapp-`)
    * Generate one in Slack App → Socket Mode → App-Level Tokens
    * Ensure Socket Mode is enabled

    **"Invalid token"** error:

    * Verify `SLACK_BOT_TOKEN` is correct (starts with `xoxb-`)
    * Re-install the app to your workspace if needed
  </Accordion>

  <Accordion title="'Add to Slack' shows error">
    * Verify you have Slack admin permissions - Check your browser allows popups from Slack - Try in
      an incognito window
  </Accordion>

  <Accordion title="Users can't sign in with Slack">
    * Confirm the workspace has Hitler installed - Verify the user's email matches their Slack profile
    * Check the user belongs to the correct Slack workspace
  </Accordion>

  <Accordion title="Messages not being received">
    * For local dev: Check that Socket Mode is enabled and `SLACK_APP_TOKEN` is set
    * Verify Event Subscriptions has `message.im` and `app_mention` subscribed
    * Check Hitler server status at [status.hitler.app](https://status.hitler.app)
    * Contact support if issues persist
  </Accordion>
</AccordionGroup>

## Disconnecting Slack

To remove the Slack integration:

1. Go to **Settings → Integrations**
2. Click the **Disconnect** button on the Slack card
3. Confirm disconnection

<Warning>
  Disconnecting will:

  * Stop all bot functionality
  * Disable "Sign in with Slack"
  * Remove stored bot tokens

  User accounts will remain, but Slack-based features will stop working.
</Warning>

## Security

### Data Access

Hitler only accesses:

* Messages in DMs with the bot
* Messages where the bot is mentioned
* User profile information (name, email)

We do **not** access:

* Private channels where bot isn't invited
* DMs between users
* Message history beyond bot interactions

### Token Storage

Slack tokens are:

* Encrypted with AES-256-GCM
* Stored in Cloudflare KV (not in database)
* Scoped to your organization
* Rotatable via re-authentication

### Audit Logging

All Slack-related actions are logged:

* Bot installations/removals
* User sign-ins via Slack
* Permission changes