ContextQMD
Back to Eliza

Mattermost Plugin

packages/docs/plugin-registry/platform/mattermost.md

2.0.14.3 KB
Original Source

The Mattermost plugin connects Eliza agents to a Mattermost server as a bot, supporting channel messages and DMs with configurable mention requirements and chat modes.

Package: @elizaos/plugin-mattermost

Installation

bash
eliza plugins install @elizaos/plugin-mattermost

Setup

1. Create a Bot Account

  1. Open your Mattermost instance
  2. Navigate to System Console → Integrations → Bot Accounts
  3. Click Add Bot Account
  4. Fill in the display name and description
  5. Copy the generated Bot Token

2. Configure Eliza

json
{
  "connectors": {
    "mattermost": {
      "enabled": true,
      "botToken": "YOUR_BOT_TOKEN",
      "baseUrl": "https://chat.example.com"
    }
  }
}

Or via environment variables:

bash
export MATTERMOST_BOT_TOKEN=YOUR_BOT_TOKEN
export MATTERMOST_SERVER_URL=https://chat.example.com

Environment Variables

VariableRequiredDescription
MATTERMOST_BOT_TOKENYesBot token from Mattermost System Console
MATTERMOST_SERVER_URLNoMattermost server URL
MATTERMOST_TEAM_IDNoTeam/tenant ID
MATTERMOST_DM_POLICYNoDM policy
MATTERMOST_GROUP_POLICYNoGroup message policy
MATTERMOST_ALLOWED_USERSNoComma-separated list of allowed user IDs
MATTERMOST_ALLOWED_CHANNELSNoComma-separated list of allowed channel IDs
MATTERMOST_REQUIRE_MENTIONNoOnly respond when mentioned
MATTERMOST_IGNORE_BOT_MESSAGESNoIgnore messages from other bots
MATTERMOST_ENABLEDNoEnable or disable the connector

Configuration

FieldRequiredDescription
botTokenYesBot token from Mattermost System Console
baseUrlYesBase URL for your Mattermost server
chatmodeNoChat mode: dm-only, channel-only, or all (default: all)
requireMentionNoOnly respond when @mentioned (default: false)
oncharPrefixesNoCustom command prefixes for triggering responses
configWritesNoAllow config writes from channel events (default: true)
enabledNoSet false to disable (default: true)

Features

  • Channel messages — Monitor and respond in public and private channels
  • DMs — Full private conversation support
  • Chat modes — Restrict to DMs only, channels only, or all
  • Mention filtering — Optionally require @mentions before responding
  • Command prefixes — Custom prefix triggers for agent responses
  • Self-hosted — Works with any Mattermost server deployment

Environment Variables

VariableRequiredDescription
MATTERMOST_BOT_TOKENYesBot token (primary auto-enable trigger)
MATTERMOST_SERVER_URLNoMattermost server URL
MATTERMOST_ENABLEDNoEnable or disable the connector
MATTERMOST_TEAM_IDNoTeam ID to connect to
MATTERMOST_DM_POLICYNoDM acceptance policy
MATTERMOST_GROUP_POLICYNoGroup message policy
MATTERMOST_ALLOWED_USERSNoComma-separated allowed user IDs
MATTERMOST_REQUIRE_MENTIONNoOnly respond when @mentioned
MATTERMOST_ALLOWED_CHANNELSNoComma-separated allowed channel IDs
MATTERMOST_IGNORE_BOT_MESSAGESNoIgnore messages from other bots

Auto-Enable

The plugin auto-enables when the connectors.mattermost block contains a botToken:

json
{
  "connectors": {
    "mattermost": {
      "botToken": "YOUR_BOT_TOKEN",
      "baseUrl": "https://chat.example.com"
    }
  }
}

Troubleshooting

Bot Not Responding in Channels

Ensure the bot account has been added to the channels where it should respond. By default, bots must be explicitly invited to channels.

Connection Refused

Verify the baseUrl is correct and the Mattermost server is reachable from the Eliza host. For self-hosted instances, check firewall rules.

Bot Token Invalid

Bot tokens can be regenerated from System Console → Integrations → Bot Accounts. Update the token in your Eliza configuration after regeneration.