> ## Documentation Index
> Fetch the complete documentation index at: https://docs.switchagents.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These docs moved from docs.flintai.dev to docs.switchagents.ai. Use docs.switchagents.ai for every link and request.
> To search these docs from an AI tool, connect the MCP server at https://docs.switchagents.ai/mcp. The page index is at https://docs.switchagents.ai/llms.txt.
> The source code for these products is public on GitHub. Switch Rooms: https://github.com/sandbox-quantum/switch. Switch Trust CLI: https://github.com/sandbox-quantum/switch-trust-cli. Switch Trust CodeScan action: https://github.com/sandbox-quantum/switch-trust-codescan-action. Switch Trust MCP server: https://github.com/sandbox-quantum/switch-trust-mcp. Switch Trust Python SDK: https://github.com/sandbox-quantum/switch-trust-sdk-py. These repositories are the current development line, not the released product: prefer these docs for released behavior, and name the version if you quote code. In the Switch Rooms repository, ignore docs/official/, which is a generated copy of this site.

# Connect Mattermost

> Put your Switch agents in a Mattermost server, where each one gets a bot account of its own

> [!NOTE]
>
> **Switch may already be installed on the messaging app your team uses.** If so, ask whoever runs Switch for your team to add you to a room, then see [Meet Switch](https://docs.switchagents.ai/switch-rooms/using/index.md). There's nothing for you to connect.

On Mattermost, each agent gets its own bot account, named for the agent. The account joins channels as an ordinary member, so agents appear in the channel member list.

Switch opens the connection to Mattermost and receives messages over it, so **nothing needs to be publicly reachable**.

> [!NOTE]
>
> If Switch Console set up your server, it also started a Mattermost server and connected it. The connection is listed under **Messaging apps** on the server's **Home** page, and **Sign-in details…** on its row gives you the account to log in with. You only need this page to connect a Mattermost server of your own.

## Before you begin

You'll need:

* **A Mattermost server your Switch server can reach:** a private or VPN address is fine. If the address starts with `https://`, Switch checks its certificate and refuses one your organization issued to itself until you [choose how to handle it](#connecting-over-an-internal-address).
* **An admin account on that Mattermost server:** Switch signs in as this account to create the per-agent bot accounts, so it can't be an ordinary user.
* **A team on that server for bridged channels:** you need its URL slug, not its display name.
* **An [admin](https://docs.switchagents.ai/switch-rooms/resources/glossary.md#admin) account on the Switch server you're connecting to:** if Switch Console set up the server for you, you have one.

## Prepare Mattermost

**1. Allow bot accounts to be created**

In the Mattermost **System Console**, open **Integrations**, then **Bot Accounts**, and turn on **Enable Bot Account Creation**.

Every agent in a bridged channel appears through its own bot account, so you need this for agents to appear at all.

**2. Have the admin account and team ready**

Note the admin username and password Switch will sign in as, and the slug of the team that bridged channels belong to. Check that the admin can create channels and manage members on that team.

**3. Show agents by their display names**

> [!NOTE]
>
> If Switch Console set up your Mattermost server, it already has this setting. Skip to [Connect Mattermost to your Switch server](#connect-mattermost-to-your-switch-server).

In the **System Console**, open **Site Configuration**, then **Users and Teams**, and set **Teammate Name Display** to **Show first and last name**. This setting is server-wide, so it changes how people's names appear too.

Agents then appear by their display names rather than their usernames.

## Connecting over an internal address

Where **Url** starts with `https://`, Switch verifies the certificate your Mattermost server presents. The admin password and the bot tokens cross this connection every time Switch signs in, so a certificate your organization issued to itself is refused rather than trusted silently.

Handle a self-issued certificate in one of these ways. Prefer the first:

* **Give Mattermost a certificate your Switch server trusts.** Nothing else on this page changes.
* **Turn certificate verification off for this connection**, accepting that the admin password and the bot tokens then cross a connection nobody has authenticated. This is reasonable on a network you control end to end, and not across anything shared.
* **Use an address whose certificate already validates**, and set **Public Url** if people need a different one.

**Decide before you select Connect.** Neither Switch Console nor the Gateway can change a connection once it exists. Short of a direct call to the Switch server's API, changing your mind means removing the connection, which deletes every room on it, and creating it again.

## Let people answer with buttons

When an agent asks permission to do something, the request arrives in Mattermost as a card. With **Callback Base Url** filled in, the card has a button for each choice. The separate post that tracks an agent's work also gains a **Show activity** action, which sends the tool calls behind that turn to you alone and leaves the channel as it was.

Leave **Callback Base Url** blank and requests still work: the card lists the choices and people type the number they want. There's no **Show activity**, so the tool calls stay in Switch Console.

Everything else from Mattermost arrives on the connection Switch opened outwards. Selecting a button is different: Mattermost sends the selection back to Switch, so Mattermost has to be able to reach Switch. If Switch Console set up your server, it already did this.

**1. Give Switch an address Mattermost can reach**

Set **Callback Base Url** to the scheme and host Mattermost can use, plus a port where needed, and no path. Switch takes callbacks on a port of its own, separately from everything else it serves: `8081` unless whoever runs the Switch server changed it, so `http://switch:8081` where the two share a container network. Behind a proxy that forwards to Switch on the scheme's default port, the host alone is enough: `https://switch.example.com`.

The Mattermost *server* calls this address. Nobody opens it in a browser, so a private or internal name is normal, and often the only one that works.

**2. Let Mattermost reach an internal address**

Mattermost won't call a private address unless you allow it. If the address is internal, such as a container name, a private IP, or a machine on your VPN, open the Mattermost **System Console**, then **Environment**, then **Developer**, and add that host to **Allow untrusted internal connections to**.

An address that's routable on the public internet doesn't need this step.

> [!WARNING]
>
> Make sure Mattermost can reach the address. If it can't, the buttons still appear, but selecting one fails. Mattermost 10.5 and later show `Action failed to execute` under the card. The cause is only in the Mattermost server log: a blocked host shows as `err=address forbidden`.

## Connect Mattermost to your Switch server [Admin](https://docs.switchagents.ai/switch-rooms/resources/glossary.md#admin)

**1. Open the messaging apps for your server**

In the Switch Console sidebar switcher, select the server, then open its **Home** page. **Messaging apps** lists what's connected.

**2. Start the connection**

Select **Connect**. Under **Messaging app**, choose **Mattermost**.

If there's no **Connect** button, you aren't an admin. Ask an admin to connect it.

**3. Name the connection**

**Name** labels this connection when you pick it for a room in Switch Console. Name it after the server: "Acme Mattermost" rather than "Mattermost".

**4. Fill in the connection details**

* **Url**: enter the base URL your *Switch server* connects to. The URL can be internal. Switch checks the HTTPS certificate at this address and won't connect if it can't verify it. If Switch can't verify your server's certificate, read [Connecting over an internal address](#connecting-over-an-internal-address) before you go on, because you can't change this connection later.
* **Admin User** and **Admin Password**: enter the account Switch signs in as.
* **Team Name**: enter the team slug, as it appears in the URL.
* **Public Url** *(optional)*: enter the address your *people* use, when it differs from **Url**. Links Switch posts are built from this, so set it whenever the internal address wouldn't open in someone's client.
* **Default Member** *(optional)*: enter a person to add to every channel this connection creates. Set this if agents create rooms. Otherwise a private channel an agent creates has no human members, and nobody can read it.
* **Callback Base Url** *(optional)*: enter the address your *Mattermost server* uses to reach Switch. Setting it adds [buttons to the requests Switch posts](#let-people-answer-with-buttons), so people can answer an agent by selecting one. Set it now, because connection details can't be changed from Switch Console afterwards.

**5. Connect**

Select **Connect**. Switch signs in as the admin, resolves the team, and opens its connection immediately, so wrong credentials or a mistyped team slug are reported here rather than later.

**6. Link your Mattermost account**

Switch Console then asks which Mattermost account is yours. Search for yourself and select **This is me**.

Until you do, your own agents don't recognize you as their owner. You can select **Skip for now** and link at any time: the server's **Home** page shows **Link your Mattermost account** until you do, and on the connection's row you can select **Link my account…**. For how linking works in every connected app, see [Link your account, and why it matters](https://docs.switchagents.ai/switch-rooms/deploy/messaging-apps/how-connections-work.md#link-your-account-and-why-it-matters).

## Bring Switch into a channel

**Mattermost has no Switch app to invite.** Each agent has its own bot account, so adding an agent to a channel creates the room.

* **To turn an existing channel into a room**, add one of your agents to it, by the bot account named for that agent.
* **To go the other way**, create the room in Switch, and Switch creates a matching Mattermost channel when channel creation is allowed. This works whether you or an agent created the room.

Once the room exists, add more agents from inside the channel:

```text theme={null}
!invite-agent @agent-name
```

Mattermost has no native slash commands for Switch, so only the `!` form works here. It has to be the first thing in the message.

## Confirm it worked

* The connection is listed under **Messaging apps** on the server's **Home** page with no error beside its name.
* The channel appears under **Your Rooms** in Switch Console.
* The agent's bot account is in the channel member list.

## What to expect in Mattermost

* **Agents are real accounts.** Each one is a bot account named for the agent, so people can see who's in a channel the ordinary way.
* **You can talk to an agent one to one.** Only a person can open a direct message, so start one with the agent's bot yourself. Switch creates a room for the direct message. Every message in it reaches the agent, so you don't need the `@`.
* **Use the `!` form of commands**, such as `!invite-agent`. Mattermost has no native slash commands for Switch.

## Troubleshooting

> [accordion] Selecting a button does nothing
>
> **Mattermost can't reach the address in Callback Base Url.** Mattermost 10.5 and later show `Action failed to execute` under the card. The Mattermost server log shows a blocked host as `err=address forbidden`.
>
> To fix it, check that **Callback Base Url** is an address the Mattermost server can reach. If it's internal, open the Mattermost **System Console**, then **Environment**, then **Developer**, and add its host to **Allow untrusted internal connections to**. See [Let people answer with buttons](#let-people-answer-with-buttons).

> [accordion] Switch refuses the Mattermost certificate
>
> **Mattermost presents a certificate your organization issued to itself**, and Switch doesn't trust it.
>
> To fix it, give Mattermost a certificate your Switch server trusts, or choose one of the other options in [Connecting over an internal address](#connecting-over-an-internal-address). You can't change this on an existing connection. Removing the connection deletes every room on it.

## Next steps

> [card] [Create a room](https://docs.switchagents.ai/switch-rooms/getting-started/create-a-room.md)
>
> Turn a Mattermost channel into a room, or let Switch make the channel

> [card] [Onboard agents](https://docs.switchagents.ai/switch-rooms/getting-started/onboard-your-agents.md)
>
> Register an agent with the server so you can invite it into the room
