Mattermost Notifications

Overview

• Source: https://mattermost.com/
• Image Support: Yes
• Attachment Support: No
• Message Character Limits:
  • Body: 4000
• Build Your Apprise URL

Account Setup

To use this plugin, you need to first set yourself up with http://mattermost.com. Download their software and set it up.

This plugin supports 2 different integration styles:

1. Incoming Webhooks (default), posts to /hooks/<webhook_token>.
2. Bot (REST API) posting (mode=bot), posts to /api/v4/posts using an access token (Bot or User).

Incoming Webhook Setup (default)

From here you’ll need an *Incoming Webhook. This can be done as follows:

1. Click on the Integrations option under the channel dropdown and select Incoming Webhook:
   
2. From here you can select Add Incoming Webhook:
   
3. Finally you’ll be able to customize how you want the webhook to act and you can press Save at the bottom when you’re complete.
   

An example URL you may be provided could look like this:

# The URL provided by Mattermost:
http://localhost:8065/hooks/yokkutpah3r3urc5h6i969yima
         ^        ^                ^
         |        |                |
      hostname   port           webhook token

# From here you can do the following to generate your Apprise URL:
# - http:// becomes mmost://
# - drop /hooks reference
# Which gets you:
mmost://localhost:8065/yokkutpah3r3urc5h6i969yima

Posting as the Bot

If you want the message to be attributed to a bot account (or a specific user), you must use Mattermost’s REST API posting:

• POST /api/v4/posts
• Authorization: Bearer <bot_access_token>
• JSON payload containing channel_id and message

Incoming webhooks do not authenticate as a user session, so they cannot truly post as a bot account. You can still set a display name in webhook mode, but it depends on Mattermost server settings permitting overrides.

In bot mode you can target channels in two ways:

1. Provide a channel_id directly (preferred).
2. Provide #channel_name only when a team name is also provided, since Apprise must perform a lookup to translate #channel_name into a channel_id.

Syntax

Webhook Mode (default)

Valid syntax is as follows:

• mmost://{hostname}/{token}
• mmost://{hostname}:{port}/{token}
• mmost://{botname}@{hostname}/{token}
• mmost://{botname}@{hostname}:{port}/{token}
• mmost://{hostname}/{path}/{token}
• mmost://{hostname}:{port}/{path}/{token}
• mmost://{botname}@{hostname}/{path}/{token}
• mmost://{botname}@{hostname}:{port}/{path}/{token}

Secure connections (via https) should be referenced using mmosts://, whereas insecure connections (via http) should be referenced via mmost://. They follow the same structure.

Webhook mode can be used with or without channels:

• If channels are provided, Apprise will include "channel" in the payload.
• If channels are not provided, Apprise will not include "channel", and Mattermost will use the webhook’s configured defaults.

Bot Mode (mode=bot)

Bot mode uses the same base URL syntax, however:

• {token} is an access token (Bot token or User token)
• you must provide one or more targets using to= or channels=
• image and icon_url do not apply in this mode

If a team name is not provided, any #channel_name targets are ignored.

Examples:

• mmosts://{hostname}/{access_token}?mode=bot&to={channel_id}
• mmosts://{hostname}/{access_token}?mode=bot&to={id1},{id2}
• mmosts://{team}@{hostname}/{access_token}?mode=bot&to=#general
• mmosts://{hostname}/{access_token}?mode=bot&team={team}&to=#general
• mmosts://{hostname}:{port}/{path}/{access_token}?mode=bot&to={channel_id}

Parameter Breakdown

