YapHub

Appearance

Slack App Setup Guide ​

Complete guide for setting up the Yappa Knowledge Hub Slack app.

Prerequisites ​

Quick Setup with Manifest ​

Step 1: Create the Slack App ​

  1. Go to https://api.slack.com/apps
  2. Click "Create New App"
  3. Select "From an app manifest"
  4. Choose your workspace
  5. Copy the contents of slack-app-manifest.yaml from this repository
  6. Paste it into the YAML tab
  7. Click "Next" and review the configuration
  8. Click "Create"

Step 2: Configure Socket Mode ​

Socket Mode allows your app to receive events without exposing a public URL.

  1. In your app settings, go to "Socket Mode" in the left sidebar
  2. Toggle "Enable Socket Mode" to ON
  3. Click "Generate" to create an app-level token
  4. Name it "Socket Mode Token" and add the connections:write scope
  5. Click "Generate"
  6. Copy the token (starts with xapp-) and save it as SLACK_APP_TOKEN in your .env file

Step 3: Install the App to Your Workspace ​

  1. In the left sidebar, click "Install App"
  2. Click "Install to Workspace"
  3. Review the permissions and click "Allow"
  4. Copy the "Bot User OAuth Token" (starts with xoxb-)
  5. Save it as SLACK_BOT_TOKEN in your .env file

Step 4: Get Your Signing Secret ​

  1. In the left sidebar, click "Basic Information"
  2. Scroll down to "App Credentials"
  3. Copy the "Signing Secret"
  4. Save it as SLACK_SIGNING_SECRET in your .env file

Step 5: Configure Environment Variables ​

Create or update your .env file in the backend directory:

bash
# Slack Configuration
SLACK_BOT_TOKEN=xoxb-your-bot-token-here
SLACK_SIGNING_SECRET=your-signing-secret-here
SLACK_APP_TOKEN=xapp-your-app-token-here

# Server Configuration
PORT=3000

Step 6: Start the Application ​

bash
cd /path/to/yappa-knowledge-hub
npm install
npm start

You should see:

[Yappa Kennishub] Bot is actief op poort 3000
[Yappa Kennishub] Socket Mode: ingeschakeld

Manual Setup (Without Manifest) ​

If you prefer to configure the app manually or need to modify an existing app:

OAuth & Permissions ​

Navigate to "OAuth & Permissions" and add these Bot Token Scopes:

Chat & Messaging:

  • chat:write - Send messages as the bot
  • chat:write.public - Send messages to channels without joining

Commands:

  • commands - Add slash commands

Reactions:

  • reactions:read - View emoji reactions

Files:

  • files:read - View files shared in channels

Channels & Conversations:

  • channels:history - View messages in public channels
  • channels:read - View basic channel information
  • groups:history - View messages in private channels
  • groups:read - View basic private channel information
  • im:history - View messages in direct messages
  • im:read - View basic direct message information
  • mpim:history - View messages in group direct messages
  • mpim:read - View basic group direct message information

Users:

  • users:read - View people in the workspace
  • users:read.email - View email addresses of people

App Home:

  • app_mentions:read - View messages that mention the app

Slash Commands ​

Navigate to "Slash Commands" and create:

Command: /knowledge

  • Request URL: https://your-domain.com/slack/events (not needed for Socket Mode)
  • Short Description: Manage and search the Knowledge Hub
  • Usage Hint: [dashboard|add|search <query>|help]
  • Escape channels, users, and links: Unchecked

Interactivity & Shortcuts ​

Navigate to "Interactivity & Shortcuts":

  1. Toggle "Interactivity" to ON
  2. Request URL: https://your-domain.com/slack/events (not needed for Socket Mode)

Create Message Shortcut:

  • Name: Save to Knowledge Hub
  • Short Description: Save this message to the Knowledge Hub
  • Callback ID: save_to_knowledge

Create Global Shortcut:

  • Name: Quick Add Knowledge
  • Short Description: Quickly add new knowledge to the hub
  • Callback ID: quick_add_knowledge

