Featured Resources
Our most popular content.
Featured Resources
Our most popular content.
This is the documentation for the Go github.com/mattermost/mattermost-server/plugin package. It can also be found on GoDoc.
The plugin package is used by Mattermost server plugins written in go. It also enables the Mattermost server to manage and interact with the running plugin environment.
Note that this package exports a large number of types prefixed with Z_. These are public only to allow their use with Hashicorp's go-plugin (and net/rpc). Do not use these directly.
The API can be used to retrieve data or perform actions on behalf of the plugin. Most methods have direct counterparts in the REST API and very similar behavior.
Plugins obtain access to the API by embedding MattermostPlugin and accessing the API member directly.
Hooks describes the methods a plugin may implement to automatically receive the corresponding event.
A plugin only need implement the hooks it cares about. The MattermostPlugin provides some default implementations for convenience but may be overridden.
LoadPluginConfiguration(dest any) errorLoadPluginConfiguration loads the plugin's configuration. dest should be a pointer to a struct that the configuration JSON can be unmarshalled to.
@tag Plugin Minimum server version: 5.2
RegisterCommand(command *model.Command) errorRegisterCommand registers a custom slash command. When the command is triggered, your plugin can fulfill it via the ExecuteCommand hook.
@tag Command Minimum server version: 5.2
UnregisterCommand(teamID, trigger string) errorUnregisterCommand unregisters a command previously registered via RegisterCommand.
@tag Command Minimum server version: 5.2
ExecuteSlashCommand(commandArgs *model.CommandArgs) (*model.CommandResponse, error)ExecuteSlashCommand executes a slash command with the given parameters.
@tag Command Minimum server version: 5.26
GetConfig() *model.ConfigGetConfig fetches the currently persisted config
@tag Configuration Minimum server version: 5.2
GetUnsanitizedConfig() *model.ConfigGetUnsanitizedConfig fetches the currently persisted config without removing secrets.
@tag Configuration Minimum server version: 5.16
SaveConfig(config *model.Config) *model.AppErrorSaveConfig sets the given config and persists the changes
@tag Configuration Minimum server version: 5.2
GetPluginConfig() map[string]anyGetPluginConfig fetches the currently persisted config of plugin
@tag Plugin Minimum server version: 5.6
SavePluginConfig(config map[string]any) *model.AppErrorSavePluginConfig sets the given config for plugin and persists the changes
@tag Plugin Minimum server version: 5.6
GetBundlePath() (string, error)GetBundlePath returns the absolute path where the plugin's bundle was unpacked.
@tag Plugin Minimum server version: 5.10
GetLicense() *model.LicenseGetLicense returns the current license used by the Mattermost server. Returns nil if the server does not have a license.
@tag Server Minimum server version: 5.10
IsEnterpriseReady() boolIsEnterpriseReady returns true if the Mattermost server is configured as Enterprise Ready.
@tag Server Minimum server version: 5.10
GetServerVersion() stringGetServerVersion return the current Mattermost server version
@tag Server Minimum server version: 5.4
GetSystemInstallDate() (int64, *model.AppError)GetSystemInstallDate returns the time that Mattermost was first installed and ran.
@tag Server Minimum server version: 5.10
GetDiagnosticId() stringGetDiagnosticId returns a unique identifier used by the server for diagnostic reports.
@tag Server Minimum server version: 5.10
GetTelemetryId() stringGetTelemetryId returns a unique identifier used by the server for telemetry reports.
@tag Server Minimum server version: 5.28
CreateUser(user *model.User) (*model.User, *model.AppError)CreateUser creates a user.
@tag User Minimum server version: 5.2
DeleteUser(userID string) *model.AppErrorDeleteUser deletes a user.
@tag User Minimum server version: 5.2
GetUsers(options *model.UserGetOptions) ([]*model.User, *model.AppError)GetUsers a list of users based on search options.
@tag User Minimum server version: 5.10
GetUser(userID string) (*model.User, *model.AppError)GetUser gets a user.
@tag User Minimum server version: 5.2
GetUserByEmail(email string) (*model.User, *model.AppError)GetUserByEmail gets a user by their email address.
@tag User Minimum server version: 5.2
GetUserByUsername(name string) (*model.User, *model.AppError)GetUserByUsername gets a user by their username.
@tag User Minimum server version: 5.2
GetUsersByUsernames(usernames []string) ([]*model.User, *model.AppError)GetUsersByUsernames gets users by their usernames.
@tag User Minimum server version: 5.6
GetUsersInTeam(teamID string, page int, perPage int) ([]*model.User, *model.AppError)GetUsersInTeam gets users in team.
@tag User @tag Team Minimum server version: 5.6
GetPreferencesForUser(userID string) ([]model.Preference, *model.AppError)GetPreferencesForUser gets a user's preferences.
@tag User @tag Preference Minimum server version: 5.26
UpdatePreferencesForUser(userID string, preferences []model.Preference) *model.AppErrorUpdatePreferencesForUser updates a user's preferences.
@tag User @tag Preference Minimum server version: 5.26
DeletePreferencesForUser(userID string, preferences []model.Preference) *model.AppErrorDeletePreferencesForUser deletes a user's preferences.
@tag User @tag Preference Minimum server version: 5.26
GetSession(sessionID string) (*model.Session, *model.AppError)GetSession returns the session object for the Session ID
Minimum server version: 5.2
CreateSession(session *model.Session) (*model.Session, *model.AppError)CreateSession creates a new user session.
@tag User Minimum server version: 6.2
ExtendSessionExpiry(sessionID string, newExpiry int64) *model.AppErrorExtendSessionExpiry extends the duration of an existing session.
@tag User Minimum server version: 6.2
RevokeSession(sessionID string) *model.AppErrorRevokeSession revokes an existing user session.
@tag User Minimum server version: 6.2
CreateUserAccessToken(token *model.UserAccessToken) (*model.UserAccessToken, *model.AppError)CreateUserAccessToken creates a new access token. @tag User Minimum server version: 5.38
RevokeUserAccessToken(tokenID string) *model.AppErrorRevokeUserAccessToken revokes an existing access token. @tag User Minimum server version: 5.38
GetTeamIcon(teamID string) ([]byte, *model.AppError)GetTeamIcon gets the team icon.
@tag Team Minimum server version: 5.6
SetTeamIcon(teamID string, data []byte) *model.AppErrorSetTeamIcon sets the team icon.
@tag Team Minimum server version: 5.6
RemoveTeamIcon(teamID string) *model.AppErrorRemoveTeamIcon removes the team icon.
@tag Team Minimum server version: 5.6
UpdateUser(user *model.User) (*model.User, *model.AppError)UpdateUser updates a user.
@tag User Minimum server version: 5.2
GetUserStatus(userID string) (*model.Status, *model.AppError)GetUserStatus will get a user's status.
@tag User Minimum server version: 5.2
GetUserStatusesByIds(userIds []string) ([]*model.Status, *model.AppError)GetUserStatusesByIds will return a list of user statuses based on the provided slice of user IDs.
@tag User Minimum server version: 5.2
UpdateUserStatus(userID, status string) (*model.Status, *model.AppError)UpdateUserStatus will set a user's status until the user, or another integration/plugin, sets it back to online. The status parameter can be: "online", "away", "dnd", or "offline".
@tag User Minimum server version: 5.2
SetUserStatusTimedDND(userId string, endtime int64) (*model.Status, *model.AppError)SetUserStatusTimedDND will set a user's status to dnd for given time until the user, or another integration/plugin, sets it back to online. @tag User Minimum server version: 5.35
UpdateUserActive(userID string, active bool) *model.AppErrorUpdateUserActive deactivates or reactivates an user.
@tag User Minimum server version: 5.8
UpdateUserCustomStatus(userID string, customStatus *model.CustomStatus) *model.AppErrorUpdateUserCustomStatus will set a user's custom status until the user, or another integration/plugin, clear it or update the custom status. The custom status have two parameters: emoji icon and custom text.
@tag User Minimum server version: 6.2
RemoveUserCustomStatus(userID string) *model.AppErrorRemoveUserCustomStatus will remove a user's custom status.
@tag User Minimum server version: 6.2
GetUsersInChannel(channelID, sortBy string, page, perPage int) ([]*model.User, *model.AppError)GetUsersInChannel returns a page of users in a channel. Page counting starts at 0. The sortBy parameter can be: "username" or "status".
@tag User @tag Channel Minimum server version: 5.6
GetLDAPUserAttributes(userID string, attributes []string) (map[string]string, *model.AppError)GetLDAPUserAttributes will return LDAP attributes for a user. The attributes parameter should be a list of attributes to pull. Returns a map with attribute names as keys and the user's attributes as values. Requires an enterprise license, LDAP to be configured and for the user to use LDAP as an authentication method.
@tag User Minimum server version: 5.3
CreateTeam(team *model.Team) (*model.Team, *model.AppError)CreateTeam creates a team.
@tag Team Minimum server version: 5.2
DeleteTeam(teamID string) *model.AppErrorDeleteTeam deletes a team.
@tag Team Minimum server version: 5.2
GetTeams() ([]*model.Team, *model.AppError)GetTeam gets all teams.
@tag Team Minimum server version: 5.2
GetTeam(teamID string) (*model.Team, *model.AppError)GetTeam gets a team.
@tag Team Minimum server version: 5.2
GetTeamByName(name string) (*model.Team, *model.AppError)GetTeamByName gets a team by its name.
@tag Team Minimum server version: 5.2
GetTeamsUnreadForUser(userID string) ([]*model.TeamUnread, *model.AppError)GetTeamsUnreadForUser gets the unread message and mention counts for each team to which the given user belongs.
@tag Team @tag User Minimum server version: 5.6
UpdateTeam(team *model.Team) (*model.Team, *model.AppError)UpdateTeam updates a team.
@tag Team Minimum server version: 5.2
SearchTeams(term string) ([]*model.Team, *model.AppError)SearchTeams search a team.
@tag Team Minimum server version: 5.8
GetTeamsForUser(userID string) ([]*model.Team, *model.AppError)GetTeamsForUser returns list of teams of given user ID.
@tag Team @tag User Minimum server version: 5.6
CreateTeamMember(teamID, userID string) (*model.TeamMember, *model.AppError)CreateTeamMember creates a team membership.
@tag Team @tag User Minimum server version: 5.2
CreateTeamMembers(teamID string, userIds []string, requestorId string) ([]*model.TeamMember, *model.AppError)CreateTeamMembers creates a team membership for all provided user ids.
@tag Team @tag User Minimum server version: 5.2
CreateTeamMembersGracefully(teamID string, userIds []string, requestorId string) ([]*model.TeamMemberWithError, *model.AppError)CreateTeamMembersGracefully creates a team membership for all provided user ids and reports the users that were not added.
@tag Team @tag User Minimum server version: 5.20
DeleteTeamMember(teamID, userID, requestorId string) *model.AppErrorDeleteTeamMember deletes a team membership.
@tag Team @tag User Minimum server version: 5.2
GetTeamMembers(teamID string, page, perPage int) ([]*model.TeamMember, *model.AppError)GetTeamMembers returns the memberships of a specific team.
@tag Team @tag User Minimum server version: 5.2
GetTeamMember(teamID, userID string) (*model.TeamMember, *model.AppError)GetTeamMember returns a specific membership.
@tag Team @tag User Minimum server version: 5.2
GetTeamMembersForUser(userID string, page int, perPage int) ([]*model.TeamMember, *model.AppError)GetTeamMembersForUser returns all team memberships for a user.
@tag Team @tag User Minimum server version: 5.10
UpdateTeamMemberRoles(teamID, userID, newRoles string) (*model.TeamMember, *model.AppError)UpdateTeamMemberRoles updates the role for a team membership.
@tag Team @tag User Minimum server version: 5.2
CreateChannel(channel *model.Channel) (*model.Channel, *model.AppError)CreateChannel creates a channel.
@tag Channel Minimum server version: 5.2
DeleteChannel(channelId string) *model.AppErrorDeleteChannel deletes a channel.
@tag Channel Minimum server version: 5.2
GetPublicChannelsForTeam(teamID string, page, perPage int) ([]*model.Channel, *model.AppError)GetPublicChannelsForTeam gets a list of all channels.
@tag Channel @tag Team Minimum server version: 5.2
GetChannel(channelId string) (*model.Channel, *model.AppError)GetChannel gets a channel.
@tag Channel Minimum server version: 5.2
GetChannelByName(teamID, name string, includeDeleted bool) (*model.Channel, *model.AppError)GetChannelByName gets a channel by its name, given a team id.
@tag Channel Minimum server version: 5.2
GetChannelByNameForTeamName(teamName, channelName string, includeDeleted bool) (*model.Channel, *model.AppError)GetChannelByNameForTeamName gets a channel by its name, given a team name.
@tag Channel @tag Team Minimum server version: 5.2
GetChannelsForTeamForUser(teamID, userID string, includeDeleted bool) ([]*model.Channel, *model.AppError)GetChannelsForTeamForUser gets a list of channels for given user ID in given team ID.
@tag Channel @tag Team @tag User Minimum server version: 5.6
GetChannelStats(channelId string) (*model.ChannelStats, *model.AppError)GetChannelStats gets statistics for a channel.
@tag Channel Minimum server version: 5.6
GetDirectChannel(userId1, userId2 string) (*model.Channel, *model.AppError)GetDirectChannel gets a direct message channel. If the channel does not exist it will create it.
@tag Channel @tag User Minimum server version: 5.2
GetGroupChannel(userIds []string) (*model.Channel, *model.AppError)GetGroupChannel gets a group message channel. If the channel does not exist it will create it.
@tag Channel @tag User Minimum server version: 5.2
UpdateChannel(channel *model.Channel) (*model.Channel, *model.AppError)UpdateChannel updates a channel.
@tag Channel Minimum server version: 5.2
SearchChannels(teamID string, term string) ([]*model.Channel, *model.AppError)SearchChannels returns the channels on a team matching the provided search term.
@tag Channel Minimum server version: 5.6
CreateChannelSidebarCategory(userID, teamID string, newCategory *model.SidebarCategoryWithChannels) (*model.SidebarCategoryWithChannels, *model.AppError)CreateChannelSidebarCategory creates a new sidebar category for a set of channels.
@tag ChannelSidebar Minimum server version: 5.38
GetChannelSidebarCategories(userID, teamID string) (*model.OrderedSidebarCategories, *model.AppError)GetChannelSidebarCategories returns sidebar categories.
@tag ChannelSidebar Minimum server version: 5.38
UpdateChannelSidebarCategories(userID, teamID string, categories []*model.SidebarCategoryWithChannels) ([]*model.SidebarCategoryWithChannels, *model.AppError)UpdateChannelSidebarCategories updates the channel sidebar categories.
@tag ChannelSidebar Minimum server version: 5.38
SearchUsers(search *model.UserSearch) ([]*model.User, *model.AppError)SearchUsers returns a list of users based on some search criteria.
@tag User Minimum server version: 5.6
SearchPostsInTeam(teamID string, paramsList []*model.SearchParams) ([]*model.Post, *model.AppError)SearchPostsInTeam returns a list of posts in a specific team that match the given params.
@tag Post @tag Team Minimum server version: 5.10
SearchPostsInTeamForUser(teamID string, userID string, searchParams model.SearchParameter) (*model.PostSearchResults, *model.AppError)SearchPostsInTeamForUser returns a list of posts by team and user that match the given search parameters. @tag Post Minimum server version: 5.26
AddChannelMember(channelId, userID string) (*model.ChannelMember, *model.AppError)AddChannelMember joins a user to a channel (as if they joined themselves) This means the user will not receive notifications for joining the channel.
@tag Channel @tag User Minimum server version: 5.2
AddUserToChannel(channelId, userID, asUserId string) (*model.ChannelMember, *model.AppError)AddUserToChannel adds a user to a channel as if the specified user had invited them. This means the user will receive the regular notifications for being added to the channel.
@tag User @tag Channel Minimum server version: 5.18
GetChannelMember(channelId, userID string) (*model.ChannelMember, *model.AppError)GetChannelMember gets a channel membership for a user.
@tag Channel @tag User Minimum server version: 5.2
GetChannelMembers(channelId string, page, perPage int) (model.ChannelMembers, *model.AppError)GetChannelMembers gets a channel membership for all users.
@tag Channel @tag User Minimum server version: 5.6
GetChannelMembersByIds(channelId string, userIds []string) (model.ChannelMembers, *model.AppError)GetChannelMembersByIds gets a channel membership for a particular User
@tag Channel @tag User Minimum server version: 5.6
GetChannelMembersForUser(teamID, userID string, page, perPage int) ([]*model.ChannelMember, *model.AppError)GetChannelMembersForUser returns all channel memberships on a team for a user.
@tag Channel @tag User Minimum server version: 5.10
UpdateChannelMemberRoles(channelId, userID, newRoles string) (*model.ChannelMember, *model.AppError)UpdateChannelMemberRoles updates a user's roles for a channel.
@tag Channel @tag User Minimum server version: 5.2
UpdateChannelMemberNotifications(channelId, userID string, notifications map[string]string) (*model.ChannelMember, *model.AppError)UpdateChannelMemberNotifications updates a user's notification properties for a channel.
@tag Channel @tag User Minimum server version: 5.2
GetGroup(groupId string) (*model.Group, *model.AppError)GetGroup gets a group by ID.
@tag Group Minimum server version: 5.18
GetGroupByName(name string) (*model.Group, *model.AppError)GetGroupByName gets a group by name.
@tag Group Minimum server version: 5.18
GetGroupMemberUsers(groupID string, page, perPage int) ([]*model.User, *model.AppError)GetGroupMemberUsers gets a page of users belonging to the given group.
@tag Group Minimum server version: 5.35
GetGroupsBySource(groupSource model.GroupSource) ([]*model.Group, *model.AppError)GetGroupsBySource gets a list of all groups for the given source.
@tag Group Minimum server version: 5.35
GetGroupsForUser(userID string) ([]*model.Group, *model.AppError)GetGroupsForUser gets the groups a user is in.
@tag Group @tag User Minimum server version: 5.18
DeleteChannelMember(channelId, userID string) *model.AppErrorDeleteChannelMember deletes a channel membership for a user.
@tag Channel @tag User Minimum server version: 5.2
CreatePost(post *model.Post) (*model.Post, *model.AppError)CreatePost creates a post.
@tag Post Minimum server version: 5.2
AddReaction(reaction *model.Reaction) (*model.Reaction, *model.AppError)AddReaction add a reaction to a post.
@tag Post Minimum server version: 5.3
RemoveReaction(reaction *model.Reaction) *model.AppErrorRemoveReaction remove a reaction from a post.
@tag Post Minimum server version: 5.3
GetReactions(postId string) ([]*model.Reaction, *model.AppError)GetReaction get the reactions of a post.
@tag Post Minimum server version: 5.3
SendEphemeralPost(userID string, post *model.Post) *model.PostSendEphemeralPost creates an ephemeral post.
@tag Post Minimum server version: 5.2
UpdateEphemeralPost(userID string, post *model.Post) *model.PostUpdateEphemeralPost updates an ephemeral message previously sent to the user. EXPERIMENTAL: This API is experimental and can be changed without advance notice.
@tag Post Minimum server version: 5.2
DeleteEphemeralPost(userID, postId string) DeleteEphemeralPost deletes an ephemeral message previously sent to the user. EXPERIMENTAL: This API is experimental and can be changed without advance notice.
@tag Post Minimum server version: 5.2
DeletePost(postId string) *model.AppErrorDeletePost deletes a post.
@tag Post Minimum server version: 5.2
GetPostThread(postId string) (*model.PostList, *model.AppError)GetPostThread gets a post with all the other posts in the same thread.
@tag Post Minimum server version: 5.6
GetPost(postId string) (*model.Post, *model.AppError)GetPost gets a post.
@tag Post Minimum server version: 5.2
GetPostsSince(channelId string, time int64) (*model.PostList, *model.AppError)GetPostsSince gets posts created after a specified time as Unix time in milliseconds.
@tag Post @tag Channel Minimum server version: 5.6
GetPostsAfter(channelId, postId string, page, perPage int) (*model.PostList, *model.AppError)GetPostsAfter gets a page of posts that were posted after the post provided.
@tag Post @tag Channel Minimum server version: 5.6
GetPostsBefore(channelId, postId string, page, perPage int) (*model.PostList, *model.AppError)GetPostsBefore gets a page of posts that were posted before the post provided.
@tag Post @tag Channel Minimum server version: 5.6
GetPostsForChannel(channelId string, page, perPage int) (*model.PostList, *model.AppError)GetPostsForChannel gets a list of posts for a channel.
@tag Post @tag Channel Minimum server version: 5.6
GetTeamStats(teamID string) (*model.TeamStats, *model.AppError)GetTeamStats gets a team's statistics
@tag Team Minimum server version: 5.8
UpdatePost(post *model.Post) (*model.Post, *model.AppError)UpdatePost updates a post.
@tag Post Minimum server version: 5.2
GetProfileImage(userID string) ([]byte, *model.AppError)GetProfileImage gets user's profile image.
@tag User Minimum server version: 5.6
SetProfileImage(userID string, data []byte) *model.AppErrorSetProfileImage sets a user's profile image.
@tag User Minimum server version: 5.6
GetEmojiList(sortBy string, page, perPage int) ([]*model.Emoji, *model.AppError)GetEmojiList returns a page of custom emoji on the system.
The sortBy parameter can be: "name".
@tag Emoji Minimum server version: 5.6
GetEmojiByName(name string) (*model.Emoji, *model.AppError)GetEmojiByName gets an emoji by it's name.
@tag Emoji Minimum server version: 5.6
GetEmoji(emojiId string) (*model.Emoji, *model.AppError)GetEmoji returns a custom emoji based on the emojiId string.
@tag Emoji Minimum server version: 5.6
CopyFileInfos(userID string, fileIds []string) ([]string, *model.AppError)CopyFileInfos duplicates the FileInfo objects referenced by the given file ids, recording the given user id as the new creator and returning the new set of file ids.
The duplicate FileInfo objects are not initially linked to a post, but may now be passed to CreatePost. Use this API to duplicate a post and its file attachments without actually duplicating the uploaded files.
@tag File @tag User Minimum server version: 5.2
GetFileInfo(fileId string) (*model.FileInfo, *model.AppError)GetFileInfo gets a File Info for a specific fileId
@tag File Minimum server version: 5.3
GetFileInfos(page, perPage int, opt *model.GetFileInfosOptions) ([]*model.FileInfo, *model.AppError)GetFileInfos gets File Infos with options
@tag File Minimum server version: 5.22
GetFile(fileId string) ([]byte, *model.AppError)GetFile gets content of a file by it's ID
@tag File Minimum server version: 5.8
GetFileLink(fileId string) (string, *model.AppError)GetFileLink gets the public link to a file by fileId.
@tag File Minimum server version: 5.6
ReadFile(path string) ([]byte, *model.AppError)ReadFile reads the file from the backend for a specific path
@tag File Minimum server version: 5.3
GetEmojiImage(emojiId string) ([]byte, string, *model.AppError)GetEmojiImage returns the emoji image.
@tag Emoji Minimum server version: 5.6
UploadFile(data []byte, channelId string, filename string) (*model.FileInfo, *model.AppError)UploadFile will upload a file to a channel using a multipart request, to be later attached to a post.
@tag File @tag Channel Minimum server version: 5.6
OpenInteractiveDialog(dialog model.OpenDialogRequest) *model.AppErrorOpenInteractiveDialog will open an interactive dialog on a user's client that generated the trigger ID. Used with interactive message buttons, menus and slash commands.
Minimum server version: 5.6
GetPlugins() ([]*model.Manifest, *model.AppError)GetPlugins will return a list of plugin manifests for currently active plugins.
@tag Plugin Minimum server version: 5.6
EnablePlugin(id string) *model.AppErrorEnablePlugin will enable an plugin installed.
@tag Plugin Minimum server version: 5.6
DisablePlugin(id string) *model.AppErrorDisablePlugin will disable an enabled plugin.
@tag Plugin Minimum server version: 5.6
RemovePlugin(id string) *model.AppErrorRemovePlugin will disable and delete a plugin.
@tag Plugin Minimum server version: 5.6
GetPluginStatus(id string) (*model.PluginStatus, *model.AppError)GetPluginStatus will return the status of a plugin.
@tag Plugin Minimum server version: 5.6
InstallPlugin(file io.Reader, replace bool) (*model.Manifest, *model.AppError)InstallPlugin will upload another plugin with tar.gz file. Previous version will be replaced on replace true.
@tag Plugin Minimum server version: 5.18
KVSet(key string, value []byte) *model.AppErrorKVSet stores a key-value pair, unique per plugin. Provided helper functions and internal plugin code will use the prefix `mmi_` before keys. Do not use this prefix.
@tag KeyValueStore Minimum server version: 5.2
KVCompareAndSet(key string, oldValue, newValue []byte) (bool, *model.AppError)KVCompareAndSet updates a key-value pair, unique per plugin, but only if the current value matches the given oldValue. Inserts a new key if oldValue == nil. Returns (false, err) if DB error occurred Returns (false, nil) if current value != oldValue or key already exists when inserting Returns (true, nil) if current value == oldValue or new key is inserted
@tag KeyValueStore Minimum server version: 5.12
KVCompareAndDelete(key string, oldValue []byte) (bool, *model.AppError)KVCompareAndDelete deletes a key-value pair, unique per plugin, but only if the current value matches the given oldValue. Returns (false, err) if DB error occurred Returns (false, nil) if current value != oldValue or key does not exist when deleting Returns (true, nil) if current value == oldValue and the key was deleted
@tag KeyValueStore Minimum server version: 5.16
KVSetWithOptions(key string, value []byte, options model.PluginKVSetOptions) (bool, *model.AppError)KVSetWithOptions stores a key-value pair, unique per plugin, according to the given options. Returns (false, err) if DB error occurred Returns (false, nil) if the value was not set Returns (true, nil) if the value was set
Minimum server version: 5.20
KVSetWithExpiry(key string, value []byte, expireInSeconds int64) *model.AppErrorKVSet stores a key-value pair with an expiry time, unique per plugin.
@tag KeyValueStore Minimum server version: 5.6
KVGet(key string) ([]byte, *model.AppError)KVGet retrieves a value based on the key, unique per plugin. Returns nil for non-existent keys.
@tag KeyValueStore Minimum server version: 5.2
KVDelete(key string) *model.AppErrorKVDelete removes a key-value pair, unique per plugin. Returns nil for non-existent keys.
@tag KeyValueStore Minimum server version: 5.2
KVDeleteAll() *model.AppErrorKVDeleteAll removes all key-value pairs for a plugin.
@tag KeyValueStore Minimum server version: 5.6
KVList(page, perPage int) ([]string, *model.AppError)KVList lists all keys for a plugin.
@tag KeyValueStore Minimum server version: 5.6
PublishWebSocketEvent(event string, payload map[string]any, broadcast *model.WebsocketBroadcast) PublishWebSocketEvent sends an event to WebSocket connections. event is the type and will be prepended with "custom_<pluginid>_". payload is the data sent with the event. Interface values must be primitive Go types or mattermost-server/model types. broadcast determines to which users to send the event.
Minimum server version: 5.2
HasPermissionTo(userID string, permission *model.Permission) boolHasPermissionTo check if the user has the permission at system scope.
@tag User Minimum server version: 5.3
HasPermissionToTeam(userID, teamID string, permission *model.Permission) boolHasPermissionToTeam check if the user has the permission at team scope.
@tag User @tag Team Minimum server version: 5.3
HasPermissionToChannel(userID, channelId string, permission *model.Permission) boolHasPermissionToChannel check if the user has the permission at channel scope.
@tag User @tag Channel Minimum server version: 5.3
RolesGrantPermission(roleNames []string, permissionId string) boolRolesGrantPermission check if the specified roles grant the specified permission
Minimum server version: 6.3
LogDebug(msg string, keyValuePairs ...any) LogDebug writes a log message to the Mattermost server log file. Appropriate context such as the plugin name will already be added as fields so plugins do not need to add that info.
@tag Logging Minimum server version: 5.2
LogInfo(msg string, keyValuePairs ...any) LogInfo writes a log message to the Mattermost server log file. Appropriate context such as the plugin name will already be added as fields so plugins do not need to add that info.
@tag Logging Minimum server version: 5.2
LogError(msg string, keyValuePairs ...any) LogError writes a log message to the Mattermost server log file. Appropriate context such as the plugin name will already be added as fields so plugins do not need to add that info.
@tag Logging Minimum server version: 5.2
LogWarn(msg string, keyValuePairs ...any) LogWarn writes a log message to the Mattermost server log file. Appropriate context such as the plugin name will already be added as fields so plugins do not need to add that info.
@tag Logging Minimum server version: 5.2
SendMail(to, subject, htmlBody string) *model.AppErrorSendMail sends an email to a specific address
Minimum server version: 5.7
CreateBot(bot *model.Bot) (*model.Bot, *model.AppError)CreateBot creates the given bot and corresponding user.
@tag Bot Minimum server version: 5.10
PatchBot(botUserId string, botPatch *model.BotPatch) (*model.Bot, *model.AppError)PatchBot applies the given patch to the bot and corresponding user.
@tag Bot Minimum server version: 5.10
GetBot(botUserId string, includeDeleted bool) (*model.Bot, *model.AppError)GetBot returns the given bot.
@tag Bot Minimum server version: 5.10
GetBots(options *model.BotGetOptions) ([]*model.Bot, *model.AppError)GetBots returns the requested page of bots.
@tag Bot Minimum server version: 5.10
UpdateBotActive(botUserId string, active bool) (*model.Bot, *model.AppError)UpdateBotActive marks a bot as active or inactive, along with its corresponding user.
@tag Bot Minimum server version: 5.10
PermanentDeleteBot(botUserId string) *model.AppErrorPermanentDeleteBot permanently deletes a bot and its corresponding user.
@tag Bot Minimum server version: 5.10
PluginHTTP(request *http.Request) *http.ResponsePluginHTTP allows inter-plugin requests to plugin APIs.
Minimum server version: 5.18
PublishUserTyping(userID, channelId, parentId string) *model.AppErrorPublishUserTyping publishes a user is typing WebSocket event. The parentId parameter may be an empty string, the other parameters are required.
@tag User Minimum server version: 5.26
CreateCommand(cmd *model.Command) (*model.Command, error)CreateCommand creates a server-owned slash command that is not handled by the plugin itself, and which will persist past the life of the plugin. The command will have its CreatorId set to "" and its PluginId set to the id of the plugin that created it.
@tag SlashCommand Minimum server version: 5.28
ListCommands(teamID string) ([]*model.Command, error)ListCommands returns the list of all slash commands for teamID. E.g., custom commands (those created through the integrations menu, the REST api, or the plugin api CreateCommand), plugin commands (those created with plugin api RegisterCommand), and builtin commands (those added internally through RegisterCommandProvider).
@tag SlashCommand Minimum server version: 5.28
ListCustomCommands(teamID string) ([]*model.Command, error)ListCustomCommands returns the list of slash commands for teamID that where created through the integrations menu, the REST api, or the plugin api CreateCommand.
@tag SlashCommand Minimum server version: 5.28
ListPluginCommands(teamID string) ([]*model.Command, error)ListPluginCommands returns the list of slash commands for teamID that were created with the plugin api RegisterCommand.
@tag SlashCommand Minimum server version: 5.28
ListBuiltInCommands() ([]*model.Command, error)ListBuiltInCommands returns the list of slash commands that are builtin commands (those added internally through RegisterCommandProvider).
@tag SlashCommand Minimum server version: 5.28
GetCommand(commandID string) (*model.Command, error)GetCommand returns the command definition based on a command id string.
@tag SlashCommand Minimum server version: 5.28
UpdateCommand(commandID string, updatedCmd *model.Command) (*model.Command, error)UpdateCommand updates a single command (commandID) with the information provided in the updatedCmd model.Command struct. The following fields in the command cannot be updated: Id, Token, CreateAt, DeleteAt, and PluginId. If updatedCmd.TeamId is blank, it will be set to commandID's TeamId.
@tag SlashCommand Minimum server version: 5.28
DeleteCommand(commandID string) errorDeleteCommand deletes a slash command (commandID).
@tag SlashCommand Minimum server version: 5.28
CreateOAuthApp(app *model.OAuthApp) (*model.OAuthApp, *model.AppError)CreateOAuthApp creates a new OAuth App.
@tag OAuth Minimum server version: 5.38
GetOAuthApp(appID string) (*model.OAuthApp, *model.AppError)GetOAuthApp gets an existing OAuth App by id.
@tag OAuth Minimum server version: 5.38
UpdateOAuthApp(app *model.OAuthApp) (*model.OAuthApp, *model.AppError)UpdateOAuthApp updates an existing OAuth App.
@tag OAuth Minimum server version: 5.38
DeleteOAuthApp(appID string) *model.AppErrorDeleteOAuthApp deletes an existing OAuth App by id.
@tag OAuth Minimum server version: 5.38
PublishPluginClusterEvent(ev model.PluginClusterEvent, opts model.PluginClusterEventSendOptions) errorPublishPluginClusterEvent broadcasts a plugin event to all other running instances of the calling plugin that are present in the cluster.
This method is used to allow plugin communication in a High-Availability cluster. The receiving side should implement the OnPluginClusterEvent hook to receive events sent through this method.
Minimum server version: 5.36
RequestTrialLicense(requesterID string, users int, termsAccepted bool, receiveEmailsAccepted bool) *model.AppErrorRequestTrialLicense requests a trial license and installs it in the server
Minimum server version: 5.36
GetCloudLimits() (*model.ProductLimits, error)GetCloudLimits gets limits associated with a cloud workspace, if any
Minimum server version: 7.0
EnsureBotUser(bot *model.Bot) (string, error)EnsureBotUser updates the bot if it exists, otherwise creates it.
Minimum server version: 7.1
OnActivate() errorOnActivate is invoked when the plugin is activated. If an error is returned, the plugin will be terminated. The plugin will not receive hooks until after OnActivate returns without error. OnConfigurationChange will be called once before OnActivate.
Minimum server version: 5.2
Implemented() ([]string, error)Implemented returns a list of hooks that are implemented by the plugin. Plugins do not need to provide an implementation. Any given will be ignored.
Minimum server version: 5.2
OnDeactivate() errorOnDeactivate is invoked when the plugin is deactivated. This is the plugin's last chance to use the API, and the plugin will be terminated shortly after this invocation. The plugin will stop receiving hooks just prior to this method being called.
Minimum server version: 5.2
OnConfigurationChange() errorOnConfigurationChange is invoked when configuration changes may have been made. Any returned error is logged, but does not stop the plugin. You must be prepared to handle a configuration failure gracefully. It is called once before OnActivate.
Minimum server version: 5.2
ServeHTTP(c *plugin.Context, w http.ResponseWriter, r *http.Request) ServeHTTP allows the plugin to implement the http.Handler interface. Requests destined for the /plugins/{id} path will be routed to the plugin.
The Mattermost-User-Id header will be present if (and only if) the request is by an authenticated user.
Minimum server version: 5.2
ExecuteCommand(c *plugin.Context, args *model.CommandArgs) (*model.CommandResponse, *model.AppError)ExecuteCommand executes a command that has been previously registered via the RegisterCommand API.
Minimum server version: 5.2
UserHasBeenCreated(c *plugin.Context, user *model.User) UserHasBeenCreated is invoked after a user was created.
Minimum server version: 5.10
UserWillLogIn(c *plugin.Context, user *model.User) stringUserWillLogIn before the login of the user is returned. Returning a non empty string will reject the login event. If you don't need to reject the login event, see UserHasLoggedIn
Minimum server version: 5.2
UserHasLoggedIn(c *plugin.Context, user *model.User) UserHasLoggedIn is invoked after a user has logged in.
Minimum server version: 5.2
MessageWillBePosted(c *plugin.Context, post *model.Post) (*model.Post, string)MessageWillBePosted is invoked when a message is posted by a user before it is committed to the database. If you also want to act on edited posts, see MessageWillBeUpdated.
To reject a post, return an non-empty string describing why the post was rejected. To modify the post, return the replacement, non-nil *model.Post and an empty string. To allow the post without modification, return a nil *model.Post and an empty string. To dismiss the post, return a nil *model.Post and the const DismissPostError string.
If you don't need to modify or reject posts, use MessageHasBeenPosted instead.
Note that this method will be called for posts created by plugins, including the plugin that created the post.
Minimum server version: 5.2
MessageWillBeUpdated(c *plugin.Context, newPost, oldPost *model.Post) (*model.Post, string)MessageWillBeUpdated is invoked when a message is updated by a user before it is committed to the database. If you also want to act on new posts, see MessageWillBePosted. Return values should be the modified post or nil if rejected and an explanation for the user. On rejection, the post will be kept in its previous state.
If you don't need to modify or rejected updated posts, use MessageHasBeenUpdated instead.
Note that this method will be called for posts updated by plugins, including the plugin that updated the post.
Minimum server version: 5.2
MessageHasBeenPosted(c *plugin.Context, post *model.Post) MessageHasBeenPosted is invoked after the message has been committed to the database. If you need to modify or reject the post, see MessageWillBePosted Note that this method will be called for posts created by plugins, including the plugin that created the post.
Minimum server version: 5.2
MessageHasBeenUpdated(c *plugin.Context, newPost, oldPost *model.Post) MessageHasBeenUpdated is invoked after a message is updated and has been updated in the database. If you need to modify or reject the post, see MessageWillBeUpdated Note that this method will be called for posts created by plugins, including the plugin that created the post.
Minimum server version: 5.2
ChannelHasBeenCreated(c *plugin.Context, channel *model.Channel) ChannelHasBeenCreated is invoked after the channel has been committed to the database.
Minimum server version: 5.2
UserHasJoinedChannel(c *plugin.Context, channelMember *model.ChannelMember, actor *model.User) UserHasJoinedChannel is invoked after the membership has been committed to the database. If actor is not nil, the user was invited to the channel by the actor.
Minimum server version: 5.2
UserHasLeftChannel(c *plugin.Context, channelMember *model.ChannelMember, actor *model.User) UserHasLeftChannel is invoked after the membership has been removed from the database. If actor is not nil, the user was removed from the channel by the actor.
Minimum server version: 5.2
UserHasJoinedTeam(c *plugin.Context, teamMember *model.TeamMember, actor *model.User) UserHasJoinedTeam is invoked after the membership has been committed to the database. If actor is not nil, the user was added to the team by the actor.
Minimum server version: 5.2
UserHasLeftTeam(c *plugin.Context, teamMember *model.TeamMember, actor *model.User) UserHasLeftTeam is invoked after the membership has been removed from the database. If actor is not nil, the user was removed from the team by the actor.
Minimum server version: 5.2
FileWillBeUploaded(c *plugin.Context, info *model.FileInfo, file io.Reader, output io.Writer) (*model.FileInfo, string)FileWillBeUploaded is invoked when a file is uploaded, but before it is committed to backing store. Read from file to retrieve the body of the uploaded file.
To reject a file upload, return an non-empty string describing why the file was rejected. To modify the file, write to the output and/or return a non-nil *model.FileInfo, as well as an empty string. To allow the file without modification, do not write to the output and return a nil *model.FileInfo and an empty string.
Note that this method will be called for files uploaded by plugins, including the plugin that uploaded the post. FileInfo.Size will be automatically set properly if you modify the file.
Minimum server version: 5.2
ReactionHasBeenAdded(c *plugin.Context, reaction *model.Reaction) ReactionHasBeenAdded is invoked after the reaction has been committed to the database.
Note that this method will be called for reactions added by plugins, including the plugin that added the reaction.
Minimum server version: 5.30
ReactionHasBeenRemoved(c *plugin.Context, reaction *model.Reaction) ReactionHasBeenRemoved is invoked after the removal of the reaction has been committed to the database.
Note that this method will be called for reactions removed by plugins, including the plugin that removed the reaction.
Minimum server version: 5.30
OnPluginClusterEvent(c *plugin.Context, ev model.PluginClusterEvent) OnPluginClusterEvent is invoked when an intra-cluster plugin event is received.
This is used to allow communication between multiple instances of the same plugin that are running on separate nodes of the same High-Availability cluster. This hook receives events sent by a call to PublishPluginClusterEvent.
Minimum server version: 5.36
OnWebSocketConnect(webConnID, userID string) OnWebSocketConnect is invoked when a new websocket connection is opened.
This is used to track which users have connections opened with the Mattermost websocket.
Minimum server version: 6.0
OnWebSocketDisconnect(webConnID, userID string) OnWebSocketDisconnect is invoked when a websocket connection is closed.
This is used to track which users have connections opened with the Mattermost websocket.
Minimum server version: 6.0
WebSocketMessageHasBeenPosted(webConnID, userID string, req *model.WebSocketRequest) WebSocketMessageHasBeenPosted is invoked when a websocket message is received.
Minimum server version: 6.0
RunDataRetention(nowTime, batchSize int64) (int64, error)RunDataRetention is invoked during a DataRetentionJob.
Minimum server version: 6.4
OnInstall(c *plugin.Context, event model.OnInstallEvent) errorOnInstall is invoked after the installation of a plugin as part of the onboarding. It's called on every installation, not only once.
In the future, other plugin installation methods will trigger this hook, e.g. an installation via the Marketplace.
Minimum server version: 6.5
OnSendDailyTelemetry() OnSendDailyTelemetry is invoked when the server send the daily telemetry data.
Minimum server version: 6.5
OnCloudLimitsUpdated(limits *model.ProductLimits) OnCloudLimitsUpdated is invoked product limits change, for example when plan tiers change
Minimum server version: 7.0
This example demonstrates a plugin that handles HTTP requests which respond by greeting the world.
package main
import (
"fmt"
"net/http"
"github.com/mattermost/mattermost-server/v6/plugin"
)
// HelloWorldPlugin implements the interface expected by the Mattermost server to communicate
// between the server and plugin processes.
type HelloWorldPlugin struct {
plugin.MattermostPlugin
}
// ServeHTTP demonstrates a plugin that handles HTTP requests by greeting the world.
func (p *HelloWorldPlugin) ServeHTTP(c *plugin.Context, w http.ResponseWriter, r *http.Request) {
fmt.Fprint(w, "Hello, world!")
}
// This example demonstrates a plugin that handles HTTP requests which respond by greeting the
// world.
func main() {
plugin.ClientMain(&HelloWorldPlugin{})
}
package main
import (
"strings"
"sync"
"github.com/pkg/errors"
"github.com/mattermost/mattermost-server/v6/model"
"github.com/mattermost/mattermost-server/v6/plugin"
)
// configuration represents the configuration for this plugin as exposed via the Mattermost
// server configuration.
type configuration struct {
TeamName string
ChannelName string
// channelID is resolved when the public configuration fields above change
channelID string
}
// HelpPlugin implements the interface expected by the Mattermost server to communicate
// between the server and plugin processes.
type HelpPlugin struct {
plugin.MattermostPlugin
// configurationLock synchronizes access to the configuration.
configurationLock sync.RWMutex
// configuration is the active plugin configuration. Consult getConfiguration and
// setConfiguration for usage.
configuration *configuration
}
// getConfiguration retrieves the active configuration under lock, making it safe to use
// concurrently. The active configuration may change underneath the client of this method, but
// the struct returned by this API call is considered immutable.
func (p *HelpPlugin) getConfiguration() *configuration {
p.configurationLock.RLock()
defer p.configurationLock.RUnlock()
if p.configuration == nil {
return &configuration{}
}
return p.configuration
}
// setConfiguration replaces the active configuration under lock.
//
// Do not call setConfiguration while holding the configurationLock, as sync.Mutex is not
// reentrant.
func (p *HelpPlugin) setConfiguration(configuration *configuration) {
// Replace the active configuration under lock.
p.configurationLock.Lock()
defer p.configurationLock.Unlock()
p.configuration = configuration
}
// OnConfigurationChange updates the active configuration for this plugin under lock.
func (p *HelpPlugin) OnConfigurationChange() error {
var configuration = new(configuration)
// Load the public configuration fields from the Mattermost server configuration.
if err := p.API.LoadPluginConfiguration(configuration); err != nil {
return errors.Wrap(err, "failed to load plugin configuration")
}
team, err := p.API.GetTeamByName(configuration.TeamName)
if err != nil {
return errors.Wrapf(err, "failed to find team %s", configuration.TeamName)
}
channel, err := p.API.GetChannelByName(configuration.ChannelName, team.Id, false)
if err != nil {
return errors.Wrapf(err, "failed to find channel %s", configuration.ChannelName)
}
configuration.channelID = channel.Id
p.setConfiguration(configuration)
return nil
}
// MessageHasBeenPosted automatically replies to posts that plea for help.
func (p *HelpPlugin) MessageHasBeenPosted(c *plugin.Context, post *model.Post) {
configuration := p.getConfiguration()
// Ignore posts not in the configured channel
if post.ChannelId != configuration.channelID {
return
}
// Ignore posts this plugin made.
if sentByPlugin, _ := post.GetProp("sent_by_plugin").(bool); sentByPlugin {
return
}
// Ignore posts without a plea for help.
if !strings.Contains(post.Message, "help") {
return
}
p.API.SendEphemeralPost(post.UserId, &model.Post{
ChannelId: configuration.channelID,
Message: "You asked for help? Checkout https://support.mattermost.com/hc/en-us",
Props: map[string]any{
"sent_by_plugin": true,
},
})
}
func main() {
plugin.ClientMain(&HelpPlugin{})
}