Mattermost Logo
We're hiring!
Edit on GitHub

Manifest Reference at Mattermost

The plugin manifest defines the metadata required to load and present your plugin. The manifest file should be named plugin.json or plugin.yaml and placed in the top of your plugin bundle.

Example plugin.json:

{
  "id": "com.mycompany.myplugin",
  "name": "My Plugin",
  "description": "This is my plugin",
  "homepage_url": "https://example.com",
  "support_url": "https://example.com/support",
  "release_notes_url": "https://example.com/releases/v0.0.1",
  "icon_path": "assets/logo.svg",
  "version": "0.1.0",
  "min_server_version": "5.6.0",
  "server": {
    "executables": {
      "linux-amd64": "server/dist/plugin-linux-amd64",
      "darwin-amd64": "server/dist/plugin-darwin-amd64",
      "windows-amd64": "server/dist/plugin-windows-amd64.exe"
    }
  },
  "webapp": {
      "bundle_path": "webapp/dist/main.js"
  },
  "settings_schema": {
    "header": "Some header text",
    "footer": "Some footer text",
    "settings": [{
      "key": "someKey",
      "display_name": "Enable Extra Feature",
      "type": "bool",
      "help_text": "When true, an extra feature will be enabled!",
      "default": "false"
    }]
  },
  "props": {
    "someKey": "someData"
  }
}

Table of Contents

Documentation

  • id - String

    The id is a globally unique identifier that represents your plugin. Ids must be at least 3 characters, at most 190 characters and must match ^[a-zA-Z0-9-_\.]+$. Reverse-DNS notation using a name you control is a good option, e.g. "com.mycompany.myplugin".

  • name - String

    The name to be displayed for the plugin.

  • description - String

    A description of what your plugin is and does.

  • homepage_url - String

    HomepageURL is an optional link to learn more about the plugin.

  • support_url - String

    SupportURL is an optional URL where plugin issues can be reported.

  • release_notes_url - String

    ReleaseNotesURL is an optional URL where a changelog for the release can be found.

  • icon_path - String

    A relative file path in the bundle that points to the plugins svg icon for use with the Plugin Marketplace. This should be relative to the root of your bundle and the location of the manifest file. Bitmap image formats are not supported.

  • version - String

    A version number for your plugin. Semantic versioning is recommended: http://semver.org

  • min_server_version - String

    The minimum Mattermost server version required for your plugin.

    Minimum server version: 5.6

  • server - Object

    Server defines the server-side portion of your plugin.

    • executables - Dict

      AllExecutables are the paths to your executable binaries, specifying multiple entry points for different platforms when bundled together in a single plugin.

    • executable - String

      Executable is the path to your executable binary. This should be relative to the root of your bundle and the location of the manifest file.

      On Windows, this file must have a ".exe" extension.

      If your plugin is compiled for multiple platforms, consider bundling them together and using the Executables field instead.

  • backend - Object

    Backend is a deprecated flag for defining the server-side portion of your plugin. Going forward, use Server instead.

    • executables - Dict

      AllExecutables are the paths to your executable binaries, specifying multiple entry points for different platforms when bundled together in a single plugin.

    • executable - String

      Executable is the path to your executable binary. This should be relative to the root of your bundle and the location of the manifest file.

      On Windows, this file must have a ".exe" extension.

      If your plugin is compiled for multiple platforms, consider bundling them together and using the Executables field instead.

  • webapp - Object

    If your plugin extends the web app, you'll need to define webapp.

    • bundle_path - String

      The path to your webapp bundle. This should be relative to the root of your bundle and the location of the manifest file.

  • settings_schema - Object

    To allow administrators to configure your plugin via the Mattermost system console, you can provide your settings schema.

    • header - String

      Optional text to display above the settings. Supports Markdown formatting.

    • footer - String

      Optional text to display below the settings. Supports Markdown formatting.

    • settings - Array

      A list of setting definitions.

      • key - String

        The key that the setting will be assigned to in the configuration file.

      • display_name - String

        The display name for the setting.

      • type - String

        The type of the setting.

        "bool" will result in a boolean true or false setting.

        "dropdown" will result in a string setting that allows the user to select from a list of pre-defined options.

        "generated" will result in a string setting that is set to a random, cryptographically secure string.

        "radio" will result in a string setting that allows the user to select from a short selection of pre-defined options.

        "text" will result in a string setting that can be typed in manually.

        "longtext" will result in a multi line string that can be typed in manually.

        "number" will result in in integer setting that can be typed in manually.

        "username" will result in a text setting that will autocomplete to a username.

        "custom" will result in a custom defined setting and will load the custom component registered for the Web App System Console.

      • help_text - String

        The help text to display to the user. Supports Markdown formatting.

      • regenerate_help_text - String

        The help text to display alongside the "Regenerate" button for settings of the "generated" type.

      • placeholder - String

        The placeholder to display for "generated", "text", "longtext", "number" and "username" types when blank.

      • default - Interface

        The default value of the setting.

      • options - Array

        For "radio" or "dropdown" settings, this is the list of pre-defined options that the user can choose from.

        • display_name - String

          The display name for the option.

        • value - String

          The string value for the option.

  • props - Dict

    Plugins can store any kind of data in Props to allow other plugins to use it.

  • required_configuration - Object

    RequiredConfig defines any required server configuration fields for the plugin to function properly.

    Use the plugin helpers CheckRequiredServerConfiguration method to enforce this.

    Config fields support the 'access' tag with the following values corresponding to the suffix of the associated PERMISSION_SYSCONSOLE_*_* permission Id: 'about', 'reporting', 'user_management_users', 'user_management_groups', 'user_management_teams', 'user_management_channels', 'user_management_permissions', 'environment', 'site', 'authentication', 'plugins', 'integrations', 'compliance', 'plugins', and 'experimental'. They grant read and/or write access to the config field to roles without PERMISSION_MANAGE_SYSTEM.

    By default config values can be written with PERMISSION_MANAGE_SYSTEM, but if ExperimentalSettings.RestrictSystemAdmin is true and the access tag contains the value 'write_restrictable', then even PERMISSION_MANAGE_SYSTEM does not grant write access.

    PERMISSION_MANAGE_SYSTEM always grants read access.

    Config values with the access tag 'cloud_restrictable' mean that are marked to be filtered when it's used in a cloud licensed environment with ExperimentalSettings.RestrictedSystemAdmin set to true.

    Example:

    type HairSettings struct {
        // Colour is writeable with either PERMISSION_SYSCONSOLE_WRITE_REPORTING or PERMISSION_SYSCONSOLE_WRITE_USER_MANAGEMENT_GROUPS.
        // It is readable by PERMISSION_SYSCONSOLE_READ_REPORTING and PERMISSION_SYSCONSOLE_READ_USER_MANAGEMENT_GROUPS permissions.
        // PERMISSION_MANAGE_SYSTEM grants read and write access.
        Colour string `access:"reporting,user_management_groups"`
    
        // Length is only readable and writable via PERMISSION_MANAGE_SYSTEM.
        Length string
    
        // Product is only writeable by PERMISSION_MANAGE_SYSTEM if ExperimentalSettings.RestrictSystemAdmin is false.
        // PERMISSION_MANAGE_SYSTEM can always read the value.
        Product bool `access:write_restrictable`
    }