Copy page

Guides

Reference bridge: Mattermost

bridge.mjs is a complete, ready-to-run bridge in one file of plain Node (20 or later, no dependencies). It forwards the /hijinks slash command, button clicks and typed answers to Hijinks, verifies incoming events, and posts, updates, DMs and ephemeral replies through the Mattermost REST API with a bot token. It keeps its state in a JSON file, so a restart does not break a game in progress.

Not the one setting it up? Send whoever runs your Mattermost server the email below.

Send this to IT

Copy it, fill in the two brackets, and send it as is:

Code
Subject: Setting up Hijinks for our Mattermost (about an hour)

Hi,

We'd like to run Hijinks team games (trivia, birthdays, icebreakers) in our
Mattermost. It needs a small, ready-made connector ("bridge") on one of our
servers. Nothing has to be written; it is one file of plain Node with a
Dockerfile and a systemd unit.

What it needs:
- Admin access to the Mattermost System Console: a bot account, the /hijinks
  slash command, and two settings.
- The System Admin role for the bot (Mattermost only lets system admins post
  replies that one member sees). Without it, those replies fail and the rest
  works.
- A host to run it: Node 20 or later, or Docker. Very little memory or CPU.
- Either a public HTTPS address for the bridge, or outbound HTTPS to
  api.hijinks.team only (polling mode, for an intranet-only Mattermost).
- A Mattermost channel just for games, if we want word games: Mattermost
  forwards every message posted there to Hijinks, which ignores anything
  that is not an answer.

Time: about an hour, less if Mattermost already sits behind a reverse
proxy with automatic certificates.

Setup guide, step by step:
https://docs.hijinks.team/webhooks/mattermost/README.md
What data passes where: https://docs.hijinks.team/data-flow

I'll send you the workspace's signing secret through [our password manager]
once I've connected it in the Hijinks dashboard.

Thanks,
[your name]

Before you start

About an hour, if Mattermost already sits behind a reverse proxy with automatic certificates.

• Mattermost System Console access, to create a bot account and the /hijinks command.
• The System Admin role for the bot: Mattermost lets only system admins post the replies one member sees. Without it those replies fail and the rest of the game works.
• A host that keeps it running: Node 20 or later, or Docker. A Dockerfile and a systemd unit are included.
• A public HTTPS address for the bridge, or polling: Hijinks pushes only to HTTPS URLs that resolve to public addresses. For an intranet-only Mattermost, run the bridge in polling mode instead: it needs outbound HTTPS to api.hijinks.team and nothing inbound from the internet.
• Typed answers forward every message in the game channel to Hijinks, which ignores anything that is not an answer. Use a channel just for games. What a bridge sends us lists every field.

The setup guide has the full checklist and the steps in order: Mattermost, then connect in the dashboard, then start the bridge, then send a test event.

What each feature looks like in Mattermost is on What works over a bridge. Copy the bridge as the starting point for any other chat: the Hijinks half stays the same.

Files

Download them into one directory and the guide's commands work as written:

Code
mkdir hijinks-bridge && cd hijinks-bridge
for f in bridge.mjs package.json Dockerfile hijinks-bridge.service README.md; do
  curl -fsSO "https://docs.hijinks.team/webhooks/mattermost/$f"
done