> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.alephant.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server. # Mattermost Bot > Configure a Mattermost bot entry while controlling channels, tokens, and audit boundaries. 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](https://developers.mattermost.com/integrate/webhooks/outgoing/). | | Slash Command Token | In **Product menu > Integrations > Slash Commands**, create the custom command and copy the generated token. See [Mattermost Developers: Custom slash commands](https://developers.mattermost.com/integrate/slash-commands/custom/). | | 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](https://developers.mattermost.com/integrate/reference/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](https://developers.mattermost.com/integrate/reference/personal-access-token/). | | 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](https://docs.mattermost.com/administration-guide/configure/integrations-configuration-settings.html). | ## Configure an Outgoing Webhook Use an Outgoing Webhook when the bot should listen for trigger words in public channels: 1. Open **Product menu > Integrations > Outgoing Webhooks**. 2. Select **Add Outgoing Webhook**, then enter a name and description. 3. Choose the request content type. Prefer `application/json` so AIvis can parse a structured request. 4. Select one explicit public channel, or set a clear trigger word such as `aivis`. 5. Paste the AIvis callback URL into **Callback URLs** and save. 6. 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: 1. Open **Product menu > Integrations > Slash Commands**. 2. Select **Add Slash Command**. 3. Set the title, description, and unique trigger word, such as `aivis`. The trigger word must not include `/` or spaces. 4. Set **Request URL** to the AIvis callback URL. 5. Set the request method to `POST`. 6. Enable autocomplete if useful, and add an argument hint such as `[question]`. 7. 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. 1. Confirm **Bot Accounts** and the required **Personal Access Tokens** settings are enabled in the System Console. 2. Create a dedicated Bot Account, such as `aivis-bot`. Do not grant System Admin unless it has passed a separate security review. 3. Add the bot to the allowed teams and channels. 4. Copy the generated bot access token and save it in protected AIvis credentials. 5. 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 1. Ask a normal question in a test channel or direct message and review the reply. 2. If using an Outgoing Webhook, test both matching and non-matching trigger words. 3. If using a Slash Command, test `/aivis question`, empty arguments, and invalid arguments. 4. Validate denial from an unauthorized channel, unauthorized user, or request without a bound Agent. 5. Confirm AIvis tracing records Mattermost source, team, channel, user, trigger method, response result, and errors. 6. 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. ## Official references * [Mattermost Developers: Bot accounts](https://developers.mattermost.com/integrate/reference/bot-accounts/) * [Mattermost Developers: Personal access tokens](https://developers.mattermost.com/integrate/reference/personal-access-token/) * [Mattermost Developers: Outgoing webhooks](https://developers.mattermost.com/integrate/webhooks/outgoing/) * [Mattermost Developers: Slash commands](https://developers.mattermost.com/integrate/slash-commands/) * [Mattermost Developers: Custom slash commands](https://developers.mattermost.com/integrate/slash-commands/custom/) * [Mattermost admin docs: Integrations configuration settings](https://docs.mattermost.com/administration-guide/configure/integrations-configuration-settings.html) ## Related pages * [Agents](/aivis/agents/agents) * [Users, Groups, and Roles](/aivis/governance/users-and-groups) * [Tracing](/aivis/governance/tracing)