Variable	Required	Description
hostname	Yes	The server Mattermost is listening on.
token	Yes	Webhook mode: Incoming Webhook token. Bot mode: Bot or User access token (Bearer token).
port	No	The server port Mattermost is listening on. If omitted, Apprise uses the default port associated with the scheme (for example 443 for mmosts://). Many Mattermost installs use port 8065, so specify it when needed.
path	No	You can identify a sub-path if you wish. The last element of the path must be the token.
botname	No	Webhook mode: optional display name override. Requires the Mattermost admin setting “Enable integrations to override usernames”. Bot mode: alias of team, used only for #channel_name lookup.
team	No	Bot mode only. Team name used to resolve #channel_name targets into channel ids. This maps to the same internal value as botname and the URL user portion.
image	No	Webhook mode only. Include the Apprise status image. Ignored when icon_url is set.
icon_url	No	Webhook mode only. Override the avatar icon with a custom URL. Requires the Mattermost admin setting “Enable integrations to override profile picture icons”.
channels	No	Webhook mode: channel names. Bot mode: channel ids (or #channel_name when team is provided). You can specify a comma separated list.
channel	No	Alias of channels.
to	No	Alias of channels. Useful for YAML config where to: is already a concept.
mode	No	webhook (default) or bot.

Global Parameters

Variable	Description
overflow	This parameter can be set to either split, truncate, or upstream. This determines how Apprise delivers the message you pass it. By default this is set to upstream 👉 upstream: Do nothing at all; pass the message exactly as you received it to the service. 👉 truncate: Ensure that the message will fit within the service’s documented upstream message limit. If more information was passed then the defined limit, the overhead information is truncated. 👉 split: similar to truncate except if the message doesn’t fit within the service’s documented upstream message limit, it is split into smaller chunks and they are all delivered sequentially there-after.
format	This parameter can be set to either text, html, or markdown. Some services support the ability to post content by several different means. The default of this varies (it can be one of the 3 mentioned at any time depending on which service you choose). You can optionally force this setting to stray from the defaults if you wish. If the service doesn’t support different types of transmission formats, then this field is ignored.
verify	External requests made to secure locations (such as through the use of https) will have certificates associated with them. By default, Apprise will verify that these certificates are valid; if they are not then no notification will be sent to the source. In some occasions, a user might not have a certificate authority to verify the key against or they trust the source; in this case you will want to set this flag to no. By default it is set to yes.
cto	This stands for Socket Connect Timeout. This is the number of seconds Requests will wait for your client to establish a connection to a remote machine (corresponding to the connect()) call on the socket. The default value is 4.0 seconds.
rto	This stands for Socket Read Timeout. This is the number of seconds the client will wait for the server to send a response. The default value is 4.0 seconds.
emojis	Enable Emoji support (such as providing :+1: would translate to 👍). By default this is set to no. Note: Depending on server side settings, the administrator has the power to disable emoji support at a global level; but default this is not the case.
tz	Identify the IANA Time Zone Database you wish to operate as. By default this is detected based on the configuration the server hosting Apprise is running on. You can set this to things like America/Toronto, or any other properly formated Timezone describing your area.

Examples

Send a secure Mattermost notification to our server using a webhook:

# Assuming our {hostname} is mattermost.server.local
# Assuming our {token} is 3ccdd113474722377935511fc85d3dd4

apprise -vv -t "Test Message Title" -b "Test Message Body" \
   mmosts://mattermost.server.local/3ccdd113474722377935511fc85d3dd4

Send a secure Mattermost notification to our server running on TCP Port 8065:

# Assuming our {hostname} is mattermost.server.local
# Assuming our secure {port} our server is running on is 8065
# Assuming our {token} is 3ccdd113474722377935511fc85d3dd4

apprise -vv -t "Test Message Title" -b "Test Message Body" \
   mmosts://mattermost.server.local:8065/3ccdd113474722377935511fc85d3dd4

Send an insecure Mattermost notification to a server, addressing specific channels:

# Assuming our {hostname} is mattermost.server.local
# Assuming our {token} is 3ccdd113474722377935511fc85d3dd4
# Assuming our {channels} is #support and #general

# We don't need to provide the '#' (hashtag) prefix:
apprise -vv -t "Test Message Title" -b "Test Message Body" \
   mmost://mattermost.server.local/3ccdd113474722377935511fc85d3dd4?channels=support,general

Post as a bot into a specific channel id:

# Assuming our {access_token} is abcd1234
# Assuming our {channel_id} is f6g7ha13d4e58ib2c9aa
apprise -vv -t "Test Message Title" -b "Test Message Body" \
   'mmosts://mattermost.server.local/abcd1234?mode=bot&to=f6g7ha13d4e58ib2c9aa'

Post as a bot into multiple channel id targets:

# Assuming our {access_token} is abcd1234
# Assuming our {channel_ids} are a1b2c3d4e5f6g7h8i9j0 and f6g7ha13d4e58ib2c9aa
apprise -vv -t "Test Message Title" -b "Test Message Body" \
   'mmosts://mattermost.server.local/abcd1234?mode=bot&to=a1b2c3d4e5f6g7h8i9j0,f6g7ha13d4e58ib2c9aa'

Post as a bot using #channel_name lookup (team required):

# Assuming our {access_token} is abcd1234
# Assuming our {team} is myteam
# Assuming our {channel_name} is general

# Team provided via URL user portion:
apprise -vv -t "Test Message Title" -b "Test Message Body" \
   'mmosts://myteam@mattermost.server.local/abcd1234?mode=bot&to=#general'

# Team provided via query string:
apprise -vv -t "Test Message Title" -b "Test Message Body" \
   'mmosts://mattermost.server.local/abcd1234?mode=bot&team=myteam&to=#general'