Slack Integration

Overview

The Slack integration enables your elizaOS agent to participate in Slack workspaces, responding to messages, managing channels, and facilitating team collaboration. Your agent can send messages, react to content, pin important items, and more.

Prerequisites

Before setting up Slack integration, you need:

A Slack workspace where you have permission to install apps
Access to create a Slack app in the Slack API Dashboard

Setup

Create a Slack App

Go to Slack API: Your Apps

Click “Create New App”

Choose “From scratch”

Enter your app name and select the workspace

Click “Create App”

Configure OAuth Scopes

In your app settings, go to “OAuth & Permissions”

Scroll to “Scopes” section

Add the following Bot Token Scopes:

chat:write - Send messages
chat:write.public - Send messages to channels without joining
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 DMs
im:read - View DM information
mpim:history - View messages in group DMs
mpim:read - View group DM information
reactions:read - View reactions
reactions:write - Add reactions
users:read - View user information
emoji:read - View custom emoji

Add additional scopes based on your agent’s needs:

pins:write / pins:read - Manage pinned items
files:read / files:write - Handle file uploads
channels:manage - Create and archive channels

Enable Socket Mode

Go to “Socket Mode” in the sidebar

Toggle “Enable Socket Mode”

Give your token a name (e.g., “elizaOS Socket Token”)

Copy the app-level token (starts with xapp-)

Get Your Bot Token

Go to “OAuth & Permissions”

Click “Install to Workspace”

Review permissions and click “Allow”

Copy the “Bot User OAuth Token” (starts with xoxb-)

Set Environment Variables

Add the following to your .env file:

# Required
SLACK_BOT_TOKEN=xoxb-your-bot-token-here
SLACK_APP_TOKEN=xapp-your-app-token-here

Add the Slack Plugin

In your character configuration file, add the Slack plugin:

{
  "name": "YourAgent",
  "plugins": [
    "@elizaos/plugin-slack"
  ],
  "settings": {
    "channels": {
      "slack": {
        "enabled": true
      }
    }
  }
}

Configuration

Environment Variables

The Slack integration requires the following environment variables:

Variable	Required	Description
`SLACK_BOT_TOKEN`	Yes	Your bot user OAuth token (starts with `xoxb-`)
`SLACK_APP_TOKEN`	Yes	Your app-level token for Socket Mode (starts with `xapp-`)

Alternative names supported:

SLACK_TOKEN → SLACK_BOT_TOKEN
SLACK_API_TOKEN → SLACK_BOT_TOKEN

Character Settings

Configure Slack-specific behavior and action permissions:

{
  "settings": {
    "channels": {
      "slack": {
        "enabled": true,
        "actions": {
          "reactions": true,
          "messages": true,
          "pins": true,
          "memberInfo": true,
          "emojiList": true
        }
      }
    }
  }
}

All action groups are enabled by default.

Features

Message Management

Send, edit, and delete messages:

// Send a message
{
  "action": "sendMessage",
  "to": "channel:C12345678",
  "content": "Hello from elizaOS!"
}

// Send a DM
{
  "action": "sendMessage",
  "to": "user:U12345678",
  "content": "Private message"
}

// Edit a message
{
  "action": "editMessage",
  "channelId": "C12345678",
  "messageId": "1234567890.123456",
  "content": "Updated message content"
}

// Delete a message
{
  "action": "deleteMessage",
  "channelId": "C12345678",
  "messageId": "1234567890.123456"
}

Slack message IDs (timestamps) are in the format 1234567890.123456. You can get these from message context or by reading messages.

Read Messages

Fetch recent messages from channels:

{
  "action": "readMessages",
  "channelId": "C12345678",
  "limit": 20
}

Reactions

Add and view reactions:

// Add a reaction
{
  "action": "react",
  "channelId": "C12345678",
  "messageId": "1234567890.123456",
  "emoji": "✅"
}

// Or use emoji name
{
  "action": "react",
  "channelId": "C12345678",
  "messageId": "1234567890.123456",
  "emoji": ":white_check_mark:"
}

// List reactions on a message
{
  "action": "reactions",
  "channelId": "C12345678",
  "messageId": "1234567890.123456"
}

Pin Management

Pin important messages:

// Pin a message
{
  "action": "pinMessage",
  "channelId": "C12345678",
  "messageId": "1234567890.123456"
}

// Unpin a message
{
  "action": "unpinMessage",
  "channelId": "C12345678",
  "messageId": "1234567890.123456"
}

// List pinned items
{
  "action": "listPins",
  "channelId": "C12345678"
}

User Information

Retrieve member details:

{
  "action": "memberInfo",
  "userId": "U12345678"
}

Custom Emoji

List available custom emoji:

{
  "action": "emojiList"
}

Rich Formatting

Slack supports Block Kit for rich messages:

