# 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:
```text
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](/polling) 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](/data-flow) 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](/bridged-chats).
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:
```sh
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
```
| File | What it is |
| --- | --- |
| bridge.mjs | The bridge, one file |
| README.md | Setup guide: prerequisites, bot account, slash command, settings, running it as a service |
| package.json | `npm start` and the Node version |
| Dockerfile | Container image, state on a volume |
| hijinks-bridge.service | systemd unit |
| openapi.yaml | The contract it implements |