Slack

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

Shoal Intelligence Slack integration showing radar and signal event cards

Setup

1. Create a Slack App

Go to 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

# .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

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 The bot is ~200 lines of JavaScript using @slack/bolt for Socket Mode and the Shoal REST API for intelligence data.

Overview

Claude

Developer Tools

Workflows

Payments

What You Get

Setup

1. Create a Slack App

2. Configure Environment

3. Install and Run

Event Card Format

Slash Commands

Example: On-Demand Brief

Architecture

Source Code

​What You Get

​Setup

​1. Create a Slack App

​2. Configure Environment

​3. Install and Run

​Event Card Format

​Slash Commands

​Example: On-Demand Brief

​Architecture

​Source Code

What You Get

Setup

1. Create a Slack App

2. Configure Environment

3. Install and Run

Event Card Format

Slash Commands

Example: On-Demand Brief

Architecture

Source Code