Mattermost
This article describes how to connect Mattermost to Agentic Engine. The channel sends and edits messages through the Mattermost REST API v4 and receives messages through WebSocket. User identity can be verified through OAuth authorization or a one-time binding code.
1. Prerequisites
- You have Mattermost system admin permissions and can create a Bot Account. If you need OAuth, you also need to create an OAuth 2.0 Application.
- You have permission to access System Admin > Channels in Agentic Engine.
- A Team and Channel are ready for the Bot to use.
- The Agentic Engine server can access the Mattermost Site URL,
/api/v4/**, and/api/v4/websocket. - If you need OAuth binding, prepare an Agentic Engine URL that users' browsers can access. We recommend HTTPS for production.
Supported deployments: Both Mattermost Cloud and self-hosted deployments are supported. The Site URL can include a deployment subpath.
2. Create a Mattermost Bot and get credentials
Use a Mattermost system admin account and follow these steps:
- Go to System Console → Integrations → Bot Accounts and set Enable Bot Account Creation to true.
- Open Product menu → Integrations → Bot Accounts and click Add Bot Account.
- Enter the Bot Username, Display Name, and Description. For production, we recommend keeping the regular Member role and granting permissions on the principle of least privilege.
- Click Create Bot Account and copy the generated Access Token right away.
- Add the Bot to the Team and Channel where you want to use it.
The Bot Token is shown only once. Save it right away in a controlled password management system. Don't put it in code repositories, tickets, or chat logs. If the token is leaked, revoke it and generate a new one in Mattermost.
The Bot needs at least the following capabilities:
| Capability | Purpose |
|---|---|
| Read the target Channel | Receive messages in direct messages, public channels, private channels, and group chats. |
| Create Posts | Send regular replies and final results. |
| Edit Posts it created | Show streaming replies in the same Post. |
| Read and upload files | Process user attachments and send files generated by the Agent back to the original channel and thread. |
Record the Mattermost Site URL
Record the URL of your Mattermost site, for example:
https://chat.example.com
If the site is deployed under a subpath, you can enter:
https://example.com/mattermost
Don't append /api/v4, query parameters, or fragments, and don't embed a username and password in the URL.
3. Create an OAuth 2.0 app (optional)
OAuth isn't required for the bot to send and receive messages. With OAuth turned off, users can still bind their accounts with a 6-digit one-time binding code. If you want users to authorize and bind directly after they click the entry, continue with the following configuration:
- Go to System Console → Integrations → Integration Management and set Enable OAuth 2.0 Service Provider to true.
- Go to Product menu → Integrations → OAuth 2.0 Applications and click Add OAuth 2.0 Application.
- Set Is Public Client to No to create a Confidential Client.
- We recommend keeping Is Trusted set to No so that users explicitly confirm the authorization when they bind for the first time.
- Enter the Callback URL. After you save, record the Client ID and Client Secret.
The Callback URL must exactly match the actual Agentic Engine access URL:
https://your-domain/agent/api/mattermost-oauth/callback
OAuth applications are registered per Mattermost instance. The Client ID, Client Secret, and Server URL must belong to the same Mattermost instance and can't be reused across instances.
4. Add a Mattermost channel in Agentic Engine
As an admin, log in to Agentic Engine and go to System Admin > Channels:
- Click New Channel and select Mattermost as the channel type.
- Fill in the following configuration items.
| Config items | Required | Description |
|---|---|---|
| Channel Name | Required | Display name, such as "Mattermost Bot". |
Server URL | Required | Mattermost Site URL. It can include a deployment subpath but must not include /api/v4. |
Bot Token | Required | The Access Token generated after you create the Bot Account. |
| Enable OAuth binding | Optional | When turned on, users authorize through the browser first. When turned off, users can still use a one-time binding code. |
OAuth Client ID | Conditionally required | Required when OAuth is enabled. |
OAuth Client Secret | Conditionally required | Required when OAuth is enabled. |
| Default Model | Optional | If not selected, the system-wide default model is used. |
| System Prompt | Optional | Applies only to Agent sessions in this channel. |
- Click Save, and then turn on the channel's Enable switch.
- Confirm that the channel status is normal. When the channel is enabled, the system calls
/api/v4/users/meto verify the Bot Token and Bot identity, and then connects to<Site URL>/api/v4/websocket.
Editing secrets: When you edit an existing channel, leaving the Bot Token or OAuth Client Secret empty keeps the original value. The system doesn't display saved secrets.
5. Bind a Mattermost account
Method 1: OAuth authorization binding
- Log in to Agentic Engine, click the personal menu in the lower-left corner, and select Mattermost.
- The browser opens the authorization page of the current Mattermost instance.
- Log in and confirm the authorization. When it's done, the window closes and the status in the menu changes to Bound.
The OAuth access token is used only briefly during the callback. It isn't written to the database and doesn't replace the Bot Token in the channel configuration.
Method 2: One-time binding code
If OAuth isn't enabled, or if the system can't get the authorization URL, the authorization URL is invalid, or the browser blocks the authorization window, the binding code is used automatically:
- Click Mattermost in the personal menu in the lower-left corner.
- Copy the binding command in the dialog.
- In Mattermost, send the command to the Bot in a direct message.
- After the Bot replies that binding succeeded, Agentic Engine automatically refreshes the binding status.
+bind ABC234
By default, the binding code is valid for 10 minutes and can be used only once. To prevent leaks, the system doesn't accept binding commands in channels or group chats. A Mattermost account can't be bound to multiple Agentic Engine users at the same time.
Unbind
- Click the personal menu in the lower-left corner, and click Unbind in the Mattermost row.
- After you confirm, the status changes to Unbound. To switch to a different Agentic Engine account, unbind the original account first.
6. How to use
| Scenario | Operations |
|---|---|
| Direct messages | Send your question to the Bot directly. |
| Public/private channels and group chats | Use @Bot用户名 问题内容. Regular messages that don't @mention the Bot are ignored. |
| Threads | When you ask in an existing thread, the reply stays in that thread. When you ask from a root message in a channel, the Bot replies in a new thread with that message as the root. |
| Waiting for user response | Click Enter answers to open a Dialog, or reply with text as the Bot prompts. When the maximum number of rounds is reached, click Continue execution or reply Continue. |
| Send attachments to an Agent | In direct messages, send attachments directly. In channels, @mention the Bot in the body of the attachment message. |
| Receive Agent files | Files generated by the Agent are sent back to the original channel and thread as new Posts. |
| Task notifications | You can select Mattermost for Agent Team instant tasks and scheduled tasks. Results are sent as a direct message to the task creator's bound account. |
Common commands
| Command | Description | Example |
|---|---|---|
+bind <CODE> | Bind an account with a one-time binding code. | +bind ABC234 |
+new | Start a new session. | +new |
+agent <Agent名称> <问题> | Send a message to a specified Agent. | +agent rhea 帮我分析数据 |
In channels, you still need to @mention the Bot with @Bot用户名 before you use a command.
7. Troubleshooting
Invalid configuration error on save
- The Server URL must be a complete
http://orhttps://URL. - Don't include
/api/v4, and don't include a query, fragment, or credentials embedded in the URL. - The Bot Token can't be empty when you create a channel. Only when you edit a channel does leaving it empty keep the old token.
Channel goes offline or reconnects repeatedly after it's enabled
- Use the same Bot Token to request
GET <Site URL>/api/v4/users/me, and confirm that it returns the Bot user. - Check DNS, TLS, and network connectivity from Agentic Engine to Mattermost.
- Make sure that the reverse proxy allows WebSocket Upgrade for
/api/v4/websocket. - Make sure that the Bot hasn't been deleted or disabled, and that the token hasn't been revoked or regenerated.
Bot doesn't receive channel messages
- Make sure that the Bot has joined the target Team and Channel.
- In public channels, private channels, and group chats, you must @mention the Bot correctly with
@Bot用户名. - Make sure that the channel is enabled and its status is normal.
Can receive messages but can't reply
- Make sure that the Bot has permission to create Posts in the target Channel.
- Streaming replies require that the Bot can edit Posts it created.
- If you use an advanced permission scheme, make sure that members aren't prohibited from editing their own Posts.
Attachments fail to upload or download
- Make sure that the Bot is a member of the target Channel and has permission to read and upload files.
- Check whether
channel.mattermost.fileUploads.enabledis turned on, and check the size, count, and timeout limits. - By default, up to 5 attachments are processed per message, each no larger than 2 MiB. Files whose extension, MIME type, and actual content don't match may be rejected.
Binding code is invalid
- Generate a new binding code and use it within 10 minutes.
- Make sure that the command is sent to the Mattermost Bot configured for the current tenant.
- The binding command can be sent only in a direct message with the Bot.
OAuth authorization fails
- Make sure that OAuth 2.0 Service Provider is enabled in Mattermost and that the OAuth Application is a Confidential Client.
- Make sure that the Client ID, Client Secret, and Server URL belong to the same Mattermost instance.
- The Callback URL must exactly match the URL shown in the Agentic Engine admin interface, including the actual basePath.
- Add the Agentic Engine Origin to
ALLOWED_ORIGINS. In production, use HTTPS and make sure that the cookie security settings match the protocol. - For local access, use the real browser Origin, such as
http://localhost:3000. Don't enter0.0.0.0in the OAuth Callback URL.
Related pages and next steps
- See the setup instructions for other platforms: Channel management.
- Learn about the overall flow of channel connection and binding: Channel overview and binding.
- Configure the Agent to use: Agent.
- See how to use conversations in the platform: Conversations.