Skip to content

Slack Integration ​

Alga integrates with Slack for alert notifications, bidirectional thread sync, and automated incident channels.

Configuration ​

Required ​

sh
SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_SIGNING_SECRET=your-signing-secret
SLACK_DEFAULT_CHANNEL=#alerts
  • SLACK_BOT_TOKEN — Bot user OAuth token (xoxb-...). Requires chat:write, channels:read, groups:read scopes.
  • SLACK_SIGNING_SECRET — Signs Events API requests for verification.
  • SLACK_DEFAULT_CHANNEL — Channel for unmatched alerts.

Optional ​

sh
SLACK_DISABLED=false
SLACK_CLIENT_ID=your-client-id
SLACK_CLIENT_SECRET=your-client-secret
SLACK_OAUTH_REDIRECT_URL=https://alga.yourdomain.com/api/v1/integrations/slack/oauth/callback
  • SLACK_DISABLED — Set to true to disable Slack delivery even when configured.
  • SLACK_CLIENT_ID — Slack app client ID (required for OAuth flows).
  • SLACK_CLIENT_SECRET — Slack app client secret (required for OAuth flows).
  • SLACK_OAUTH_REDIRECT_URL — OAuth redirect URL override for reverse-proxy setups.

OAuth (Multi-Workspace) ​

For multi-workspace support via OAuth 2.0, see Slack OAuth Setup.

App Setup ​

1. Create a Slack App ​

  1. Go to api.slack.com/apps → Create New App → From manifest
  2. Use the manifest from integrations/alga-slack-app/manifest.json in the Alga repository (or run integrations/alga-slack-app/setup.sh for guided setup)
  3. Install the app to your workspace
  4. Copy the Bot User OAuth Token to SLACK_BOT_TOKEN

2. Configure Event Subscriptions ​

  1. Enable Event Subscriptions in your app settings
  2. Set the request URL to http://your-alga-host:8080/webhooks/slack
  3. Subscribe to these events (matching integrations/alga-slack-app/manifest.json):
    • message.channels (public channel messages, for thread replies)
    • message.groups (private channel messages)

Only message events are handled server-side today (webhook/slack.go): thread replies sync into alert investigations and incident-channel messages become coordination messages. Other event types — including app_mentions — are acknowledged with 200 and ignored.

3. Configure Signing Secret ​

Copy the Signing Secret from Basic Information to SLACK_SIGNING_SECRET.

Bot Token Scopes ​

The Slack app manifest (integrations/alga-slack-app/manifest.json) requests exactly these bot scopes — configure no others:

ScopePurposeRequired
chat:writeSend messages to channelsYes
chat:write.customizePost as the bot's custom name/iconYes
chat:write.publicPost to public channels without joiningYes
channels:readRead channel informationYes
groups:readRead private channel informationYes
channels:manageCreate/archive incident channels (public)Yes
groups:manageCreate/archive incident channels (private)Yes
channels:historyRead public channel message contextYes
groups:historyRead private channel message contextYes
im:writeOpen direct messages (outbound DM delivery)Yes
mpim:writeOpen group DM conversationsYes

User scope: identity.basic (Slack sign-in only).

The manifest deliberately omits channels:join, commands, and app_mentions:read: there is no slash-command or mention handler server-side, and posting to public channels works via chat:write.public. The bot must be invited to private channels before it can post or read there. Inbound DM/MPIM messages are not received with these defaults — receiving them requires adding im:history, mpim:history, im:read, mpim:read scopes and message.im, message.mpim event subscriptions (flagged inside the manifest itself).

Channel Types ​

TypeFormatBot Behavior
Public channels#channel-nameCan post without joining with chat:write.public
Private channelsChannel ID (C0123ABCD)Bot must be invited first
Direct messagesUser ID (U0123ABCD)Bot can open DM with im:write scope

Message Formatting ​

Alga uses Slack Block Kit for rich alert messages with action buttons for acknowledge, resolve, and investigate. Acknowledging via the button does more than flip the alert's state — for alerts linked to incidents it also cancels any pending escalation (timeline entry escalation_cancelled), matching what a UI or API acknowledge does.

Threading Strategy ​

  1. Initial alert — Posted as thread parent
  2. Comments — Added as thread replies
  3. Investigation updates — Threaded under the alert
  4. Agent responses — Threaded for context preservation

User-Level Slack Binding ​

Individual users can link their personal Slack account to receive DM notifications. This is separate from the workspace-level bot integration and allows per-user notification delivery.

How It Works ​

  1. The user clicks Link Slack in their notification preferences
  2. Alga redirects to Slack's OAuth authorize URL
  3. After approval, Slack redirects back to Alga with an authorization code
  4. Alga exchanges the code for a user token and stores it
  5. Notifications configured for Slack DM are sent directly to the user

API Endpoints ​

Personal Slack linking uses two separate steps — start the link, then handle the return from Slack:

MethodPathAuthDescription
GET/api/v1/users/me/slack/authorizeSessionStep 1 — start personal Slack account link
GET/api/v1/users/me/slack/callbackSessionStep 2 — Slack returns here after approval
POST/api/v1/users/me/slack/disconnectSessionDisconnect personal Slack account

Workspace installation (shared bot for the whole team) uses its own pair — see Slack OAuth Setup:

MethodPathPermissionDescription
POST/api/v1/integrations/slack/oauth/authorizeintegrations:writeStep 1 — start install
GET/api/v1/integrations/slack/oauth/callback—Step 2 — Slack returns

Setup ​

  1. Ensure the Slack app is configured with im:write scope
  2. Add the user-level OAuth redirect URL to your Slack app's OAuth & Permissions → Redirect URLs
  3. Users can link their account from Profile → Notification Preferences → Slack DM

Slack Incident Channels ​

When enabled, Alga can automatically create dedicated Slack channels for incidents. Channels provide a focused space for incident coordination separate from general alert channels.

Configuration ​

Configure via system config (PUT /api/v1/system/config):

SettingValuesDescription
slack_incident_channels_enabledtrue/falseEnable auto-creation
slack_incident_channel_visibilitypublic/privateChannel visibility
slack_incident_channel_trigger_statusactive/detectedWhen to create the channel
slack_incident_channel_archive_on_closetrue/falseArchive on incident close

When slack_incident_channels_enabled is true and an incident reaches the trigger status, Alga automatically creates a channel named inc-{incident-number}-{slug} (for example inc-1234-database-outage) and posts the initial incident summary. If the name is already taken in Slack, Alga retries with -2, -3 suffixes.

API Endpoints ​

MethodPathPermissionDescription
POST/api/v1/incidents/{id}/slack-channelincidents:commandCreate Slack channel for incident
DELETE/api/v1/incidents/{id}/slack-channelincidents:commandUnlink Slack channel from incident

Channels are automatically archived when incidents are closed (if configured).

Channel Mapping ​

Route alerts to specific Slack channels using routing rules:

  1. Go to Routes in Alga
  2. Create a rule with conditions (provider, labels, severity)
  3. Set the destination to a Slack channel (#channel-name or channel ID)

Testing Your Integration ​

  1. Test connection: Go to Integrations → Slack → Test Connection
  2. Send test alert: Use the Create Alert dialog
  3. Verify delivery: Check the target Slack channel
  4. Test threading: Reply to the alert in Slack and verify it syncs to Alga

Bot Methods ​

The Slack integration exposes these internal methods for sending messages and managing conversations:

MethodDescription
PostMessagePost a message to a channel (Block Kit formatted)
PostThreadReplyPost a threaded reply under an existing message
OpenConversationOpen a DM conversation with a user
GetPermalinkGet a permanent link to a message
GetBotUserIDResolve the bot's own user ID
TestConnectionVerify the bot token is valid and the workspace is reachable

Slack Sign-In ​

Alga supports signing in with Slack as an authentication method (separate from the workspace-level bot integration and user-level OAuth binding):

MethodPathAuthDescription
POST/api/v1/auth/slackPublicAuthenticate a user via Slack identity

API Reference ​

Integration Endpoints ​

MethodPathPermissionDescription
GET/api/v1/integrations—Get integration status
PUT/api/v1/integrationsintegrations:writeUpdate integration settings
POST/api/v1/integrations/testintegrations:testTest Slack connection
POST/api/v1/integrations/slack/oauth/authorizeintegrations:writeInitiate OAuth flow
GET/api/v1/integrations/slack/oauth/callback—OAuth callback
POST/api/v1/integrations/slack/disconnectintegrations:writeDisconnect workspace

Webhook Endpoint ​

MethodPathAuthDescription
POST/webhooks/slackSigning secretSlack Events API webhook

Troubleshooting ​

Webhook Failures ​

  1. Verify webhook URL is publicly accessible
  2. Check SLACK_SIGNING_SECRET matches Slack app
  3. Test via Slack's Event Subscriptions verification tool
  4. Review Alga logs for signature validation errors

Permission Errors ​

  • Verify required scopes are granted (chat:write, channels:read)
  • Invite bot to private channels before routing alerts there
  • Use chat:write.public scope for easier public channel access

Rate Limiting ​

  • Slack has tier-based rate limits
  • Alga implements automatic retries with exponential backoff

Linking says "already linked to another user" ​

If personal Slack linking fails with a 409 ("already linked to another user"), that Slack account is already connected to a different Alga user. Ask that person to disconnect it first (Profile → Notification Preferences → Slack DM → Disconnect), then try linking again. One Slack account can only belong to one Alga user.

Disabling ​

Set SLACK_DISABLED=true to disable Slack delivery while keeping configuration intact. Useful for maintenance windows or testing other integrations.

Released under the MIT License.