Discord Connector

Connect your agent to Discord servers and DMs using the @elizaos/plugin-discord package.

Prerequisites

A Discord bot token from the Discord Developer Portal
The bot added to your target server(s) with appropriate permissions

Configuration

Name	Required	Description
`DISCORD_API_TOKEN`	Yes	Discord bot token for authentication
`DISCORD_APPLICATION_ID`	No	Application ID (auto-resolved from bot token if omitted)
`CHANNEL_IDS`	No	Comma-separated list of channel IDs to restrict the bot to
`DISCORD_LISTEN_CHANNEL_IDS`	No	Comma-separated list of channel IDs where the bot only listens (no responses)
`DISCORD_SHOULD_IGNORE_BOT_MESSAGES`	No	If `true`, ignore messages from other bots
`DISCORD_SHOULD_IGNORE_DIRECT_MESSAGES`	No	If `true`, ignore direct messages
`DISCORD_SHOULD_RESPOND_ONLY_TO_MENTIONS`	No	If `true`, only respond when explicitly @mentioned
`DISCORD_VOICE_CHANNEL_ID`	No	Voice channel ID for the bot to join
`DISCORD_TEST_CHANNEL_ID`	No	Channel ID for test suite operations

The connector auto-enables when token, botToken, or apiKey is truthy in the connector config and enabled is not explicitly false.

Configure in ~/.eliza/eliza.json:

json

{
  "connectors": {
    "discord": {
      "token": "your-discord-bot-token"
    }
  }
}

<Warning> Use the `token` field for your bot token. The auto-enable detection accepts `token`, `botToken`, or `apiKey`, but the Discord config schema only validates `token` as a known field. Using `botToken` will trigger auto-enable but may fail schema validation. </Warning>

Disabling the Connector

To explicitly disable the connector even when a token is present:

json

{
  "connectors": {
    "discord": {
      "token": "your-discord-bot-token",
      "enabled": false
    }
  }
}

Features

The plugin-auto-enable.ts module checks connectors.discord in your config. If token (or botToken / apiKey) is truthy and enabled is not explicitly false, the runtime automatically loads @elizaos/plugin-discord.

No environment variable is required to trigger auto-enable — it is driven entirely by the connector config object.

Environment Variables

When loaded, secrets are pushed to process.env for the plugin to consume:

Variable	Required	Description
`DISCORD_API_TOKEN`	Yes	Primary bot token (always set from `token` config field)
`DISCORD_BOT_TOKEN`	No	Mirror of `DISCORD_API_TOKEN` (both always set)
`DISCORD_APPLICATION_ID`	No	Application ID. Auto-resolved via Discord OAuth2 API if not set
`CHANNEL_IDS`	No	Comma-separated list of channel IDs to restrict the bot to
`DISCORD_LISTEN_CHANNEL_IDS`	No	Comma-separated list of channel IDs where the bot will only listen (not respond)
`DISCORD_VOICE_CHANNEL_ID`	No	Voice channel ID the bot should join (auto-selects based on activity if not set)
`DISCORD_SHOULD_IGNORE_BOT_MESSAGES`	No	Ignore messages from other bots
`DISCORD_SHOULD_IGNORE_DIRECT_MESSAGES`	No	Ignore direct messages
`DISCORD_SHOULD_RESPOND_ONLY_TO_MENTIONS`	No	Only respond when explicitly @mentioned

Note: If DISCORD_APPLICATION_ID is not configured, the runtime automatically resolves it by calling https://discord.com/api/v10/oauth2/applications/@me with the bot token.

Full Configuration Reference

All fields are set under connectors.discord in eliza.json.

Field	Type	Default	Description
`token`	string	—	Bot token (legacy field name)
`name`	string	—	Account display name
`enabled`	boolean	—	Explicitly enable/disable
`capabilities`	string[]	—	Capability flags
`allowBots`	boolean	—	Allow bot-authored messages to trigger responses
`groupPolicy`	`"open"` \| `"disabled"` \| `"allowlist"`	`"allowlist"`	How the bot joins group conversations
`historyLimit`	integer >= 0	—	Max messages to include in conversation context
`dmHistoryLimit`	integer >= 0	—	History limit for DM conversations
`dms`	object	—	Per-DM history overrides keyed by DM ID. Each value: `{historyLimit?: int}`
`textChunkLimit`	integer > 0	—	Max characters per message chunk
`chunkMode`	`"length"` \| `"newline"`	—	How to split long messages
`blockStreaming`	boolean	—	Disable streaming responses
`blockStreamingCoalesce`	object	—	Coalescing settings: `minChars`, `maxChars`, `idleMs`
`maxLinesPerMessage`	integer > 0	17	Max lines per Discord message
`mediaMaxMb`	number > 0	—	Max media file size in MB
`replyToMode`	`"off"` \| `"first"` \| `"all"`	—	When to use Discord reply threading
`configWrites`	boolean	true	Allow config writes from Discord events
`markdown`	object	—	Markdown rendering: `tables` can be `"off"`, `"bullets"`, or `"code"`
`commands`	object	—	`native` and `nativeSkills` slash command toggles (boolean or `"auto"`)

