Mattermost
This document was written by AI and has been manually reviewed.
Mattermost#
The Mattermost driver connects to your self-hosted or cloud Mattermost server using the WebSocket API for real-time receive and the REST API for sending. No extra dependencies are needed beyond what NextBridge already uses.
Setup#
1. Create a Bot Account (recommended)#
Log in as a system admin and go to System Console → Integrations → Bot Accounts.
Enable bot accounts, then click Add Bot Account.
Fill in a username, display name, and description; click Create Bot Account.
Copy the generated token — this is your token config value.
Invite the bot to every channel it should bridge (click the channel name → Add Members).
2. Personal Access Token (alternative)#
If bot accounts are unavailable:
In your Mattermost profile, go to Security → Personal Access Tokens.
Click Create Token, give it a name, and copy the token.
Ensure Personal Access Tokens are enabled in System Console → Integrations.
Config keys#
Add under mattermost.<instance_id> in your config file:
| server_url | Yes | — | Base URL of the Mattermost server, e.g. "https://mattermost.example.com" |
| token | Yes | — | Bot token or personal access token |
| max_file_size | No | 52428800 (50 MB) | Maximum attachment size in bytes |
| proxy | No | — | Proxy URL for all Mattermost API requests (e.g., http://proxy.example.com:8080 or socks5://proxy.example.com:1080). Set to null to explicitly disable proxy for this instance (ignores global proxy setting). |
{
"mattermost": {
"mm_main": {
"server_url": "https://mattermost.example.com",
"token": "your-bot-or-personal-access-token"
}
}
}Rule channel keys#
| channel_id | Mattermost channel ID |
To find a channel ID: open the channel, click the channel name at the top, and look for the ID in the URL (/team-name/channels/channel-name → copy the channel ID from the API or use /api/v4/channels/name/{team}/{channel}). The easiest method is to inspect any message in the channel via the Mattermost REST API.
{
"mm_main": {
"channel_id": "abc123def456"
}
}How it works#
Receive: At startup, the driver fetches the bot’s own user ID (/api/v4/users/me) so it can filter out its own messages. It then connects to the Mattermost WebSocket endpoint (/api/v4/websocket) and sends an authentication challenge with the token. On every posted event:
System posts (joins, leaves, header changes) are ignored by checking the post type field
File attachments are fetched from /api/v4/files/{id} using the same token and forwarded as binary data
The WebSocket reconnects automatically after 5 seconds if the connection drops.
Send: For each outgoing message the driver:
Uploads any binary attachments to /api/v4/files (multipart) and collects the returned file_id values
Creates a post via POST /api/v4/posts with message and file_ids
Attachments that cannot be fetched are appended as text labels ([Type: filename])
Notes#
The bot account must be invited to each channel it should read and write. Messages in channels the bot isn’t a member of are not delivered over the WebSocket.
Mattermost uses standard Markdown for formatting. The rich_header prefix renders as **Title** · *Content*.
Display name resolution priority: Nickname → First + Last name → Username.
No new Python packages are required — the driver uses only aiohttp, which NextBridge already depends on.
User avatars are served at /api/v4/users/{user_id}/image and require a valid session to view; downstream platforms that hotlink avatars may see an error if the Mattermost server is not publicly accessible.