{
  "channel": "C12345678",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*Bold text* and _italic text_"
      }
    },
    {
      "type": "divider"
    },
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "Button example:"
      },
      "accessory": {
        "type": "button",
        "text": {
          "type": "plain_text",
          "text": "Click Me"
        },
        "action_id": "button_click"
      }
    }
  ]
}

Thread Replies

Reply in threads to keep conversations organized:

{
  "channel": "C12345678",
  "text": "Thread reply",
  "thread_ts": "1234567890.123456" // Parent message timestamp
}

Message Context

Your agent receives context with each message including:

slack message id - The message timestamp for actions
channel - The channel ID where the message was sent
User information
Thread context (if in a thread)

Reuse these fields directly in action calls.

Socket Mode vs Events API

Socket Mode (Recommended for Development)

No public URL required
Works behind firewalls
Easier to set up for testing
Uses WebSocket connection

Events API (Recommended for Production)

More reliable for high-traffic apps
Lower latency
Requires public HTTPS endpoint
Better for distributed systems

The elizaOS Slack integration uses Socket Mode by default.

Troubleshooting

Bot doesn’t respond

Verify both SLACK_BOT_TOKEN and SLACK_APP_TOKEN are set correctly
Check that Socket Mode is enabled in your Slack app settings
Ensure the bot has been invited to the channel (/invite @YourBot)
Check console logs for connection errors

Missing messages

Verify OAuth scopes include appropriate history scopes
Check that the bot is a member of the channel
For private channels, ensure the bot was explicitly invited

Permission errors

Review your OAuth scopes in the Slack app settings
Reinstall the app after adding new scopes
Check that actions match available permissions

Reactions not working

Ensure reactions:write scope is added
Verify emoji name/Unicode is valid
For custom emoji, use :emoji_name: format

Best Practices

Use threads - Keep channels organized by replying in threads
React to acknowledge - Use reactions instead of “OK” messages
Pin important info - Help users find key messages easily
Be concise - Slack users value brief, actionable messages
Use formatting - Make messages scannable with bold and lists
Respect quiet hours - Consider user timezones and DND settings
Test in a sandbox - Create a test workspace for development
Handle rate limits - Implement backoff for API limits

Rate Limits

Slack enforces rate limits:

Tier 1 methods (posting messages): ~1 request per second
Tier 2 methods (most reads): Varies by method
Tier 3 methods (complex operations): More restrictive
Tier 4 methods (rare operations): Most restrictive

The SDK handles rate limiting automatically with exponential backoff.

Use Cases

Team Assistant

Answer questions about projects
Fetch information from external systems
Schedule reminders
Summarize discussions

Workflow Automation

Monitor channels for keywords
Create tickets from messages
Update project management tools
Send notifications from external systems

Collaboration Enhancement

Pin decisions automatically
React to messages based on sentiment
Thread organization
Archive summaries

Get Started

Core Concepts

Guides

Multi-Language Support

Platform Integration

Slack Integration

Overview

Prerequisites

Setup

Configuration

Environment Variables

Character Settings

Features

Message Management

Read Messages

Reactions

Pin Management

User Information

Custom Emoji

Rich Formatting

Thread Replies

Message Context

Socket Mode vs Events API

Socket Mode (Recommended for Development)

Events API (Recommended for Production)

Troubleshooting

Bot doesn’t respond

Missing messages

Permission errors

Reactions not working

Best Practices

Rate Limits

Use Cases

Team Assistant

Workflow Automation

Collaboration Enhancement

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Multi-Language Support

Platform Integration

​Overview

​Prerequisites

​Setup

​Configuration

​Environment Variables

​Character Settings

​Features

​Message Management

​Read Messages

​Reactions

​Pin Management

​User Information

​Custom Emoji

​Rich Formatting

​Thread Replies

​Message Context

​Socket Mode vs Events API

​Socket Mode (Recommended for Development)

​Events API (Recommended for Production)

​Troubleshooting

​Bot doesn’t respond

​Missing messages

​Permission errors

​Reactions not working

​Best Practices

​Rate Limits

​Use Cases

​Team Assistant

​Workflow Automation

​Collaboration Enhancement

​Related Resources

Build docs developers (and LLMs) love

Overview

Prerequisites

Setup

Configuration

Environment Variables

Character Settings

Features

Message Management

Read Messages

Reactions

Pin Management

User Information

Custom Emoji

Rich Formatting

Thread Replies

Message Context

Socket Mode vs Events API

Socket Mode (Recommended for Development)

Events API (Recommended for Production)

Troubleshooting

Bot doesn’t respond

Missing messages

Permission errors

Reactions not working

Best Practices

Rate Limits

Use Cases

Team Assistant

Workflow Automation

Collaboration Enhancement

Related Resources