NodeBB Slack Integration Plugin

A NodeBB plugin that integrates with Slack to send notifications about forum activities using the Slack Bot API.

Features

• Real-time notifications for:
  • New topics created (with full content)
  • Replies to topics (as threaded messages in Slack)
  • New user registrations
• Category-to-Channel Mapping (v1.4.2):
  • Map specific NodeBB categories to different Slack channels
  • Automatic Slack channel creation (optional)
  • Categories without mappings use the default channel
• Threaded conversations: Replies in NodeBB appear as threaded replies in Slack, maintaining conversation context
• Rich formatting: Posts are displayed with:
  • Topic title as header
  • Full post content with bold, italic, code, and more preserved
  • Author and category information
  • User avatars (with chat:write.customize scope)
  • "View Topic" button linking back to NodeBB
• Production-ready reliability (v1.2.0):
  • Encrypted credential storage (AES-256-GCM)
  • Rate limiting (1 message/second)
  • Message queue with retry logic
  • Circuit breaker pattern for fault tolerance
  • Message deduplication
  • Automatic thread cleanup on topic deletion
• Customizable settings:
  • Enable/disable integration
  • Configure Slack Bot Token (encrypted at rest)
  • Choose target channel
  • Choose which events to notify
• Test connection functionality to verify Slack integration

Installation

1. Copy this plugin to your NodeBB node_modules directory
2. Restart NodeBB
3. Go to Admin Panel → Extend → Plugins
4. Activate "Slack Integration"
5. Configure settings in Admin Panel → Plugins → Slack Integration

Configuration

Setting up Slack Bot

1. Go to https://api.slack.com/apps
2. Create a new app or select an existing one
3. Go to OAuth & Permissions
4. Add the chat:write bot token scope under Bot Token Scopes
5. Install the app to your workspace
6. Copy the Bot User OAuth Token (starts with xoxb-)
7. In your Slack workspace, invite the bot to your desired channel:

   /invite @YourBotName

Plugin Settings

• Enable Slack Integration: Turn on/off all notifications
• Slack Bot Token: Your Slack Bot User OAuth Token (required, starts with xoxb-)
• Channel: Channel to post messages to (required, e.g., #general or #notifications)

Notification Settings

Toggle which events should trigger Slack notifications:

• New Topics: Notify when a new topic is created
• Replies: Notify when someone replies to a topic
• New Users: Notify when a new user registers

Usage

1. Configure your Slack Bot Token in the admin panel
2. Set the channel where messages should be posted
3. Click "Test Connection" to verify the integration works
4. Enable the notifications you want
5. Save settings
6. All configured events will now be sent to Slack!

Technical Details

Slack API

This plugin uses the official Slack Web API (chat.postMessage) with a Bot Token for posting messages.

Required Scopes

• chat:write - Post messages to channels
• chat:write.customize - (Recommended) Customize username and avatar per message
• channels:manage - (Optional) Create channels automatically when they don't exist
• channels:join - (Optional) Join channels automatically

Hooks Used

• action:topic.post - Triggered when a new topic is created
• action:topic.reply - Triggered when someone replies to a topic
• action:user.create - Triggered when a new user registers
• action:topic.delete - Cleanup thread timestamps when topic is deleted
• action:topic.purge - Cleanup thread timestamps when topic is purged

Data Storage

Settings are stored in the NodeBB database under the key plugin:slack-integration:settings.

Requirements

• NodeBB v3.0.0 or higher
• Node.js 14.0.0 or higher
• Valid Slack Bot with chat:write scope (and optionally chat:write.customize)

Changelog

v1.4.2 (2025-10-02)

🎉 New Features:

• ✅ Category-to-Channel Mapping: Map specific NodeBB categories to different Slack channels
• ✅ Automatic Channel Creation: Optionally auto-create Slack channels when they don't exist (requires channels:manage and channels:join scopes)
• ✅ Admin UI improvements with dynamic category mapping interface
• ✅ Category mappings displayed and loaded correctly in admin panel

Bug Fixes:

• ✅ Fixed category mapping save/load functionality
• ✅ Fixed async loading of categories in admin UI

v1.2.0 (2025-10-02)

🎉 Major Production-Ready Update

Security & Reliability:

• ✅ Bot token encryption (AES-256-GCM) for secure storage
• ✅ Rate limiting (1 message/second) to prevent API throttling
• ✅ Message queue with retry logic (3 retries with exponential backoff)
• ✅ Circuit breaker pattern (auto-disables after 5 failures, recovers after 60s)
• ✅ Message deduplication (5-second window prevents duplicates)

Features:

• ✅ Enhanced text formatting support (bold, italic, code, links, lists, blockquotes)
• ✅ Improved avatar URL handling
• ✅ Modern Blocks API for user notifications
• ✅ Automatic thread timestamp cleanup on topic deletion
• ✅ Token validation on save

Bug Fixes:

• ✅ Fixed ordered list formatting in Slack messages
• ✅ Removed unused webhook/botName/botIcon settings

Documentation:

• 📚 Added PRODUCTION_IMPROVEMENTS.md - Complete guide to all improvements
• 📚 Added FORMATTING_FIXES.md - Text formatting testing guide
• 📚 Added AVATAR_FIX.md - Avatar display troubleshooting

See PRODUCTION_IMPROVEMENTS.md for detailed technical information.

v1.1.1 (Initial Release)

• Basic Slack Bot integration
• Threaded conversations
• New topic and reply notifications
• User registration notifications

Documentation

• Production Improvements - Detailed technical documentation
• Formatting Fixes - Text formatting guide and testing
• Avatar Setup - How to enable custom avatars

License

MIT