Retry Configuration

Field	Type	Description
`retry.attempts`	integer	Max retry attempts
`retry.minDelayMs`	integer	Minimum delay between retries
`retry.maxDelayMs`	integer	Maximum delay between retries
`retry.jitter`	number	Jitter factor for retry backoff

Actions

Toggle individual Discord actions under actions:

Field	Type	Description
`actions.reactions`	boolean	Send reactions
`actions.stickers`	boolean	Send stickers
`actions.emojiUploads`	boolean	Upload custom emoji
`actions.stickerUploads`	boolean	Upload custom stickers
`actions.polls`	boolean	Create polls
`actions.permissions`	boolean	Manage permissions
`actions.messages`	boolean	Send messages
`actions.threads`	boolean	Create/manage threads
`actions.pins`	boolean	Pin messages
`actions.search`	boolean	Search messages
`actions.memberInfo`	boolean	View member info
`actions.roleInfo`	boolean	View role info
`actions.roles`	boolean	Manage roles
`actions.channelInfo`	boolean	View channel info
`actions.voiceStatus`	boolean	Voice channel status
`actions.events`	boolean	Manage server events
`actions.moderation`	boolean	Moderation actions
`actions.channels`	boolean	Manage channels
`actions.presence`	boolean	Presence updates

DM Policy

Configure DM behavior under the dm key:

Field	Type	Default	Description
`dm.enabled`	boolean	—	Enable/disable DMs
`dm.policy`	`"pairing"` \| `"allowlist"` \| `"open"` \| `"disabled"`	`"pairing"`	DM access policy. `"pairing"` requires the pairing flow. `"open"` requires `allowFrom` to include `"*"`
`dm.allowFrom`	(string\|number)[]	—	User IDs allowed to DM. Must include `"*"` when policy is `"open"`
`dm.groupEnabled`	boolean	—	Enable group DMs
`dm.groupChannels`	(string\|number)[]	—	Allowed group DM channel IDs

Guild Configuration

Per-guild settings under guilds.<guild-id>:

Field	Type	Description
`slug`	string	Guild display name
`requireMention`	boolean	Only respond when @mentioned
`tools`	ToolPolicySchema	Tool access policy
`toolsBySender`	object	Per-sender tool policies (keyed by sender ID)
`reactionNotifications`	`"off"` \| `"own"` \| `"all"` \| `"allowlist"`	Reaction notification filter
`users`	(string\|number)[]	Allowed user IDs

Channel Configuration

Per-channel settings under guilds.<guild-id>.channels.<channel-id>:

Field	Type	Description
`allow`	boolean	Allow bot in this channel
`enabled`	boolean	Enable/disable channel
`requireMention`	boolean	Only respond when @mentioned
`tools`	ToolPolicySchema	Tool access policy for this channel
`toolsBySender`	object	Per-sender tool policies (keyed by sender ID)
`skills`	string[]	Skills allowed in this channel
`users`	(string\|number)[]	Allowed user IDs
`systemPrompt`	string	Channel-specific system prompt override
`autoThread`	boolean	Auto-create threads for conversations

Advanced Features

Privileged Intents

json

{
  "connectors": {
    "discord": {
      "intents": {
        "presence": true,
        "guildMembers": true
      }
    }
  }
}

These must also be enabled in the Discord Developer Portal.

PluralKit Integration

json

{
  "connectors": {
    "discord": {
      "pluralkit": {
        "enabled": true,
        "token": "pk-token"
      }
    }
  }
}

Resolves PluralKit proxy messages to their original authors.

Exec Approvals

json

{
  "connectors": {
    "discord": {
      "execApprovals": {
        "enabled": true,
        "approvers": ["user-id-1"],
        "agentFilter": "pattern",
        "sessionFilter": "pattern"
      }
    }
  }
}

Requires human approval for certain agent actions.

Heartbeat

json

{
  "connectors": {
    "discord": {
      "heartbeat": {
        "showOk": true,
        "showAlerts": true,
        "useIndicator": true
      }
    }
  }
}

Multi-Account Support

The accounts field allows running multiple Discord bot accounts:

json

{
  "connectors": {
    "discord": {
      "accounts": {
        "bot-1": { "token": "...", "guilds": { } },
        "bot-2": { "token": "...", "guilds": { } }
      }
    }
  }
}

Each account inherits the base config and can override any field.

Discord Connector

Discord Connector

Prerequisites

Configuration

Disabling the Connector

Features

Environment Variables

Full Configuration Reference

Retry Configuration

Actions

DM Policy

Guild Configuration

Channel Configuration

Advanced Features

Privileged Intents

PluralKit Integration

Exec Approvals

Heartbeat

Multi-Account Support

Related