Building on Antimatter

This guide is for developers. It covers scripts and bots that use the API, integrations built on webhooks and slash commands, apps (plugins) that add features to the server and the web app, and building Antimatter from source to contribute to it.

Ways to extend Antimatter

Pick the lightest tool that does the job. The first four need no access to the server itself; apps run inside it.

Tool	What it does	Good for
REST API	Everything the apps do: messages, channels, people, files, settings. A WebSocket sends events as they happen.	Scripts, synchronisation with other systems, custom clients.
Incoming webhooks	A secret URL that posts a message to a channel when something sends it JSON.	Alerts, CI results, monitoring, notifications from other tools.
Outgoing webhooks	Antimatter calls your URL when a message in a public channel starts with a trigger word, or when someone picks your action in a message's menu, and posts your reply.	Simple chat-driven automations, sending a message to another tool.
Slash commands	People type `/something`; Antimatter calls your URL and shows your answer to them or to the channel.	Lookups, actions started from the chat.
Bots	Accounts made for programs, with their own tokens, a BOT tag (AGENT for AI agents), and interactive messages and dialogs.	Assistants, notifiers, AI agents you run yourself, anything that talks with people.
Apps (plugins)	Code that runs inside the server (Go) and in the web app (React): hooks on every message, new menus, panels, message types, pages.	Features: polls, notes, calendars, integrations that need the user interface.

In the interface, people call plugins "apps". This guide says "apps (plugins)" where both words help, because the code, the API and the configuration still say "plugin".

Compatibility with Mattermost

Antimatter is a fork of Mattermost. Most of what works with a Mattermost server works with Antimatter.

What is the same

The REST API under /api/v4, its authentication, its WebSocket and its error format. The server reports version 12.0.0, so clients and apps that check the server version see a recent Mattermost.
Webhooks and slash commands, including their Slack-compatible payloads.
The server plugin API and hooks: Antimatter keeps them as they are. Server code builds against the same Go module, github.com/mattermost/mattermost/server/public. Antimatter only adds methods, for its AI service (see The AI service).
The web app plugin registry: every register… method of Mattermost's registry exists in both of Antimatter's web interfaces.
Client libraries: the Go client model.Client4 and the TypeScript client @mattermost/client (see Client libraries).
Plugin bundles: a .tar.gz with a plugin.json manifest. Plugins signed with Mattermost's key install, as do those signed with Antimatter's.

What is different

Two web interfaces. The new interface, Fusion, is the default; the classic Mattermost interface is still available. Fusion renders most plugin components, but places some of them differently and leaves a few out. An app can tell which interface is running. See Supporting the Fusion interface.
Extra API. Antimatter adds endpoints for its own features: community attributes, timeouts, messages on top, message requests, channel and category overrides, channel export, moving threads, model connections, message actions, and new fields on communities. See What Antimatter adds to the API.
Extra message features. Message attachments can show pipeline stages and a small chart; posts can be inline replies or spoilers.
Extra web app hooks for apps: a composer "+" menu item, emoji picker tabs, a panel in the channel view, a footer under sidebar channels, an entry on the integrations pages, the emoji picker's add and manage views, and a side panel that reopens where it was in a new window. See Hooks only Antimatter has.
No licences. Every feature is available without a licence key. The licence, trial and enterprise upgrade endpoints are gone; GET /api/v4/license/client remains for clients that ask. Some apps built for Mattermost's paid editions check for a licence themselves and refuse to run.
Names. Teams are called communities in the interface, but the API and the code still say team. Environment variables use the AM_ prefix, the command-line tool is amctl and the server binary is antimatter.

Where the code lives

Everything is open source, in the AntimatterChat organisation on GitHub. Every repository works on its main branch.

Repository	What it holds
antimatter	The server (Go, in `server/`), both web interfaces (`webapp/fusion` and `webapp/channels`), the TypeScript client and `amctl`.
antimatter-docker	The Docker images, with the bundled apps, and compose files.
`antimatter-plugin-*`	One repository per bundled app: polls, todo, notes, whiteboard, calendar, mail, gifs, memes, voice-channels, calls, boards (Kanban), playbooks, agents and metrics.
gifs-server	The self-hosted GIF and sticker service used by the GIFs app.
desktop-app, mobile-app, push-proxy	The desktop and mobile apps, and the service that relays push notifications to phones.
antimatter.chat	This website and its documentation.
community	Issues and discussions for every part of Antimatter.

Before you start

Get a test server. The quickest is the Docker image: see Installing Antimatter. To work on Antimatter itself, see Building from source.
Check what the server allows. Several integration features are off by default and need a system admin: personal access tokens, bot accounts, username and icon overrides, and uploading apps. Each page says which setting it needs.
Know your site URL. The examples use https://chat.example.com. Replace it with your server's address.

In this guide

The REST API: authentication, main resources, pagination, errors, rate limits, the WebSocket, client libraries, and Antimatter's additions.
Webhooks: incoming and outgoing webhooks, payloads, attachments and cards.
Slash commands: custom commands, their request and response, autocomplete.
Bots and interactive messages: bot accounts, external agents, buttons, menus and dialogs.
Writing apps: the plugin layout, server hooks, the web app registry, Fusion, settings, storage, translations and packaging.
Building from source: the server, the web interfaces, the Docker image and the apps.
Contributing: issues, pull requests, style, translations, security and licences.

Questions are welcome in the community discussions. Report bugs in the community issues.