Mattermost

Mattermost channel

Since 3.1.0 · Contributed by Andrew Turbay (@turbay-a) in PR #166 · How it works underneath: Teams and Mattermost — Developer Guide

A Mattermost support channel where each post opens a ticket. Analysts reply from the ticket, and the answer appears in the thread under the customer's post — the same way the Slack channel works — so the customer simply replies in the thread and the conversation carries on.

Anyone who can see the support channel can read its threads, as with Slack. Use a channel whose members are the people you support.

---

What you need

• A system admin on the Mattermost server, once, to enable bot accounts and outgoing webhooks.
• A support channel (public — outgoing webhooks only work on public channels).
• A public address for this FreeITSM install, set on Tickets → Settings → Messaging, that the Mattermost server can reach.

1. Enable bot accounts and outgoing webhooks

System Console → Integrations: switch on Enable Bot Account Creation and Enable Outgoing Webhooks. If Mattermost later refuses FreeITSM's address as a callback, allow it under System Console → Environment (allowed untrusted internal connections).

2. Create the bot

Integrations → Bot Accounts → Add Bot Account, for example servicedesk, with Post All and Read. Copy its access token (shown once) and add the bot to the support channel.

3. Note the channel and server

Open the support channel → View Info and copy its ID (26 letters and digits). Note the server address, for example https://mattermost.example.com.

4. Create the outgoing webhook

Integrations → Outgoing Webhooks → Add:

• Channel: the support channel
• Trigger words: leave empty, so every post is sent
• Callback URL: the webhook URL from FreeITSM's channel list
• Content type: application/x-www-form-urlencoded (the default)

Save and copy the webhook's token.

5. Add the channel in FreeITSM

Tickets → Settings → Messaging → Add channel, provider Mattermost: Server address, Support channel ID, Bot access token and Outgoing webhook token. Save, then Test connection.

6. Try it

Post in the support channel as a customer. A ticket appears with the Mattermost origin. Reply from the ticket, and the answer appears in the thread under the post.

---

Good to know

• Replies are in the thread. Mattermost's outgoing webhooks never see direct messages, so a reply by DM would leave the customer's answer unheard. Answering in the thread keeps the whole conversation where FreeITSM can follow it.
• Matched to the person you already have. FreeITSM asks Mattermost for the person's email. If it's verified and someone in FreeITSM has it, the ticket is theirs, with their other tickets and their company. Otherwise they become a contact with their real name. An unverified email is never trusted: a server that lets people sign up without proving their address would otherwise let anyone file chats as anyone. If your server hides email addresses from the bot, everyone simply becomes a named contact.
• One ticket per person at a time. All of a customer's posts go to their open ticket until it's closed — a second question while the first is open joins it.
• Files. Files you attach are uploaded and posted in the thread — any type. Files a customer posts aren't downloaded, because the outgoing webhook doesn't include them.
• One support channel per configuration. Add another channel entry for another team.
• Ratings. If Tickets → Settings → CSAT → Ask chat customers in their chat is on, the customer gets their rating question in the thread with five buttons.
• No read receipts.

Troubleshooting

Symptom	Likely cause
Test connection: 401	The bot access token is wrong or revoked.
Test connection: 404	The server address is wrong, or a proxy rewrites /api/v4.
Posts don't create tickets	The webhook is on a different channel, its callback URL is wrong, or the token in FreeITSM doesn't match.
Replies don't appear	The bot isn't a member of the support channel.
Callback URL refused by Mattermost	Allow FreeITSM's host under System Console → Environment.

---

Related: Microsoft Teams channel · Slack channel · Telegram channel · Teams and Mattermost — Developer Guide