Mattermost Bot | Alephant Documentation

The Mattermost bot connects AIvis to self-hosted Mattermost collaboration environments. Treat it as a controlled message entry before rollout: accept requests only from approved teams, channels, or command triggers; return only knowledge and tool results allowed for the current user or channel; and keep every request auditable.

Use cases

Scenario	Recommendation
Public-channel Q&A	Use an Outgoing Webhook and restrict trigger words to approved public channels.
Private-channel or direct-message Q&A	Use a custom Slash Command. Mattermost documents that slash commands work in public channels, private channels, and direct messages.
Posting with a stable bot identity	Create a Bot Account and use its bot access token for Mattermost REST API calls.
Production ChatOps	Use a dedicated Mattermost bot account, dedicated webhook or command, and a dedicated AIvis workspace/access boundary.
Sensitive knowledge Q&A	Verify the Mattermost source channel, user, and AIvis access groups before returning sensitive data. Do not use the bot as a shared permission bypass.

Choose an integration method

Mattermost capability	Best for	Notes
Outgoing Webhook	Listening for messages or trigger words in public channels and POSTing them to the AIvis callback URL.	Mattermost documents outgoing webhooks for public channels. Empty channel or trigger-word fields broaden the trigger scope.
Custom Slash Command	Sending an explicit `/aivis question` request to AIvis.	Works in public channels, private channels, and direct messages, and supports autocomplete.
Bot Account + Personal Access Token	Letting AIvis proactively call the Mattermost REST API to post messages, reply, or inspect channel information.	Use a non-admin bot account. Do not reuse a System Admin or personal user token.

Start with a Custom Slash Command for the smallest controlled loop: the trigger is explicit, user intent is clear, and it supports private channels and direct messages. Use an Outgoing Webhook only when you need to listen for natural-language messages in public channels.

Management Boundary

Area	Guidance
Entry	Bind only approved Mattermost sites, teams, channels, slash commands, or outgoing webhooks.
Identity	Use a dedicated Bot Account or integration account instead of a personal admin token.
Responses	Control returned content by Mattermost source, AIvis user/group, Agent, knowledge base, and tool permissions.
Callback	Use HTTPS callback URLs; if the callback is internal, configure trusted internal connections as required by Mattermost.
Operations	Track Mattermost Site URL, team/channel, command/webhook token, bot token, network policy, owner, and rotation time.

Before Configuration

Confirm the Mattermost Server version and deployment model, and make sure the current account can open Product menu > Integrations or that a System Admin can configure it.
Confirm the required integration features are enabled: Outgoing Webhooks, Custom Slash Commands, Personal Access Tokens, or Bot Accounts.
Prepare an AIvis HTTPS callback URL reachable by the Mattermost server.
Define the teams, channels, users, default Agent, knowledge scope, and tool scope the bot can serve.
Decide whether to use an Outgoing Webhook, a Custom Slash Command, or an additional Bot Account / Personal Access Token.
Store all tokens only in protected configuration. Do not put them in public docs, Agent instructions, tickets, screenshots, or chat messages.

Where to get configuration values

Configuration value	Where to get it
Mattermost Site URL	Use the Mattermost site root, such as `https://mattermost.example.com`. The AIvis backend should be able to reach this URL, and users should be able to open source links in their browser.
Outgoing Webhook Token	In Mattermost, open Product menu > Integrations > Outgoing Webhooks, create the webhook, then copy the Token. See Mattermost Developers: Outgoing webhooks.
Slash Command Token	In Product menu > Integrations > Slash Commands, create the custom command and copy the generated token. See Mattermost Developers: Custom slash commands.
Bot Account Token	Enable bot account creation in System Console > Integrations > Bot Accounts, then create a dedicated bot from Integrations > Bot Accounts and copy the generated token. See Mattermost Developers: Bot accounts.
Personal Access Token	If you use a normal integration account, enable Personal Access Tokens in the System Console, then create a token from that account’s Profile > Security > Personal Access Tokens page. See Mattermost Developers: Personal access tokens.
Team / Channel ID	Confirm from a Mattermost channel link, API response, or system administration records. Before rollout, record the team, channel, channel display name, and owner instead of relying only on a display name.
Integration switches	Check Outgoing Webhooks, Custom Slash Commands, and Personal Access Tokens in System Console > Integrations > Integration Management. Check Bot Accounts in System Console > Integrations > Bot Accounts. See Mattermost admin docs: Integrations configuration settings.

Configure an Outgoing Webhook

