HiveMind Mattermost Bridge

Relay a Mattermost bot account to a HiveMind hub.

The bridge is a HiveMind satellite whose input and output are Mattermost chat instead of a microphone. Mentions and direct messages to the bot become utterances sent to the hub; the hub's spoken reply is posted back to the originating channel. Any HiveMind hub (and the OVOS skills behind it) becomes reachable as a Mattermost chatbot.

Mattermost channel  ⇄  HiveMind_mattermost_bridge  ⇄  HiveMind hub  ⇄  OVOS skills

Prerequisites

• A running HiveMind hub (hivemind-core) reachable over the network, and a HiveMind access key for this bridge (hivemind-core add-client).
• A Mattermost server and a bot user account on it (an email/login and password the bridge logs in with). The bot must be a member of the channels it should answer in.
• Python 3.10+.

Install

git clone https://github.com/JarbasHiveMind/HiveMind_mattermost_bridge
cd HiveMind_mattermost_bridge
pip install .

This installs the hivemind-mattermost-bridge console script.

Dependencies: hivemind-bus-client, mattermostdriver, ovos-utils, ovos-bus-client.

Quickstart

1. Register the bridge on the hub (where hivemind-core is installed):

hivemind-core add-client --name mattermost-bridge \
  --access-key "your-access-key" --password "your-password"

2. Run the bridge. Pass Mattermost credentials and HiveMind identity as flags (HiveMind key/password/host default to the values stored by hivemind-client set-identity):

hivemind-mattermost-bridge \
  --mail bot@example.com \
  --pswd bot-password \
  --url chat.example.com \
  --tag @bot \
  --host ws://127.0.0.1 \
  --port 5678 \
  --key your-access-key \
  --password your-hivemind-password

Or run as a module: python -m mattermost_bridge --help.

3. Send a message. In a channel the bot is in, mention it:

@bot what time is it?

The bridge forwards the message to the hub and posts the hub's reply back to the channel.

Configuration

CLI flags (hivemind-mattermost-bridge --help):

Flag	Description	Default
--mail	Mattermost bot account login (email)	—
--pswd	Mattermost bot account password	—
--url	Mattermost server host (no scheme)	—
--tag	Trigger tag; messages containing one are forwarded (repeatable)	@bot
--host	HiveMind hub host (e.g. ws://127.0.0.1)	from identity file
--port	HiveMind hub port	5678
--key	HiveMind access key	from identity file
--password	HiveMind password	from identity file
--self-signed	Accept self-signed SSL certificates	off
--lang	Utterance language	en-us

Troubleshooting

• Bot never answers — confirm the bot account is a member of the channel and the message contains a trigger tag; confirm the hub is reachable and the access key is registered (hivemind-core list-clients).
• Mattermost login fails — check url is the bare host (no https://) and the bot login/password are correct.
• No reply posted — replies are routed by channel and user context; the hub must echo those context keys and produce a speak for the answer to land.

Documentation

• Operator setup — getting the bot's Mattermost account (or self-hosting mattermost-preview), registering the bridge on a HiveMind hub, the run command, and live e2e.

See also docs/ for a full setup walkthrough, a configuration reference, and worked examples.