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

# Slack integration

# Slack Integration Guide

This guide walks through setting up a Slack App for Svantic. The basic setup enables **outbound notifications** (alerts sent to a Slack channel). The optional advanced setup enables **bidirectional approval workflows** where users can approve or deny directly from Slack.

***

## Overview

The integration has two directions:

1. **Outbound** (required): Svantic → Slack — alert notifications and approval requests sent to a channel
2. **Inbound** (optional): Slack → Svantic — user clicks an interactive button, Slack POSTs the action back to Svantic

For alert notifications only, you need steps 1–5. For interactive approvals, continue with steps 6–7.

***

## Step 1: Create a Slack App

1. Go to [api.slack.com/apps](https://api.slack.com/apps) and click **Create New App**
2. Choose **From scratch**
3. Name it (e.g., "Svantic Alerts") and select your workspace
4. Click **Create App**

***

## Step 2: Configure Bot Scopes

Under **OAuth & Permissions → Scopes → Bot Token Scopes**, add:

| Scope         | Purpose                                                                   | Required?                      |
| ------------- | ------------------------------------------------------------------------- | ------------------------------ |
| `chat:write`  | Send messages to channels                                                 | Yes                            |
| `chat:update` | Update messages after approval (replace buttons with "Approved by @user") | Only for interactive approvals |

***

## Step 3: Install to Workspace

1. On the **OAuth & Permissions** page, scroll up and click **Install to Workspace**
2. Click **Allow** on the permission prompt
3. Copy the **Bot User OAuth Token** (`xoxb-...`) — this is your **bot token**

<Note>
  If you see **Request to Install** instead of **Install to Workspace**, your workspace has app approval enabled. Ask a workspace admin to approve the app, or temporarily disable approval in **Slack Admin → Manage Apps → Settings**.
</Note>

***

## Step 4: Get the Channel ID and Invite the Bot

1. In Slack, navigate to the channel where you want alerts delivered
2. Right-click the channel name → **View channel details**
3. Scroll to the bottom and copy the **Channel ID** (e.g., `C0123456789`)
4. In the channel, invite the bot:

```
/invite @Svantic Alerts
```

Replace "Svantic Alerts" with the name you gave your app in step 1. The bot must be a member of the channel to post messages.

To find your bot's exact name, go to [api.slack.com/apps](https://api.slack.com/apps) → select your app → **App Home** → look for the **Display Name (Bot)**.

***

## Step 5: Register the Slack Channel in Svantic

### Via the dashboard

1. Go to **Settings → Channels** → click **New Channel**
2. Select **Slack** as the type
3. Enter a name (e.g., "Engineering Slack")
4. Enter the **Bot Token** (`xoxb-...`)
5. Enter the **Channel ID** (`C0123456789`)
6. Click **Create**

You can also add a Slack channel directly on the **Alerts** page by clicking **Add channel** on any alert subscription.

### Via the API

```bash theme={null}
POST /internal/channels/new
{
  "type": "slack",
  "name": "Engineering alerts",
  "config": {
    "bot_token": "xoxb-your-bot-token",
    "channel_id": "C0123456789"
  }
}
```

| Config Field | Where to Get It                                                            |
| ------------ | -------------------------------------------------------------------------- |
| `bot_token`  | OAuth & Permissions → Bot User OAuth Token                                 |
| `channel_id` | Right-click the Slack channel → View channel details → copy the Channel ID |

***

## Step 5b: Test

Trigger a real event (e.g., register and deregister an agent) with the alert subscription enabled and the Slack channel linked. A notification should appear in the Slack channel.

***

## Step 6: Enable Interactivity (Optional)

This step is only needed if you want users to approve or deny requests directly from Slack buttons.

Under **Interactivity & Shortcuts** in your Slack App settings:

1. Toggle **Interactivity** to **On**
2. Set **Request URL** to: `https://your-gateway-domain/integrations/slack/interactive`
3. Click **Save Changes**

This tells Slack where to POST when a user clicks an interactive button in a Svantic notification.

***

## Step 7: Note Your Signing Secret (Optional)

Only needed for interactive approvals (step 6).

Under **Basic Information → App Credentials**, copy the **Signing Secret**.

Svantic uses this to verify that inbound requests actually come from Slack (and not an attacker spoofing Slack's payload format).

***

## How Approval Buttons Work

### Outbound (Svantic → Slack)

When a message enters `input-required`, the `SlackRenderer` inspects the A2UI spec:

* **Simple approval** (1 action field with 2-3 options): renders Slack buttons inline
* **Complex form** (multiple fields, sensitive data): renders a summary text with a "Complete in Dashboard" button

The Block Kit message includes metadata linking the buttons to the specific `message_id`.

### Inbound (Slack → Svantic)

When a user clicks a button:

1. Slack POSTs an interaction payload to `https://your-gateway/integrations/slack/interactive`
2. Svantic verifies the **Slack signing secret**:
   * Computes `v0:timestamp:body` → HMAC-SHA256 with signing secret
   * Compares to the `X-Slack-Signature` header
   * Rejects if timestamp is stale (>5 minutes)
3. Svantic extracts the action (`approve` or `deny`) and `message_id` from the payload
4. Svantic resolves the pending request (same logic as dashboard resolution)
5. Svantic POSTs back to Slack's `response_url` to update the original message:
   * Buttons are replaced with: "Approved by @john at 3:45 PM"
   * This prevents other users from clicking already-resolved buttons

### Race Conditions

If someone approves from the dashboard at the same moment someone clicks Approve in Slack, the first resolution wins. The second receives a `409 Conflict`, and Svantic updates the Slack message to reflect that it was already resolved.

***

## Limitations

| Limitation                                         | Workaround                                         |
| -------------------------------------------------- | -------------------------------------------------- |
| Complex forms can't render inline in Slack         | "Complete in Dashboard" button with deep link      |
| Sensitive fields (passwords) can't appear in Slack | Always routed to dashboard                         |
| Slack modals require additional scopes             | Currently uses buttons only; modal support planned |
| Bot must be in the channel                         | Invite the bot before testing                      |

***

## Security Considerations

* **Never expose the signing secret.** Store it in a secrets manager, not in source code.
* **The bot token is sensitive.** It allows posting to channels. Restrict it to the minimum required scopes.
* **Verify every inbound request.** The signing secret verification prevents attackers from forging Slack payloads.
* **Svantic never sends sensitive field values to Slack.** Credentials, passwords, and other sensitive A2UI fields are filtered out by the `SlackRenderer`.

***

## Troubleshooting

| Problem                                 | Check                                                                      |
| --------------------------------------- | -------------------------------------------------------------------------- |
| No message in Slack                     | Is the bot invited to the channel? Is the channel ID correct?              |
| Buttons don't work                      | Is the Interactivity Request URL correct? Is it HTTPS?                     |
| "Invalid signature" errors              | Is the signing secret in Svantic the same as in Slack's Basic Information? |
| "Already resolved" after clicking       | Someone else (dashboard/webhook) resolved it first                         |
| Test works but real notifications don't | Check the `event_filter` — does it include `input-required`?               |

***

## Further Reading

* [Notification Channels](./channels) — managing all channel types
* [Approvals Guide](./approvals) — the full approval workflow
* [Notifications & Approvals](../concepts/notifications) — the architectural model