Use an Outgoing Webhook when the bot should listen for trigger words in public channels:

Open Product menu > Integrations > Outgoing Webhooks.
Select Add Outgoing Webhook, then enter a name and description.
Choose the request content type. Prefer application/json so AIvis can parse a structured request.
Select one explicit public channel, or set a clear trigger word such as aivis.
Paste the AIvis callback URL into Callback URLs and save.
Copy the generated Mattermost Token and paste it into the AIvis bot configuration page.

Do not leave the Outgoing Webhook channel or trigger words too broad. Mattermost documents that an empty channel field can apply trigger words across all public channels in the team, and an empty trigger-word field can respond to all messages in the selected public channel.

Configure a Slash Command

Use a custom Slash Command when users should explicitly call the bot with /aivis, or when the bot needs to work in private channels or direct messages:

Open Product menu > Integrations > Slash Commands.
Select Add Slash Command.
Set the title, description, and unique trigger word, such as aivis. The trigger word must not include / or spaces.
Set Request URL to the AIvis callback URL.
Set the request method to POST.
Enable autocomplete if useful, and add an argument hint such as [question].
Save, copy the generated token, and paste it into the AIvis bot configuration page.

Configure a Bot Account

Use a Bot Account or Personal Access Token only when AIvis needs to proactively call the Mattermost REST API to post, reply, send direct messages, or inspect channel information.

Confirm Bot Accounts and the required Personal Access Tokens settings are enabled in the System Console.
Create a dedicated Bot Account, such as aivis-bot. Do not grant System Admin unless it has passed a separate security review.
Add the bot to the allowed teams and channels.
Copy the generated bot access token and save it in protected AIvis credentials.
Post a minimal test response from the bot in a test channel to confirm identity, channel, and permission behavior.

Configure AIvis

Open the Mattermost bot configuration page in the AIvis Admin panel and fill the fields that match the selected integration method:

AIvis field	Mattermost source	Notes
Mattermost Site URL	Mattermost Site URL	Used for source links or Mattermost API calls.
Callback URL	Generated by AIvis	Paste it into the Outgoing Webhook Callback URLs field or Slash Command Request URL field.
Webhook / Command Token	Generated by the Mattermost Outgoing Webhook or Slash Command	Validates that requests came from Mattermost.
Bot Access Token	Bot Account or Personal Access Token	Fill only if AIvis must call the Mattermost REST API proactively.
Allowed Team / Channel	Mattermost team, channel, or internal approval record	Limits the sources the bot may respond to.
Default Agent / Knowledge Scope	AIvis configuration	Controls which knowledge and tools the bot calls by default.

After saving, confirm the bot is enabled and record the callback URL, Mattermost integration name, token owner, and operational owner.

Verification

Ask a normal question in a test channel or direct message and review the reply.
If using an Outgoing Webhook, test both matching and non-matching trigger words.
If using a Slash Command, test /aivis question, empty arguments, and invalid arguments.
Validate denial from an unauthorized channel, unauthorized user, or request without a bound Agent.
Confirm AIvis tracing records Mattermost source, team, channel, user, trigger method, response result, and errors.
After rotating a webhook token, command token, or bot token, save the AIvis configuration again and repeat the test.

Troubleshooting

Symptom	What to check
Mattermost does not show the Integrations menu	Confirm a System Admin enabled the required integration feature and allowed the current user to create integrations.
Outgoing Webhook does not trigger	Confirm the channel is public, the trigger word matches, and the channel or trigger-word rule is not too narrow.
Slash Command has no response	Confirm the Request URL is the AIvis callback URL, the request method is `POST`, and the Mattermost server can reach that URL.
AIvis receives the request but validation fails	Confirm the Webhook / Command Token is correct, is not a token ID, and has no extra spaces.
Bot cannot post	Confirm the bot is in the target team/channel, the token is valid, and the bot can post to the target channel.
Private channels or DMs do not work	Do not use an Outgoing Webhook. Use a Slash Command or Bot Account + REST API instead.
Users can search content they should not see	Restrict AIvis access groups, default Agent, knowledge scope, or the Mattermost source allowlist.

Security and maintenance

Use separate Mattermost integrations and tokens for production, staging, and demos.
Do not use a System Admin personal token as the bot credential.
Rotate Outgoing Webhook, Slash Command, and Bot Account tokens regularly and track token owners.
Disable unused webhooks, commands, or bot accounts before disabling the AIvis-side bot.
Revalidate denial paths and traces whenever channels, teams, owners, or access boundaries change.