Slack App

Overview

The Hi Energy AI Slack integration brings search, slash commands, and Dex (MCP-backed answers) into your workspace. A single Slack app handles workspace installation (bot + scopes in a channel), interactive events (mentions, messages, shortcuts), and optional per-user Slack sign-in so accounts can store a Slack user id for routing and invites.

Two different OAuth flows

Install app to workspace — adds the bot with bot scopes; uses GET /slack/install and returns to /slack/oauth/callback.
Sign in with Slack (user) — links a person’s Slack identity to their Hi Energy AI user record; separate authorize URL and same callback host with user scopes.

Add bot to Slack workspace Sign in with Slack

Workspace install

From the web app, users start install at https://app.hienergy.ai/slack/install (same path as the footer “Add to Slack” link). That action stores an install flow marker in the session and redirects the browser to Slack’s oauth.v2.authorize URL with the public install client id when configured.

For Slack Marketplace or App Directory “direct install URL”, use the HTTPS URL on your deployed host with the same path, for example https://app.hienergy.ai/slack/install. Slack must be able to reach it over HTTPS (localhost URLs are rejected in directory validation).

Add bot to Slack workspace

Maintainer reference for manifest generation and slack:manifest:* tasks lives in the repository at config/slack/README.md.

Identity & linking

When someone completes Slack’s user OAuth, Hi Energy AI stores a Slack user id on the users record (when Slack returns an id and email match). That id is used for DM routing, contact flows, and admin visibility — it is separate from the bot token used to post into channels.

Sign in with Slack

Events, interactivity, and slash commands

Slack delivers Events API envelopes, interactivity (buttons, shortcuts), and slash commands to your configured request URL on this Rails app. The exact path is derived from the same base URL as the rest of the product (see generated manifest.yaml event_subscriptions.request_url and slash command URLs).

Surface	Role
App mentions, channel messages, DMs	Routed to the responder that can invoke Dex / MCP or return structured search results, depending on context.
Slash commands (`/hienergy`, `/dex`, …)	Same request URL family; each command is declared in the Slack app manifest and backed by Rails.
Shortcuts & modals	Interactivity URL matches the Events URL pattern in the shipped manifest.

Publisher channels versus DMs

Channels mapped to a publisher in the admin UI are treated as shared account context: Dex can answer about that publisher using the service configuration for the channel without requiring each participant to be individually linked for every question.

Direct messages to the bot are scoped to the Slack user when they are linked to a Hi Energy AI user, with invitations or prompts when no link exists yet.

Server configuration (operations)

Runtime configuration uses environment variables (set on the host, not committed). Typical names include:

SLACK_SIGNING_SECRET — verifies Slack request signatures for webhooks and interactivity.
SLACK_BOT_TOKEN or SLACK_API_TOKEN — must include a bot token whose prefix is xoxb- for chat.postMessage (welcome and admin test posts ignore user xoxp- and configuration xoxe- tokens).
SLACK_CLIENT_ID / SLACK_CLIENT_SECRET — OAuth for the primary Slack app.
SLACK_PUBLIC_INSTALL_CLIENT_ID (and secret when different) — the distributed app used by /slack/install when set.

Manifest updates use a separate configuration token (xoxe-) via SLACK_APP_CONFIGURATION_TOKEN; that token type is not valid for posting messages into channels.