Connect Slack
Create the Slack app of your instance from its manifest, give its secrets to the Helm chart, and let workspace admins connect Slack.
Create one Slack app for your instance so that workspace admins can connect their Slack workspaces. Members then talk with Hephaestus in direct messages, and a workspace admin chooses the channels that Hephaestus reads. After this setup, a workspace admin connects Slack in the web app, as Connect Slack and Outline to a workspace describes.
Before you start
- An installed instance that serves its host over HTTPS (Install on Kubernetes).
- A Slack account that can create apps in the Slack workspace that owns the app.
kubectlwith access to the release namespace, andjq.
The commands use the release namespace hephaestus and the release Secret hephaestus-app.
Replace these names if your release uses other names.
Create the Slack app
- Download
slack-app-manifest-template.yml. - Replace each
<host>in the file with the host of your instance. - Open api.slack.com/apps, and select Create New App.
- Select From a manifest, then the Slack workspace that owns the app.
- Paste the manifest, and create the app.
- Under Basic Information → Display Information, upload
slack-app-icon-512.pngas the app icon. Slack rounds the corners, so do not round the image. - Under Basic Information → App Credentials, copy the Client ID, the Client Secret, and the Signing Secret.
The manifest sets these addresses:
| Manifest field | Address | Use |
|---|---|---|
oauth_config.redirect_urls | https://<host>/api/oauth/callback/slack | A workspace admin installs the app in a Slack workspace. |
oauth_config.redirect_urls | https://<host>/api/login/oauth2/code/slack | A member links their Slack account. |
settings.event_subscriptions.request_url | https://<host>/webhooks/slack | Slack sends messages and app events. |
settings.interactivity.request_url | https://<host>/webhooks/slack/interactivity | Slack sends the buttons that members press in the App Home tab. |
Set the Helm values and Secret keys
-
Type the client secret, then the signing secret. The shell does not show them:
read -rs SLACK_CLIENT_SECRET && export SLACK_CLIENT_SECRET read -rs SLACK_SIGNING_SECRET && export SLACK_SIGNING_SECRET -
Add both secrets to the release Secret:
jq -n --arg client "$SLACK_CLIENT_SECRET" --arg signing "$SLACK_SIGNING_SECRET" \ '{stringData: {HEPHAESTUS_INTEGRATION_SLACK_CLIENT_SECRET: $client, HEPHAESTUS_INTEGRATION_SLACK_SIGNING_SECRET: $signing}}' | kubectl -n hephaestus patch secret hephaestus-app --type merge --patch-file /dev/stdin -
Add Slack to
site.yaml:config: slack: enabled: true clientId: "1234567890.1234567890123"With
config.slack.enabled, a server withoutHEPHAESTUS_INTEGRATION_SLACK_SIGNING_SECRETdoes not start. While it isfalse, the Slack page of each workspace says that Slack is not enabled on this instance. -
Apply
site.yaml. On a cluster, run thehelm upgradecommand of Install again. On one host, run the installer again (Run the installer).
At its next start, the server also creates the Slack login provider if it does not exist. Members use it only to link their Slack account, and it never shows on the sign-in page. After that, the server ignores the client ID and secret of the chart for account linking. Slack secrets describes how to replace each secret.
Check that it worked
- In a workspace, open Administration → Integrations. The sidebar lists Slack.
- Open Slack, and select Connect Slack workspace.
- Allow the app in Slack. Slack returns you to Hephaestus. The Slack page shows Connected.
- In Slack, send the app a direct message. Hephaestus answers when the member linked their Slack account and the workspace has a ready Ask Hephaestus model (Assign models).
Undo
- In each workspace with a Slack connection, select Disconnect Slack if its Slack data must be erased. A connection cannot disconnect while Slack is off for the instance.
- Set
config.slack.enabledtofalseinsite.yaml. - Apply
site.yaml. - Delete the app on api.slack.com/apps if no other instance uses it.
What the app can read
The manifest asks for these bot scopes, and Hephaestus uses no other scope:
| Scope | Use |
|---|---|
chat:write | Answers in direct messages, weekly digest notes, and channel announcements |
im:history | Direct messages with their edits and deletions |
channels:history, groups:history | Messages in the public and private channels that a workspace admin activates |
channels:read, groups:read | The channel list for the channel picker, and channel names |
channels:join | A workspace admin adds a public channel from the picker. |
users:read | The match of a Slack user to a workspace member |
Account linking uses the user scopes openid, profile and email.
Hephaestus reads no reactions.
When a later release needs another scope, its release notes say so. Then apply the new manifest to the app, and a workspace admin selects Reconnect Slack in each workspace. Until then, the Slack page of the workspace shows Permissions missing and names each missing scope.
What the app says about itself
The manifest describes Hephaestus as an AI system.
Slack shows the app's description and agent description before a person writes to the app.
An app made from an earlier manifest can still call Hephaestus an AI assistant.
To update it, copy display_information.description and features.agent_view.agent_description from the current manifest into the app settings.
A description change needs no new scope and no reinstall.