Mattermost | Sophon

Sophon connects to a Mattermost server using its REST API v4 for sending messages and the Mattermost WebSocket API for receiving them in real time. You authenticate with a single bot access token and the URL of your Mattermost server.

Prerequisites

A running Mattermost server (Cloud or self-hosted) reachable over HTTPS
System Admin access, or a team admin who can create bot accounts
The bot account added to the channels you want Sophon to listen and post in

Step-by-Step Setup

1. Create a Bot Account

Sign in to Mattermost as a System Admin
Open the System Console and go to Integrations > Bot Accounts
Make sure Enable Bot Account Creation is set to true
Return to your team, open the Main Menu > Integrations > Bot Accounts
Click Add Bot Account
Give it a username (e.g., sophon) and a display name, then click Create Bot Account

2. Copy the Access Token

After the bot is created, Mattermost shows a Token. Copy it immediately and store it securely. This is the value Sophon uses to authenticate.

3. Add the Bot to Channels

The bot only receives and posts in channels it belongs to. In each target channel, use the channel menu Add Members (or /invite @sophon) to add the bot account.

4. Note Your Server URL

Sophon needs the base URL of your Mattermost server, for example https://chat.example.com. Do not include a path such as /api/v4 — Sophon appends the API path automatically. Sophon derives the WebSocket endpoint from this URL, so an https:// server is reached over wss://.

5. Configure in Sophon Dashboard

Go to Channels and click Add Channel
Select Mattermost
Paste the Server URL
Paste the Bot Token
Click Test Connection — Sophon calls the server to verify the credentials
Click Activate

6. Test It

Post a message in a channel the bot has joined. Sophon should reply in the same channel.

Configuration Reference

Field	Type	Required	Description
`serverUrl`	string	Yes	Base URL of the Mattermost server, e.g. `https://chat.example.com` (no trailing path)
`botToken`	secret	Yes	Access token for the bot account, used as a Bearer token

These two keys (serverUrl and botToken) are the exact settings the adapter reads. Both are required — the connection fails to start if either is missing or blank.

channels.json Example

{
  "id": "mattermost-server",
  "type": "mattermost",
  "name": "Sophon Mattermost Bot",
  "enabled": true,
  "config": {
    "serverUrl": "https://chat.example.com",
    "botToken": "<encrypted>"
  },
  "routing": {
    "agentId": "default",
    "dmBehavior": "main-session",
    "groupBehavior": "mention-only"
  },
  "status": "connected"
}

Media Support

The adapter exchanges plain text posts. Inbound messages are read as the post text, and outbound replies are sent as the post message body. When Sophon emits an image, only its caption text is delivered to Mattermost.

Type	Inbound	Outbound
Text	Yes	Yes
Images	No	Caption text only
Audio	No	No
Video	No	No
Documents	No	No

Troubleshooting

Test Connection fails with a 401 — The bot token is invalid, revoked, or for the wrong server. Recreate the token from Integrations > Bot Accounts and paste it again.
Bot never receives messages — The bot account must be a member of the channel. Add it with /invite @sophon. Sophon also ignores the bot's own posts, so messages it sends will not loop back.
WebSocket keeps reconnecting — Confirm the server URL uses the correct scheme. An https:// URL is required for a secure wss:// socket; a reverse proxy that blocks WebSocket upgrades will cause repeated reconnect attempts.
"requires a 26-character channel ID" — When targeting a channel directly, Mattermost channel IDs are exactly 26 characters. Verify you are using the internal channel ID, not the channel name or URL slug.
Wrong server URL — Do not append /api/v4 to the server URL; Sophon adds the API path itself. A trailing path or slash leads to failed requests.

Group behavior

In channels, Sophon responds according to the channel's group policy (mention-only by default on Pro/Enterprise; Personal-tier instances respond to all group messages — see Group Chats). Mattermost supports all four mention triggers: explicit @mentions, replies to the bot, quotes of the bot's messages, and participation in threads the bot is already part of.

When a user replies to an earlier post, Sophon fetches the quoted post from the Mattermost API and presents it to the agent as context. This adds a small amount of latency to the response.

Each Mattermost threaded post gets its own isolated session, rooted at the thread's first post — a child of the channel's session with separate history and context, expired automatically after a period of inactivity.

See Group Chats for policies and allowlists, and Threads & Sessions for thread session lifecycle and configuration.

MattermostNEW