Mattermostdriver documentation

See for the github repository.

You interact with this module mainly by using the Driver class. If you want to access information about the logged in user, like the user id, you can access them by using Driver.client.userid.


pip install mattermostdriver


from mattermostdriver import Driver

foo = Driver({
    Required options

    Instead of the login/password, you can also use a personal access token.
    If you have a token, you don't need to pass login/pass.
    'url': '',
    'login_id': '',
    'password': 'verySecret',
    'token': 'YourPersonalAccessToken',

    Optional options

    These options already have useful defaults or are just not needed in every case.
    In most cases, you won't need to modify these, especially the basepath.
    If you can only use a self signed/insecure certificate, you should set
    verify to False. Please double check this if you have any errors while
    using a self signed certificate!
    'scheme': 'https',
    'port': 8065,
    'basepath': '/api/v4',
    'verify': True,
    'mfa_token': 'YourMFAToken'

    If for some reasons you get regular timeouts after a while, try to decrease
    this value. The websocket will ping the server in this interval to keep the connection
    If you have access to your server configuration, you can of course increase the timeout
    'timeout': 30,

    Setting debug to True, will activate a very verbose logging.
    This also activates the logging for the requests package,
    so you can see every request you send.

    Be careful. This SHOULD NOT be active in production, because this logs a lot!
    Even the password for your account when doing driver.login()!
    'debug': False

Most of the requests need you to be logged in, so calling login()
should be the first thing you do after you created your Driver instance.
login() returns the raw response.
If using a personal access token, you still need to run login().
In this case, does not make a login request, but a `get_user('me')`
and sets everything up in the client.

You can make api calls by using calling `Driver.endpointofchoice`.
Using api[''] is deprecated for 5.0.0!

So, for example, if you used `Driver.api['users'].get_user('me')` before,
you now just do `Driver.users.get_user('me')`.
The names of the endpoints and requests are almost identical to
the names on the page.
API calls always return the json the server send as a response.

If the api request needs additional parameters
you can pass them to the function in the following way:
- Path parameters are always simple parameters you pass to the function

# - Query parameters are always passed by passing a `params` dict to the function

# - Request Bodies are always passed by passing an `options` dict or array to the function

# See the mattermost api documentation to see which parameters you need to pass.
    'team_id': 'some_team_id',
    'name': 'awesome-channel',
    'display_name': 'awesome channel',
    'type': 'O'

If you want to make a websocket connection to the mattermost server
you can call the init_websocket method, passing an event_handler.
Every Websocket event send by mattermost will be send to that event_handler.
See the API documentation for which events are available.

# To upload a file you will need to pass a `files` dictionary
channel_id = foo.channels.get_channel_by_name_and_team_name('team', 'channel')['id']
file_id = foo.files.upload_file(
    files={'files': (filename, open(filename))}

# track the file id and pass it in `create_post` options, to attach the file
    'channel_id': channel_id,
    'message': 'This is the important file',
    'file_ids': [file_id]})

# If needed, you can make custom requests by calling `make_request`
foo.client.make_request('post', '/endpoint', options=None, params=None, data=None, files=None, basepath=None)

# If you want to call a webhook/execute it use the `call_webhook` method.
# This method does not exist on the mattermost api AFAIK, I added it for ease of use.
foo.hooks.call_webhook('myHookId', options) # Options are optional


class mattermostdriver.Driver(options={'basepath': '/api/v4', 'debug': False, 'login_id': None, 'mfa_token': None, 'password': None, 'port': 8065, 'scheme': 'https', 'timeout': 30, 'token': None, 'url': 'localhost', 'verify': True}, client_cls=<class 'mattermostdriver.client.Client'>)[source]

Contains the client, api and provides you with functions for login, logout and initializing a websocket connection.

default_options = {'basepath': '/api/v4', 'debug': False, 'login_id': None, 'mfa_token': None, 'password': None, 'port': 8065, 'scheme': 'https', 'timeout': 30, 'token': None, 'url': 'localhost', 'verify': True}
Required options
  • url
  • login_id
  • password
  • scheme (‘https’)
  • port (8065)
  • verify (True)
  • timeout (30)
  • mfa_token (None)
  • debug (False)
Should not be changed
  • basepath (‘/api/v4’) - unlikely this would do any good
init_websocket(event_handler, websocket_cls=<class 'mattermostdriver.websocket.Websocket'>)[source]

Will initialize the websocket connection to the mattermost server.

This should be run after login(), because the websocket needs to make an authentification.

See for which websocket events mattermost sends.

Example of a really simple event_handler function

def my_event_handler(message):
Parameters:event_handler (Function(message)) – The function to handle the websocket events. Takes one argument.
Returns:The event loop

Logs the user in.

The log in information is saved in the client
  • userid
  • username
  • cookies
Returns:The raw response from the request

Log the user out.

Returns:The JSON response from the server

Deprecated since version 4.0.2.

Use the endpoints directly instead.

Returns:dictionary containing the endpoints
Return type:dict

Api endpoint for users

Returns:Instance of Users

Api endpoint for teams

Returns:Instance of Teams

Api endpoint for channels

Returns:Instance of Channels

Api endpoint for posts

Returns:Instance of Posts

Api endpoint for files

Returns:Instance of Files

Api endpoint for preferences

Returns:Instance of Preferences

Api endpoint for emoji

Returns:Instance of Emoji

Api endpoint for system

Returns:Instance of System

Api endpoint for webhooks

Returns:Instance of Webhooks

Api endpoint for compliance

Returns:Instance of Compliance

Api endpoint for cluster

Returns:Instance of Cluster

Api endpoint for brand

Returns:Instance of Brand

Api endpoint for oauth

Returns:Instance of OAuth

Api endpoint for saml

Returns:Instance of SAML

Api endpoint for ldap

Returns:Instance of LDAP

Api endpoint for elasticsearch

Returns:Instance of Elasticsearch

Api endpoint for data_retention

Returns:Instance of DataRetention
class mattermostdriver.Client(options)[source]
Returns:The user id of the logged in user
Returns:The username of the logged in user. If none, returns an emtpy string.
Returns:The cookie given on login
Returns:The token for the login

Exceptions that api requests can throw

class mattermostdriver.exceptions.InvalidOrMissingParameters(*args, **kwargs)[source]

Raised when mattermost returns a 400 Invalid or missing parameters in URL or request body

class mattermostdriver.exceptions.NoAccessTokenProvided(*args, **kwargs)[source]

Raised when mattermost returns a 401 No access token provided

class mattermostdriver.exceptions.NotEnoughPermissions(*args, **kwargs)[source]

Raised when mattermost returns a 403 Do not have appropriate permissions

class mattermostdriver.exceptions.ResourceNotFound(*args, **kwargs)[source]

Raised when mattermost returns a 404 Resource not found

class mattermostdriver.exceptions.ContentTooLarge(*args, **kwargs)[source]

Raised when mattermost returns a 413 Content too large

class mattermostdriver.exceptions.FeatureDisabled(*args, **kwargs)[source]

Raised when mattermost returns a 501 Feature is disabled

Indices and tables