Skip to main content
Python Software Foundation 20th Year Anniversary Fundraiser  Donate today!

A python based bot for Mattermost with its own webhook server.

Project description

PyPI Travis-Ci Codacy Maintainability Python Support Mattermost License

Documentation available at Read the Docs.


A Python based chat bot for Mattermost. The code for this bot was heavily re-factored in v2.0.0 and will only work with Python 3.8 or higher. For Python 2 support, please use v1.3.9 or lower.


  • <input type="checkbox" checked="" disabled="" /> Based on Mattermost WebSocket API(V4.0.0)
  • <input type="checkbox" checked="" disabled="" /> Simple plugins mechanism
  • <input type="checkbox" checked="" disabled="" /> Concurrent message handling
  • <input type="checkbox" checked="" disabled="" /> Attachment support
  • <input type="checkbox" checked="" disabled="" /> Auto-reconnect to Mattermost after connection loss
  • <input type="checkbox" checked="" disabled="" /> Python 2 compatible (<=v1.3.9 only)
Additional features in v2.0.0:
  • <input type="checkbox" checked="" disabled="" /> Multi-threading and asyncio execution
  • <input type="checkbox" checked="" disabled="" /> Integrated webhook server
  • <input type="checkbox" checked="" disabled="" /> Support for click functions
  • <input type="checkbox" checked="" disabled="" /> Job scheduling
  • <input type="checkbox" checked="" disabled="" /> Compatible with Python 3.8+ only


Mattermost mmpy_bot
>= 4.0 > 1.2.0
< 4.0 unsupported


v2.0.0 refactor
pip install mmpy_bot
v1.3.9 legacy
pip install mmpy_bot==1.3.9

Usage (v2.0.0)


First you need to create a bot account on your Mattermost server. Note: Enable Bot Account Creation must be enabled under System Console

  1. Login to your Mattermost server as a user with Administrative privileges.
  2. Navigate to Integrations -> Bot Accounts -> Add Bot Account
  3. Fill in the configuration options and upon creation take note of the Access Token

Note that some API functions, such as ephemeral message replies, will require the bot to be part of the System Admin group, however most API functions will work with a regular Member account role. Just be aware that if some API functions are not working, it may be due to a lack of appropriate permissions.

Configure and run the bot

Create an entrypoint file (or copy the one provided), that defines your Mattermost server and bot account settings and imports the desired modules.


#!/usr/bin/env python

from mmpy_bot import Bot, Settings
from my_plugin import MyPlugin

bot = Bot(
        MATTERMOST_URL = "",
        MATTERMOST_PORT = 443,
        BOT_TOKEN = "a69155mvlsobcnqpfdceqihaa",
        BOT_TEAM = "test",
        SSL_VERIFY = True,
    ),  # Either specify your settings here or as environment variables.
    plugins=[MyPlugin()],  # Add your own plugins here.

Set the executable bit on the entrypoint file (i.e. chmod +x and start your bot from the command prompt. Now you can talk to your bot in your Mattermost client!

In order to get the most out of your bot, you will need to write your own plugins. Refer to the Plugins Documentation to get started.

Talk to us

The primary channel for communication is GitHub via Issues or Pull requests but you may also find some of us in Discord for some real-time interaction.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for mmpy-bot, version 2.0.2
Filename, size File type Python version Upload date Hashes
Filename, size mmpy_bot-2.0.2-py3-none-any.whl (26.5 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size mmpy_bot-2.0.2.tar.gz (23.9 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page