nodebb-plugin-slack-integration

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

• Copy this plugin to your NodeBB node_modules directory
• Restart NodeBB
• Go to Admin Panel → Extend → Plugins
• Activate "Slack Integration"
• Configure settings in Admin Panel → Plugins → Slack Integration

Configuration

Setting up Slack Bot

• Go to https://api.slack.com/apps
• Create a new app or select an existing one
• Go to OAuth & Permissions
• Add the chat:write bot token scope under Bot Token Scopes
• Install the app to your workspace
• Copy the Bot User OAuth Token (starts with xoxb-)
• 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

• Configure your Slack Bot Token in the admin panel
• Set the channel where messages should be posted
• Click "Test Connection" to verify the integration works
• Enable the notifications you want
• Save settings
• 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