elizaos--eliza/plugins/plugin-slack

@elizaos/plugin-slack

Slack integration plugin for elizaOS agents with Socket Mode support.

Features

• Socket Mode: Real-time event handling via Slack Socket Mode
• Message Operations: Send, edit, delete, read messages
• Reactions: Add and remove emoji reactions
• Pins: Pin and unpin messages, list pinned items
• Channels: List channels, read channel history
• User Info: Get user profile information
• Threads: Full thread support with reply tracking
• Media: Handle file uploads and attachments
• Custom Emoji: List workspace custom emoji

Installation

npm install @elizaos/plugin-slack
# or
bun add @elizaos/plugin-slack

Configuration

Required Environment Variables

# Bot Token (starts with xoxb-)
SLACK_BOT_TOKEN=xoxb-your-bot-token

# App Token for Socket Mode (starts with xapp-)
SLACK_APP_TOKEN=xapp-your-app-token

Optional Environment Variables

# Signing Secret for request verification
SLACK_SIGNING_SECRET=your-signing-secret

# User Token for enhanced permissions (starts with xoxp-)
SLACK_USER_TOKEN=xoxp-your-user-token

# Comma-separated list of channel IDs to restrict bot to
SLACK_CHANNEL_IDS=C123456789,C987654321

# Ignore messages from other bots
SLACK_SHOULD_IGNORE_BOT_MESSAGES=false

# Only respond when mentioned
SLACK_SHOULD_RESPOND_ONLY_TO_MENTIONS=false

Slack App Setup

1. Create a new Slack App at https://api.slack.com/apps

2. Enable Socket Mode in your app settings

3. Generate an App-Level Token with connections:write scope

4. Add the following Bot Token Scopes:

   • channels:history - Read messages in public channels
   • channels:read - View basic channel information
   • chat:write - Send messages
   • emoji:read - View custom emoji
   • files:read - View files
   • groups:history - Read messages in private channels
   • groups:read - View basic private channel information
   • im:history - Read direct messages
   • im:read - View basic direct message information
   • mpim:history - Read group direct messages
   • mpim:read - View basic group direct message information
   • pins:read - View pinned items
   • pins:write - Add and remove pinned items
   • reactions:read - View reactions
   • reactions:write - Add and remove reactions
   • team:read - View workspace information
   • users:read - View basic user information
   • users:read.email - View user email addresses

5. Enable Events and subscribe to:

   • message.channels - Messages in public channels
   • message.groups - Messages in private channels
   • message.im - Direct messages
   • message.mpim - Group direct messages
   • app_mention - When the app is mentioned
   • member_joined_channel - When a user joins a channel
   • member_left_channel - When a user leaves a channel
   • reaction_added - When a reaction is added
   • reaction_removed - When a reaction is removed

6. Install the app to your workspace

Usage

Add to your agent configuration

import slackPlugin from "@elizaos/plugin-slack";

const agent = {
  // ... other configuration
  plugins: [slackPlugin],
};

Character file configuration

{
  "name": "MyAgent",
  "settings": {
    "slack": {
      "shouldIgnoreBotMessages": true,
      "shouldRespondOnlyToMentions": false
    }
  }
}

Connector capabilities

This plugin registers no elizaOS actions. Slack messaging is handled via the MessageConnector interface. The registered connector exposes these capabilities: send_message, read_messages, search_messages, resolve_targets, list_rooms, list_servers, chat_context, user_context, react_message, edit_message, delete_message, pin_message, get_user.

Events

The plugin emits the following events:

• SLACK_MESSAGE_RECEIVED - When a message is received
• SLACK_MESSAGE_SENT - When a message is sent
• SLACK_REACTION_ADDED - When a reaction is added
• SLACK_REACTION_REMOVED - When a reaction is removed
• SLACK_APP_MENTION - When the bot is mentioned
• SLACK_MEMBER_JOINED_CHANNEL - When a member joins a channel
• SLACK_MEMBER_LEFT_CHANNEL - When a member leaves a channel
• SLACK_FILE_SHARED - When a file is shared

API Reference

SlackService

The main service class providing direct access to Slack functionality:

import { SlackService, SLACK_SERVICE_NAME } from "@elizaos/plugin-slack";

// Get service from runtime
const slackService = runtime.getService(SLACK_SERVICE_NAME) as SlackService;

// Send a message
await slackService.sendMessage(channelId, "Hello!", { threadTs: "..." });

// Add a reaction
await slackService.sendReaction(channelId, messageTs, "thumbsup");

// Get user info
const user = await slackService.getUser(userId);

// List channels
const channels = await slackService.listChannels();

Troubleshooting

Bot not responding to messages

1. Verify your SLACK_BOT_TOKEN and SLACK_APP_TOKEN are correct
2. Check that Socket Mode is enabled in your Slack app
3. Ensure the bot has been invited to the channel
4. Check if SLACK_SHOULD_RESPOND_ONLY_TO_MENTIONS is enabled

Permission errors

1. Verify the bot has all required OAuth scopes
2. Reinstall the app to your workspace after adding new scopes
3. Check if the channel is private and the bot is a member

Socket Mode connection issues

1. Verify your SLACK_APP_TOKEN starts with xapp-
2. Check that the app-level token has connections:write scope
3. Ensure only one instance of the bot is running per token