Event Subscriptions ​

Navigate to "Event Subscriptions":

  1. Toggle "Enable Events" to ON
  2. Request URL: https://your-domain.com/slack/events (not needed for Socket Mode)

Subscribe to Bot Events:

  • message.channels - Messages in public channels
  • message.groups - Messages in private channels
  • message.im - Direct messages
  • message.mpim - Group direct messages
  • app_home_opened - User opens App Home
  • file_shared - File is shared
  • reaction_added - Emoji reaction is added
  • app_mention - App is mentioned

App Home ​

Navigate to "App Home":

  1. Home Tab: Toggle ON
  2. Messages Tab: Toggle OFF
  3. Edit the bot display name to "Yappa Knowledge Hub"

Feature Configuration ​

Slash Command Usage ​

The /knowledge command supports multiple subcommands:

/knowledge                     Open the dashboard
/knowledge dashboard           Open the dashboard
/knowledge add                 Open add knowledge modal
/knowledge search <query>      Search the knowledge base
/knowledge help                Show help message

Message Shortcuts ​

Save to Knowledge Hub:

  1. Hover over any message
  2. Click the three dots (More actions)
  3. Select "Save to Knowledge Hub"
  4. Fill in the modal with title, category, target groups, and tags
  5. Click "Save"

Global Shortcuts ​

Quick Add Knowledge:

  1. Click the lightning bolt icon in the message input area
  2. Select "Quick Add Knowledge"
  3. Fill in the form with title, content, category, URL (optional), and tags
  4. Click "Add"

Emoji-Based Capture ​

React to any message with one of these emojis to trigger a save prompt:

  • 🧠 (brain)
  • 💡 (bulb)
  • 🔖 (bookmark)
  • 📚 (books)

The bot will send you an ephemeral message with a button to save the message.

URL Detection ​

When a URL is posted in a channel where the bot is present:

  1. The bot automatically scrapes metadata (title, description, image)
  2. Sends an ephemeral message to the user who posted it
  3. Offers to save the URL to the knowledge base with pre-filled information

File Sharing ​

When a file is shared in a channel:

  1. The bot detects the file
  2. Sends an ephemeral message to the user
  3. Offers to save file information to the knowledge base

App Home ​

The App Home tab provides:

  • Welcome message and quick action buttons
  • Statistics (total items and categories)
  • Browse by thematic list
  • Recently added items
  • Tips for using the app

To access:

  1. Click on the app name in the Slack sidebar
  2. Select the "Home" tab

Troubleshooting ​

Bot Not Responding to Commands ​

Check:

  • Bot is running (npm start shows no errors)
  • Socket Mode is enabled
  • SLACK_APP_TOKEN is correctly set in .env
  • App is installed to the workspace

Solution:

bash
# Restart the bot
npm start

Events Not Being Received ​

Check:

  • Socket Mode is enabled in app settings
  • All required event subscriptions are added
  • Bot has necessary scopes

Solution:

  1. Go to "Event Subscriptions" in app settings
  2. Verify all events are listed under "Subscribe to bot events"
  3. Reinstall the app if scopes were added after installation

Shortcuts Not Appearing ​

Check:

  • Shortcuts are created with correct callback IDs
  • App is reinstalled after adding shortcuts

Solution:

  1. Go to "Interactivity & Shortcuts"
  2. Verify shortcuts exist with callback IDs:
    • save_to_knowledge (message shortcut)
    • quick_add_knowledge (global shortcut)
  3. Reinstall the app to workspace

Check:

  • Trigger ID is valid (expires after 3 seconds)
  • Modal payload is valid JSON
  • No network errors in console

Solution:

  • Check application logs for errors
  • Verify modal structure matches Slack's Block Kit format

Emoji Reactions Not Triggering ​

Check:

  • reaction_added event is subscribed
  • reactions:read scope is granted
  • Reaction is one of: brain, bulb, bookmark, books

Solution:

  1. Verify event subscription in app settings
  2. Check bot logs for reaction events
  3. Ensure bot is in the channel (or use public channels)

