Skip to main content
The nao Mattermost bot brings your analytics agent directly into Mattermost, allowing your team to ask questions and get insights without leaving their workspace.
nao Mattermost Bot Interface
When configured, the nao Mattermost bot:
  • Runs against your own self-hosted Mattermost server
  • Connects as a bot account with a personal access token, over a persistent WebSocket
  • Answers mentions in channels, and every message in direct messages
  • Returns answers with SQL queries, data tables, and visualizations
  • Streams the answer into a single message that is edited as the answer grows
The Mattermost bot uses the same agent context, rules, models, and capabilities as your web chat interface. Any improvements to your agent automatically benefit Mattermost users.
Each nao project connects its own bot, so several projects can live on the same Mattermost server.

​
Setup

​
Step 1: Create a Bot Account in Mattermost

  1. In Mattermost, go to the System Console → Integrations → Bot Accounts and set Enable Bot Account Creation to true. It is off by default.
  2. Go to Integrations → Bot Accounts → Add Bot Account, create the bot, and copy the token. It is shown only once, at creation.
  3. Add the bot to the team first, then to each channel where it should answer.
Adding the bot straight to a channel does not work until it is a member of the team. Add it to the team first, then to the channels.
See the Mattermost bot accounts guide for more detail.

​
Step 2: Connect your Mattermost Bot to nao

  1. In nao, click on your profile → “Project” → “Mattermost”
  2. Fill in the Server URL (for example https://mattermost.example.com) and the Bot Token
  3. Click “Save”
  4. Choose the model used for Mattermost replies

​
Step 3: Turn on the Stop button

On the same settings page, turn on Enable interactive buttons. This adds a Stop button to the answer while nao is generating, so people can cut a long answer short. The button disappears on its own once the answer finishes. Buttons work by Mattermost calling back into nao over HTTP, so your Mattermost server must be able to reach nao. Two things commonly block that:
  1. The address is wrong. The address your Mattermost server uses to reach nao can differ from the one you use in your browser. That is what the optional Callback URL field is for — leave it blank unless buttons fail. For example, with Mattermost running in Docker on a laptop, the callback URL would be http://host.docker.internal:5005.
  2. The host is not allow-listed. Mattermost refuses calls to internal hosts unless you allow them.
Go to System Console → Environment → Developer → Allow untrusted internal connections to and add the host from your Callback URL. This is the most common reason buttons fail silently.
This step is optional. Everything except the Stop button works with the toggle off.

​
Step 4: Account Linking

People are linked automatically by their Mattermost email. If the email on someone’s Mattermost account matches their nao account, they are recognised on their first message and there is nothing to type. If the two emails do not match, they can link manually instead: send the bot a direct message with login <linking_code>. The linking code is on the Mattermost settings page, tucked behind a collapsible section.
Write login <linking_code> without a leading slash. Mattermost intercepts slash commands, so /login never reaches the bot.

​
Usage

Ask Questions In a channel, mention the bot:
The bot will:
  1. Process your question using the same agent as the web interface
  2. Generate SQL queries based on your context
  3. Execute queries against your connected databases
  4. Stream the answer into a single Mattermost message, editing it as the answer grows
  5. End the answer with a bold Open in nao link to the full conversation
Thread Conversations Once a thread exists, follow-ups inside it need no mention:
The first answer lands in the channel itself, and follow-up housekeeping messages go into a thread under it, so channels stay quiet. Direct messages are never threaded.
Direct Messages In a direct message the bot answers every message. No mention needed. Tables and formatting Mattermost supports full markdown, so answers come through with real tables, code blocks, bold text, and links. Charts are posted as images. Large tables are capped at about 20 rows, with a note pointing to the full result in nao. Feedback React to an answer with 👍 or 👎 and the vote is recorded in nao, the same as the thumbs in the web UI. Remove the reaction to remove the vote. What’s Next?

Admin Setup

Configure authentication, models, and messaging integrations

Chat Overview

Learn how the main chat interface works