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

# Slack

> Push Shoal intelligence alerts to Slack channels with a bot that supports real-time events and slash commands

Connect Shoal to Slack for real-time radar and signal alerts in your team channels. The bot polls the Shoal API every 60 seconds and posts formatted intelligence cards, plus supports slash commands for on-demand queries.

## What You Get

* **Real-time alerts** — New radar and signal events posted as they arrive
* **Rich formatting** — Organization name, category tags, summary, source links
* **Slash commands** — `/shoal brief <org>`, `/shoal radar`, `/shoal signal`, `/shoal usage`
* **Socket Mode** — No public URL required, runs behind your firewall

<Frame>
  <img src="https://mintcdn.com/shoalresearch/kPKbliFQYCFjQvCO/images/slack-integration.svg?fit=max&auto=format&n=kPKbliFQYCFjQvCO&q=85&s=6febacd9eaf5aa78f78d8452024bea81" alt="Shoal Intelligence Slack integration showing radar and signal event cards" width="1512" height="947" data-path="images/slack-integration.svg" />
</Frame>

## Setup

### 1. Create a Slack App

Go to [api.slack.com/apps](https://api.slack.com/apps) and create a new app for your workspace.

**Required Bot Token Scopes** (OAuth & Permissions):

* `chat:write` — Post messages to channels
* `commands` — Register slash commands

**Enable Socket Mode** (Settings > Socket Mode):

* Toggle on, generate an app-level token with `connections:write` scope
* This gives you an `xapp-` token

**Create Slash Command** (Slash Commands > Create New):

* Command: `/shoal`
* Description: `Shoal Intelligence — briefs, radar, signal`
* Leave Request URL blank (Socket Mode handles routing)

**Install the app** to your workspace and copy the Bot User OAuth Token (`xoxb-...`).

### 2. Configure Environment

```bash theme={null}
# .env
SHOAL_API_KEY=your_shoal_api_key
SLACK_APP_TOKEN=xapp-1-...          # Socket Mode app-level token
SLACK_BOT_TOKEN=xoxb-...            # Bot User OAuth Token
SLACK_CHANNEL_ID=C0ABC123DEF        # Channel for auto-posted alerts
```

### 3. Install and Run

```bash theme={null}
git clone https://github.com/shoalresearch/shoal-slack-bot.git
cd shoal-slack-bot
npm install
npm start
```

The bot connects via Socket Mode and starts polling immediately.

## Event Card Format

Each event is posted as a standalone message with this layout:

```
:handshake: Ripple  `PARTNERSHIP`  `ALLIANCE`

Bitkub and Ripple launch RLUSD stablecoin in Thailand
Bitkub Exchange partners with Ripple to launch RLUSD, a
USD-pegged stablecoin, in Thailand to enable cross-border
payments, remittances, and DeFi activities.

`RIPPLE`  `BITKUB`  ·  1 hour ago  ·  :link: Source
```

**Top line:** Organization name (bold) + category and subcategory as tag pills

**Body:** Bold title + summary paragraph

**Footer:** Entity tags + relative timestamp + source link

Signal events use the :zap: prefix to stand out from radar events.

## Slash Commands

| Command                   | Description                                          |
| ------------------------- | ---------------------------------------------------- |
| `/shoal`                  | Show help and available commands                     |
| `/shoal brief <org>`      | 7-day intelligence brief for an organization         |
| `/shoal radar [category]` | Latest radar events, optionally filtered by category |
| `/shoal signal`           | Latest signal intelligence events                    |
| `/shoal usage`            | Your API usage stats (today, week, month)            |

### Example: On-Demand Brief

```
/shoal brief Ethereum
```

Returns a formatted card with the last 7 days of radar and signal events for Ethereum Foundation, including signal scores.

## Architecture

```
┌─────────────┐     poll every 60s      ┌──────────────┐
│  Slack Bot   │ ◄─────────────────────► │  Shoal API   │
│ (Socket Mode)│                         │ api.shoal.xyz│
└──────┬───────┘                         └──────────────┘
       │
       │ chat.postMessage
       ▼
┌──────────────┐
│ #your-channel│
└──────────────┘
```

The bot runs as a long-lived Node.js process. It maintains a local state file (`.last_poll.json`) to track which events have been posted, preventing duplicates across restarts.

## Source Code

Full source: [`slack_bot/bot.js`](https://github.com/shoalresearch/shoal-slack-bot)

The bot is \~200 lines of JavaScript using `@slack/bolt` for Socket Mode and the Shoal REST API for intelligence data.