URL Detection Not Working ​

Check:

  • message.channels (and other message events) are subscribed
  • Bot is in the channel or has chat:write.public scope
  • URL is valid (starts with http:// or https://)

Solution:

  • Add bot to the channel: /invite @Yappa Knowledge Hub
  • Check logs for URL detection errors
  • Verify URL scraper service is working

File Sharing Not Detected ​

Check:

  • file_shared event is subscribed
  • files:read scope is granted
  • Bot is in the channel where file was shared

Solution:

  1. Add file_shared to event subscriptions
  2. Grant files:read scope
  3. Reinstall app
  4. Invite bot to channel

App Home Not Loading ​

Check:

  • app_home_opened event is subscribed
  • Home tab is enabled in App Home settings
  • No errors in application logs

Solution:

  1. Enable Home Tab in "App Home" settings
  2. Verify app_home_opened event subscription
  3. Check logs when opening App Home

Socket Mode Connection Issues ​

Check:

  • SLACK_APP_TOKEN is correct and starts with xapp-
  • Token has connections:write scope
  • No firewall blocking WebSocket connections

Solution:

bash
# Verify token in .env
cat .env | grep SLACK_APP_TOKEN

# Check for connection errors in logs
npm start

Permission Errors ​

Check:

  • All required scopes are granted
  • App was reinstalled after adding new scopes

Solution:

  1. Go to "OAuth & Permissions"
  2. Verify all scopes from the list above are present
  3. Click "Reinstall App" if scopes were added
  4. Update SLACK_BOT_TOKEN if it changed

Testing the App ​

Test Slash Command ​

/knowledge help

Expected: Help message appears

Test Message Shortcut ​

  1. Post a test message
  2. Click three dots "Save to Knowledge Hub" Expected: Modal opens with save form

Test Global Shortcut ​

  1. Click lightning bolt in message input
  2. Select "Quick Add Knowledge" Expected: Modal opens with add form

Test Emoji Reaction ​

  1. Post a test message
  2. React with 🧠 Expected: Ephemeral message with save button

Test URL Detection ​

  1. Post a message with a URL: https://example.com Expected: Ephemeral message with URL preview and save button

Test App Home ​

  1. Click app name in sidebar
  2. Open "Home" tab Expected: Dashboard with stats and recent items

Security Best Practices ​

  1. Never commit tokens to version control

    • Add .env to .gitignore
    • Use environment variables for all secrets

  2. Rotate tokens regularly

    • Regenerate tokens every 90 days
    • Update .env file with new tokens

  3. Limit scope permissions

    • Only request scopes your app needs
    • Review permissions periodically

  4. Use Socket Mode for development

    • No need to expose public URLs
    • Easier local development

  5. Monitor app usage

    • Check Slack app analytics
    • Review error logs regularly

Production Deployment ​

For production deployment without Socket Mode:

  1. Set up a public HTTPS endpoint

    • Use a service like Heroku, AWS, or DigitalOcean
    • Ensure SSL/TLS is properly configured

  2. Update Request URLs

    • Go to "Slash Commands" and update Request URL
    • Go to "Interactivity & Shortcuts" and update Request URL
    • Go to "Event Subscriptions" and update Request URL

  3. Disable Socket Mode

    • Toggle Socket Mode to OFF
    • Remove socketMode: true from app configuration
    • Remove SLACK_APP_TOKEN from environment

  4. Update app.js

    javascript
    const app = new App({
  token: process.env.SLACK_BOT_TOKEN,
  signingSecret: process.env.SLACK_SIGNING_SECRET,
  // Remove socketMode and appToken
});

  5. Set up process manager

    bash
    npm install -g pm2
pm2 start src/app.js --name yappa-knowledge-hub
pm2 save
pm2 startup

Support ​

For issues or questions:

  • Check the troubleshooting section above
  • Review Slack API documentation: https://api.slack.com/
  • Check application logs for error messages
  • Verify all configuration steps were completed

Additional Resources ​