Contact Us
Mattermost Integration

How to Connect Mattermost to NIVA — Self-Hosted Integration Guide

10–20 minutes Medium 6 steps

Connect NIVA to your self-hosted Mattermost server. NIVA uses Mattermost's Outgoing Webhooks to receive messages and the REST API v4 to send replies — no external dependencies needed.

Before you begin
NIVA botmaster account with a bot configured
Mattermost server with System Admin access
Mattermost version 5.0 or higher
Step-by-step setup

Enable Bot Accounts

  • Log in as System Admin
  • Go to System Console → Integrations → Bot Accounts
  • Toggle Enable Bot Account Creation ON
  • Click Save

Create a Bot Account

  • Go to Integrations → Bot Accounts → Add Bot Account
  • Set Username to something memorable (e.g. niva-bot)
  • Set Display Name and optionally an avatar
  • Set Role to Member
  • Click Create Bot Account
  • Copy the Access Token immediately — it is only shown once
Note down the bot username — you need it to prevent reply loops.

Configure in NIVA Botmaster

  • Open your NIVA botmaster → Omnichannel
  • Click Configure on the Mattermost card
  • Enter your Server URL (e.g. https://mattermost.yourcompany.com)
  • Paste the Bot Access Token
  • Enter the Bot Username (e.g. niva-bot)
  • Leave Webhook Token blank for now, click Save & Activate
  • Copy the Webhook URL

Create an Outgoing Webhook

  • In Mattermost → Integrations → Outgoing Webhooks → Add Outgoing Webhook
  • Set Content Type to application/x-www-form-urlencoded
  • Select channel(s) or leave blank for all channels
  • Paste your NIVA Webhook URL into Callback URLs
  • Click Save
  • Copy the Token shown
Content Type must be form-encoded, not JSON.

Add Webhook Token to NIVA

  • Back in NIVA Omnichannel → Edit the Mattermost config
  • Paste the token into Outgoing Webhook Token
  • Click Save & Activate

Add Bot to Channel and Test

  • Open target channel → click channel name → Add Members
  • Search for your bot username and add it
  • Send a message — bot should reply in 2–3 seconds
Troubleshooting
No reply at all
Check outgoing webhook URL is correct and server is reachable.
Token mismatch in logs
Webhook token doesn't match — re-copy from outgoing webhook settings.
Bot replies to itself
Bot Username field not set in NIVA config.
channel_id missing
Content Type must be application/x-www-form-urlencoded, not JSON.
Ready to connect Mattermost?
Open your NIVA botmaster → Omnichannel → Configure
Open Omnichannel