bot/docs/channels/mattermost.md

summary, read_when, title

summary	read_when	title
Mattermost bot setup and Hanzo Bot config	Setting up Mattermost Debugging Mattermost routing	Mattermost

Mattermost (plugin)

Status: supported via plugin (bot token + WebSocket events). Channels, groups, and DMs are supported. Mattermost is a self-hostable team messaging platform; see the official site at mattermost.com for product details and downloads.

Plugin required

Mattermost ships as a plugin and is not bundled with the core install.

Install via CLI (npm registry):

hanzo-bot plugins install @bot/mattermost

Local checkout (when running from a git repo):

hanzo-bot plugins install ./extensions/mattermost

If you choose Mattermost during configure/onboarding and a git checkout is detected, Hanzo Bot will offer the local install path automatically.

Details: Plugins

Quick setup

1. Install the Mattermost plugin.
2. Create a Mattermost bot account and copy the bot token.
3. Copy the Mattermost base URL (e.g., https://chat.example.com).
4. Configure Hanzo Bot and start the gateway.

Minimal config:

{
  channels: {
    mattermost: {
      enabled: true,
      botToken: "mm-token",
      baseUrl: "https://chat.example.com",
      dmPolicy: "pairing",
    },
  },
}

Native slash commands

Native slash commands are opt-in. When enabled, Bot registers oc_* slash commands via the Mattermost API and receives callback POSTs on the gateway HTTP server.

{
  channels: {
    mattermost: {
      commands: {
        native: true,
        nativeSkills: true,
        callbackPath: "/api/channels/mattermost/command",
        // Use when Mattermost cannot reach the gateway directly (reverse proxy/public URL).
        callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
      },
    },
  },
}

Notes:

• native: "auto" defaults to disabled for Mattermost. Set native: true to enable.
• If callbackUrl is omitted, Bot derives one from gateway host/port + callbackPath.
• For multi-account setups, commands can be set at the top level or under channels.mattermost.accounts.<id>.commands (account values override top-level fields).
• Command callbacks are validated with per-command tokens and fail closed when token checks fail.
• Reachability requirement: the callback endpoint must be reachable from the Mattermost server.
  • Do not set callbackUrl to localhost unless Mattermost runs on the same host/network namespace as Bot.
  • Do not set callbackUrl to your Mattermost base URL unless that URL reverse-proxies /api/channels/mattermost/command to Bot.
  • A quick check is curl https://<gateway-host>/api/channels/mattermost/command; a GET should return 405 Method Not Allowed from Bot, not 404.
• Mattermost egress allowlist requirement:
  • If your callback targets private/tailnet/internal addresses, set Mattermost ServiceSettings.AllowedUntrustedInternalConnections to include the callback host/domain.
  • Use host/domain entries, not full URLs.
    • Good: gateway.tailnet-name.ts.net
    • Bad: https://gateway.tailnet-name.ts.net

Environment variables (default account)

Set these on the gateway host if you prefer env vars:

• MATTERMOST_BOT_TOKEN=...
• MATTERMOST_URL=https://chat.example.com

Env vars apply only to the default account (default). Other accounts must use config values.

Chat modes

Mattermost responds to DMs automatically. Channel behavior is controlled by chatmode:

• oncall (default): respond only when @mentioned in channels.
• onmessage: respond to every channel message.
• onchar: respond when a message starts with a trigger prefix.

Config example:

{
  channels: {
    mattermost: {
      chatmode: "onchar",
      oncharPrefixes: [">", "!"],
    },
  },
}

Notes:

• onchar still responds to explicit @mentions.
• channels.mattermost.requireMention is honored for legacy configs but chatmode is preferred.

Access control (DMs)

• Default: channels.mattermost.dmPolicy = "pairing" (unknown senders get a pairing code).
• Approve via:
  • hanzo-bot pairing list mattermost
  • hanzo-bot pairing approve mattermost <CODE>
• Public DMs: channels.mattermost.dmPolicy="open" plus channels.mattermost.allowFrom=["*"].

Channels (groups)

• Default: channels.mattermost.groupPolicy = "allowlist" (mention-gated).
• Allowlist senders with channels.mattermost.groupAllowFrom (user IDs or @username).
• Open channels: channels.mattermost.groupPolicy="open" (mention-gated).

Targets for outbound delivery

Use these target formats with hanzo-bot message send or cron/webhooks:

• channel:<id> for a channel
• user:<id> for a DM
• @username for a DM (resolved via the Mattermost API)

Bare IDs are treated as channels.

Multi-account

Mattermost supports multiple accounts under channels.mattermost.accounts:

{
  channels: {
    mattermost: {
      accounts: {
        default: { name: "Primary", botToken: "mm-token", baseUrl: "https://chat.example.com" },
        alerts: { name: "Alerts", botToken: "mm-token-2", baseUrl: "https://alerts.example.com" },
      },
    },
  },
}

Troubleshooting

• No replies in channels: ensure the bot is in the channel and mention it (oncall), use a trigger prefix (onchar), or set chatmode: "onmessage".
• Auth errors: check the bot token, base URL, and whether the account is enabled.
• Multi-account issues: env vars only apply to the default account.