All Apps should define a manifest (godoc) as a JSON object. The fields of the manifest are described in the following table:
Name | Type | Description |
---|---|---|
app_id |
string | ID for your App. |
homepage_url |
string | The App homepage. Used in the Marketplace and for OAuth purposes. |
version |
string | The version of your App, formatted as v00.00.0000 . |
display_name |
string | The display name for your App. |
description |
string | The description for your App. Used in the product Marketplace. Provide examples of key functionality the App provides in a short paragraph. |
icon |
string | The icon for your App. Must be a relative path to a PNG image in the static assets folder. Used as the bot account icon and in the product Marketplace. |
requested_permissions |
Permissions | List of permissions needed by the App. |
requested_locations |
Locations | The list of top-level locations that the App intends to bind to. |
bindings |
Call | The call invoked to retrieve bindings. Default value: /bindings |
on_install |
Call | The call invoked when the App is installed. |
on_uninstall |
Call | The call invoked when the App is uninstalled, before the App is removed. |
on_version_changed |
Call | The call invoked when the App needs to be upgraded or downgraded. |
get_oauth2_connect_url |
Call | The call invoked when an OAuth2 authentication flow has started. |
on_oauth2_complete |
Call | The call invoked when an OAuth2 authentication flow has successfully completed. |
on_remote_webhook |
Call | The call invoked when an App webhook is received from a remote system. |
remote_webhook_auth_type |
string | Specifies how incoming App webhook messages from remote systems should be authenticated by Mattermost. One of "" , none , or secret . Default value: "" .The value "" is treated as if it were the value secret . |
aws_lambda |
AWSLambda | Metadata for an App that can be deployed to AWS Lambda and S3 services, and is accessed using the AWS APIs. |
open_faas |
OpenFAAS | Metadata for an App that can be deployed to OpenFAAS. |
http |
HTTP | Metadata for an App that is already deployed externally and is accessed using HTTP. |
For example, a typical App manifest would look like the following:
{
"app_id": "hello-world",
"version":"v0.8.0",
"display_name": "Hello, world!",
"icon": "icon.png",
"homepage_url": "https://github.com/mattermost/mattermost-plugin-apps",
"requested_permissions": [
"act_as_bot"
],
"requested_locations": [
"/channel_header",
"/command"
],
"on_install": {
"path": "/install"
},
"http": {
"root_url": "http://localhost:4000"
}
}
Apps need to request permissions from the System Admin who is installing them. After an App is installed and available to end users, each user in Mattermost will need to “authenticate” with your App.
Using the act_as_user
permission, your App will be performing an API call on behalf of each authenticated user.
The following table lists the supported permissions (godoc) an app can request:
Name | Description |
---|---|
act_as_bot |
Use Mattermost REST API as the app’s bot user. |
act_as_user |
Use Mattermost REST API as a connected user. |
remote_oauth2 |
Use remote (third-party) OAuth2 support, and store secrets and tokens to third-party system(s) within the Mattermost server. |
remote_webhooks |
Receive webhooks from a remote (third-party) system and process them as a bot. This will typically add a notification message to a channel. |
Locations (godoc) are spaces in the UI where an App can add interactions. Locations in the App framework are supported on the mobile, desktop, and web app clients unless otherwise noted. This list of locations will grow over time as the App framework expands.
Name | Description |
---|---|
/post_menu |
An item in a Mattermost post’s dropdown menu (e.g., Message Action) where the user can leverage message content as part of the App’s action. For example, someone reports a bug in a channel with some details, then using the “post-menu” button, the message’s content could be used to create a new “bug” object in a tracking system. |
/channel_header |
A button in the channel header on the desktop app or the web app, and an item in the channel menu on the mobile app. This is used for actions that take place at the channel level. For example, a button for the user to set up a notification subscription for all new tickets in system XYZ to be posted to the current channel. |
/command |
A slash command accessed by typing / at the beginning of any new message in Mattermost.For example, a slash command /ticketing --name "test Ticket" --priority high can capture two fields and create a ticket in an external system. The options for the priority field could be displayed to the user in a pick list to reduce their need to type. |
/in_post |
A form that is embedded within a message in Mattermost. Used to interact with users without switching context to an interactive dialog. For example, confirming simple things like “Did you complete your OKR review yet? (Yes/No)” options can be presented to the user and they can simply check off a box. |
Provides configuration for accessing an app that is deployed externally of Mattermost and is accessible via HTTP.
Name | Description |
---|---|
root_url |
Base URL for all calls and static asset requests. |
use_jwt |
Include a secret-based JWT in all requests to the App. The secret must be provided by the App to the System Admin and entered when the App is installed. |
Example:
{
"http": {
"root_url": "https://myurl.test/somepath",
"use_jwt": true
}
}
Provides configuration for deploying an App onto the AWS Lambda and S3 services. All fields are mandatory ().
Name | Type | Description |
---|---|---|
functions |
AWS Lambda functions | List of functions |
Each AWS Lambda function contains the following fields:
Name | Description |
---|---|
path |
Root path of calls to be mapped to this function. For example: "/" |
name |
Function’s base name; used to compose the actual AWS Lambda name. |
handler |
The name of the function handler. |
runtime |
AWS Lambda runtime to use. See the Lambda runtimes documentation for a list of supported runtimes. |
Example:
{
"aws_lambda": {
"functions": [
{
"path": "/",
"name": "my-funct",
"handler": "my-funct",
"runtime": "go1.x"
}
]
}
}
Provides configuration for deploying an App onto OpenFaaS and faasd
platforms.
All fields are mandatory ().
Name | Type | Description |
---|---|---|
functions |
OpenFaaS functions | List of functions |
Each function contains the following fields:
Name | Description |
---|---|
path |
Root path of calls to be mapped to this function. For example: "/" |
name |
Function’s base name. Used to compose the actual OpenFaaS function name, combined with the App ID and version. |
Example:
{
"open_faas": {
"functions": [
{
"path": "/",
"name": "my-funct"
}
]
}
}