Hunter Miller 0b3f4a27ba docs: update all plugin docs to reflect bundled + auto-install

Updated docs for all bundled plugins to reflect:
- Plugins are bundled with Clawdbot
- Dependencies auto-install on first load when enabled
- npm install is an alternative, not required
- Simplified setup steps

Updated channels:
- line, matrix, mattermost, msteams, nextcloud-talk, nostr, zalo, zalouser

Updated plugins:
- voice-call, zalouser

2026-01-26 12:55:13 -06:00

3.6 KiB

Raw Blame History

summary

read_when

Mattermost bot setup and Clawdbot config

Setting up Mattermost

Debugging Mattermost routing

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 setup

Mattermost is bundled with Clawdbot. Its dependencies are automatically installed on first load when you enable the plugin.

To enable, add mattermost to your plugins allow list:

{
  plugins: {
    allow: ["mattermost"]
  }
}

The onboarding wizard and clawdbot channels add also offer to enable Mattermost.

Alternatively, install explicitly from npm:

clawdbot plugins install @clawdbot/mattermost

Details: Plugins

Quick setup

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

Minimal config:

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

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:
- clawdbot pairing list mattermost
- clawdbot 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 clawdbot 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.

3.6 KiB Raw Blame History