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

# Slack Approval Bot

> Route AtlaSent hold and escalate decisions to a Slack thread for human approval using Block Kit interactive messages.

The AtlaSent Slack Approval Bot routes `hold` and `escalate` policy decisions to a designated Slack channel as interactive Block Kit messages. A reviewer can click **Approve** or **Deny** directly in Slack; AtlaSent resolves the decision and unblocks the waiting agent.

This integration uses two edge functions:

* `v1-slack-approval` — sends Block Kit messages and handles interactive callbacks with HMAC-SHA256 signature verification.
* `v1-slack-config` — handles org admin CRUD for the Slack connection.

***

## How it works

1. An agent calls `/v1/evaluate`. The policy returns `hold` or `escalate`.
2. AtlaSent calls `v1-slack-approval`, which posts a Block Kit message to the configured Slack channel.
3. The message shows the agent, the action class, the policy that triggered the hold, and two buttons: **Approve** and **Deny**.
4. A reviewer clicks a button. Slack sends an interactive callback to `v1-slack-approval`.
5. AtlaSent verifies the HMAC-SHA256 signature, records the decision, and resolves the pending request.
6. The waiting agent receives `approved` or `denied` and proceeds accordingly.

***

## Prerequisites

Before configuring the integration, have the following ready:

* **Slack workspace admin** access to create a new Slack app.
* The **channel ID** (or name) of the Slack channel where approval requests should be posted. The bot must be a member of this channel.
* A place to store secrets: the Slack **Bot Token** (`xoxb-…`) and **Signing Secret** will be stored encrypted in AtlaSent, but you will need them during setup.

***

## Setup

### Step 1: Create a Slack app

1. Go to [https://api.slack.com/apps](https://api.slack.com/apps) and click **Create New App**.
2. Choose **From scratch**.
3. Enter an app name (for example, `AtlaSent Approvals`) and select your workspace.
4. Click **Create App**.

### Step 2: Add OAuth scopes

In the app settings, go to **OAuth & Permissions → Scopes → Bot Token Scopes**. Add:

| Scope | Purpose |
| - | - |
| `chat:write` | Post messages to channels the bot is a member of. |
| `chat:write.public` | Post messages to public channels without joining. |

Click **Install to Workspace** and authorize the app. Copy the **Bot User OAuth Token** (`xoxb-…`) — you will need it in Step 5.

### Step 3: Enable Interactivity

In the app settings, go to **Interactivity & Shortcuts** and toggle **Interactivity** to **On**.

Set the **Request URL** to:

```
https://api.atlasent.io/functions/v1/v1-slack-approval
```

Self-hosted deployments use their own functions base instead, e.g. `https://<project-ref>.supabase.co/functions/v1/v1-slack-approval`.

Click **Save Changes**.

### Step 4: Copy the Signing Secret

In the app settings, go to **Basic Information → App Credentials**. Copy the **Signing Secret** — this is used to verify that interactive callbacks originate from Slack.

### Step 5: Configure in AtlaSent

1. In the AtlaSent Console, navigate to **Integrations → Slack** (`/integrations/slack`).
2. Enter:
   * **Bot Token**: the `xoxb-…` token from Step 2.
   * **Signing Secret**: the signing secret from Step 4.
   * **Channel**: the Slack channel where approval requests will be posted (e.g., `#atlasent-approvals`).
3. Click **Save**.

### Step 6: Test the connection

Click **Test Connection**. AtlaSent posts a test message to the configured channel:

```
🔔 AtlaSent connection test — this is not a real approval request.
```

If the message appears, the bot is configured correctly.

***

## The approval message

When a `hold` or `escalate` decision occurs, the bot posts a Block Kit message like this:

```
🔴 Approval required

Agent:        agent-001
Action:       ehr:write
Target:       patient-42 (production)
Policy:       21 CFR Part 11 v3
Decision:     hold
Requested at: 2026-05-25 14:03 UTC
Expires:      2026-05-25 14:33 UTC (30 min)

[ Approve ]  [ Deny ]
```

The request expires after the timeout configured in your policy (default: 30 minutes). After expiry, the buttons are disabled and the original call returns `timeout` to the caller.

***

## Resolving a request

A reviewer clicks **Approve** or **Deny**. AtlaSent:

1. Verifies the Slack HMAC-SHA256 signature (see [Security](#security)).
2. Records the reviewer's Slack user ID and display name in the audit chain entry.
3. Resolves the pending evaluation to `approved` or `denied`.
4. Updates the Slack message to show the outcome and the reviewer's name.

***

## Security

### HMAC-SHA256 signature verification

Every interactive callback from Slack is verified before being processed:

1. AtlaSent reads the `X-Slack-Request-Timestamp` and `X-Slack-Signature` headers.
2. It constructs the signing base string: `v0:<timestamp>:<raw request body>`.
3. It computes `HMAC-SHA256(signing_secret, base_string)` and compares with the signature in the header.
4. If the signatures do not match, the request is rejected with `403`.

### Replay protection

AtlaSent rejects any callback where the `X-Slack-Request-Timestamp` is more than **5 minutes** in the past. This prevents replay attacks where an attacker captures a valid callback and re-submits it later.

### Token storage

The Bot Token and Signing Secret are encrypted at rest using AES-256-GCM and are never returned in plaintext after the initial save. To rotate either value, click **Edit** in the Slack integration settings and enter the new value.

***

## Troubleshooting

| Symptom | Likely cause | Resolution |
| - | - | - |
| Test message doesn't appear | Bot is not in the channel | Invite the bot: `/invite @AtlaSent Approvals` in Slack |
| `invalid_auth` error | Bot Token is incorrect or expired | Reinstall the Slack app and copy the new Bot Token |
| Buttons do nothing | Interactivity Request URL is incorrect | Verify the URL in **Interactivity & Shortcuts** matches the `v1-slack-approval` function URL |
| `403` on callback | Signing Secret is wrong | Re-copy the Signing Secret from **Basic Information → App Credentials** |
| Request times out | Policy timeout is too short | Increase the hold timeout in the policy that triggers `hold`/`escalate` |

For persistent issues, contact [support@atlasent.io](mailto:support@atlasent.io) with your org ID and a copy of the Slack app's **Request URL logs** from the Slack developer dashboard.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.