Skip to main content
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

CommandDescription
/shoalShow 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 signalLatest signal intelligence events
/shoal usageYour 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.