ContextQMD
Back to Eliza

Mattermost Connector

packages/docs/connectors/mattermost.md

2.0.14.4 KB
Original Source

Mattermost Connector

Connect your agent to a self-hosted Mattermost server for channel and DM conversations using the @elizaos/plugin-mattermost package.

Prerequisites

  • A Mattermost server with bot account support enabled
  • A bot token from the Mattermost System Console

Configuration

NameRequiredDescription
MATTERMOST_BOT_TOKENYesBot token from Mattermost System Console
MATTERMOST_SERVER_URLNoServer URL for the Mattermost instance
MATTERMOST_ENABLEDNoEnable or disable the connector
MATTERMOST_TEAM_IDNoTeam/tenant ID to restrict the bot to
MATTERMOST_DM_POLICYNoDM policy (e.g., allow, deny, allowlist)
MATTERMOST_GROUP_POLICYNoGroup message policy (e.g., allow, deny)
MATTERMOST_ALLOWED_USERSNoComma-separated allowed user list
MATTERMOST_ALLOWED_CHANNELSNoComma-separated allowed channel list
MATTERMOST_REQUIRE_MENTIONNoOnly respond when @mentioned
MATTERMOST_IGNORE_BOT_MESSAGESNoIgnore messages from other bots

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

Configure in ~/.eliza/eliza.json:

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

To disable:

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

Setup

  1. In Mattermost System Console, create a bot account and note the bot token.
  2. Add the bot token and server URL to connectors.mattermost in your config.
  3. Start your agent -- the Mattermost connector will auto-enable.

Features

Environment Variables

When the connector is loaded, the runtime pushes the following secrets from your config into process.env for the plugin to consume:

VariableRequiredDescription
MATTERMOST_BOT_TOKENYesBot token from Mattermost System Console
MATTERMOST_SERVER_URLNoServer URL for the Mattermost server
MATTERMOST_ENABLEDNoEnable or disable the connector
MATTERMOST_TEAM_IDNoTeam ID to restrict the bot to
MATTERMOST_DM_POLICYNoDM policy (e.g., allow, deny, allowlist)
MATTERMOST_GROUP_POLICYNoGroup message policy
MATTERMOST_ALLOWED_USERSNoComma-separated allowed user list
MATTERMOST_ALLOWED_CHANNELSNoComma-separated channel list to restrict the bot to
MATTERMOST_REQUIRE_MENTIONNoOnly respond when @mentioned
MATTERMOST_IGNORE_BOT_MESSAGESNoIgnore messages from other bots

Full Configuration Reference

All fields are defined under connectors.mattermost in eliza.json.

Core Fields

FieldTypeDefaultDescription
botTokenstring—Bot token from Mattermost System Console (required)
baseUrlstring—Base URL for your Mattermost server (required)
enabledboolean—Explicitly enable/disable
chatmode"dm-only" | "channel-only" | "all""all"Restrict which chat types the bot responds in
requireMentionbooleanfalseOnly respond when @mentioned
oncharPrefixesstring[]—Custom command prefixes that trigger agent responses
configWritesbooleantrueAllow config writes from channel events

Chat Mode

The chatmode field controls where the bot responds:

ModeBehavior
"all"Responds in both DMs and channels (default)
"dm-only"Responds only in direct messages
"channel-only"Responds only in channels
json
{
  "connectors": {
    "mattermost": {
      "botToken": "YOUR_BOT_TOKEN",
      "baseUrl": "https://chat.example.com",
      "chatmode": "all",
      "requireMention": true,
      "oncharPrefixes": ["!", "/ask"]
    }
  }
}

Self-Hosted Server Support

The Mattermost connector works with any Mattermost server deployment, including self-hosted instances. Set baseUrl to your server's URL and ensure the Eliza host can reach it over the network.

Multi-Account Support

Mattermost does not support multi-account configuration. Each agent runs a single Mattermost bot.