1// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved. 2// See LICENSE.txt for license information. 3 4package plugin 5 6import ( 7 "io" 8 "net/http" 9 10 plugin "github.com/hashicorp/go-plugin" 11 12 "github.com/mattermost/mattermost-server/v6/model" 13) 14 15// The API can be used to retrieve data or perform actions on behalf of the plugin. Most methods 16// have direct counterparts in the REST API and very similar behavior. 17// 18// Plugins obtain access to the API by embedding MattermostPlugin and accessing the API member 19// directly. 20type API interface { 21 // LoadPluginConfiguration loads the plugin's configuration. dest should be a pointer to a 22 // struct that the configuration JSON can be unmarshalled to. 23 // 24 // @tag Plugin 25 // Minimum server version: 5.2 26 LoadPluginConfiguration(dest interface{}) error 27 28 // RegisterCommand registers a custom slash command. When the command is triggered, your plugin 29 // can fulfill it via the ExecuteCommand hook. 30 // 31 // @tag Command 32 // Minimum server version: 5.2 33 RegisterCommand(command *model.Command) error 34 35 // UnregisterCommand unregisters a command previously registered via RegisterCommand. 36 // 37 // @tag Command 38 // Minimum server version: 5.2 39 UnregisterCommand(teamID, trigger string) error 40 41 // ExecuteSlashCommand executes a slash command with the given parameters. 42 // 43 // @tag Command 44 // Minimum server version: 5.26 45 ExecuteSlashCommand(commandArgs *model.CommandArgs) (*model.CommandResponse, error) 46 47 // GetSession returns the session object for the Session ID 48 // 49 // Minimum server version: 5.2 50 GetSession(sessionID string) (*model.Session, *model.AppError) 51 52 // GetConfig fetches the currently persisted config 53 // 54 // @tag Configuration 55 // Minimum server version: 5.2 56 GetConfig() *model.Config 57 58 // GetUnsanitizedConfig fetches the currently persisted config without removing secrets. 59 // 60 // @tag Configuration 61 // Minimum server version: 5.16 62 GetUnsanitizedConfig() *model.Config 63 64 // SaveConfig sets the given config and persists the changes 65 // 66 // @tag Configuration 67 // Minimum server version: 5.2 68 SaveConfig(config *model.Config) *model.AppError 69 70 // GetPluginConfig fetches the currently persisted config of plugin 71 // 72 // @tag Plugin 73 // Minimum server version: 5.6 74 GetPluginConfig() map[string]interface{} 75 76 // SavePluginConfig sets the given config for plugin and persists the changes 77 // 78 // @tag Plugin 79 // Minimum server version: 5.6 80 SavePluginConfig(config map[string]interface{}) *model.AppError 81 82 // GetBundlePath returns the absolute path where the plugin's bundle was unpacked. 83 // 84 // @tag Plugin 85 // Minimum server version: 5.10 86 GetBundlePath() (string, error) 87 88 // GetLicense returns the current license used by the Mattermost server. Returns nil if 89 // the server does not have a license. 90 // 91 // @tag Server 92 // Minimum server version: 5.10 93 GetLicense() *model.License 94 95 // GetServerVersion return the current Mattermost server version 96 // 97 // @tag Server 98 // Minimum server version: 5.4 99 GetServerVersion() string 100 101 // GetSystemInstallDate returns the time that Mattermost was first installed and ran. 102 // 103 // @tag Server 104 // Minimum server version: 5.10 105 GetSystemInstallDate() (int64, *model.AppError) 106 107 // GetDiagnosticId returns a unique identifier used by the server for diagnostic reports. 108 // 109 // @tag Server 110 // Minimum server version: 5.10 111 GetDiagnosticId() string 112 113 // GetTelemetryId returns a unique identifier used by the server for telemetry reports. 114 // 115 // @tag Server 116 // Minimum server version: 5.28 117 GetTelemetryId() string 118 119 // CreateUser creates a user. 120 // 121 // @tag User 122 // Minimum server version: 5.2 123 CreateUser(user *model.User) (*model.User, *model.AppError) 124 125 // DeleteUser deletes a user. 126 // 127 // @tag User 128 // Minimum server version: 5.2 129 DeleteUser(userID string) *model.AppError 130 131 // GetUsers a list of users based on search options. 132 // 133 // @tag User 134 // Minimum server version: 5.10 135 GetUsers(options *model.UserGetOptions) ([]*model.User, *model.AppError) 136 137 // GetUser gets a user. 138 // 139 // @tag User 140 // Minimum server version: 5.2 141 GetUser(userID string) (*model.User, *model.AppError) 142 143 // GetUserByEmail gets a user by their email address. 144 // 145 // @tag User 146 // Minimum server version: 5.2 147 GetUserByEmail(email string) (*model.User, *model.AppError) 148 149 // GetUserByUsername gets a user by their username. 150 // 151 // @tag User 152 // Minimum server version: 5.2 153 GetUserByUsername(name string) (*model.User, *model.AppError) 154 155 // GetUsersByUsernames gets users by their usernames. 156 // 157 // @tag User 158 // Minimum server version: 5.6 159 GetUsersByUsernames(usernames []string) ([]*model.User, *model.AppError) 160 161 // GetUsersInTeam gets users in team. 162 // 163 // @tag User 164 // @tag Team 165 // Minimum server version: 5.6 166 GetUsersInTeam(teamID string, page int, perPage int) ([]*model.User, *model.AppError) 167 168 // GetPreferencesForUser gets a user's preferences. 169 // 170 // @tag User 171 // @tag Preference 172 // Minimum server version: 5.26 173 GetPreferencesForUser(userID string) ([]model.Preference, *model.AppError) 174 175 // UpdatePreferencesForUser updates a user's preferences. 176 // 177 // @tag User 178 // @tag Preference 179 // Minimum server version: 5.26 180 UpdatePreferencesForUser(userID string, preferences []model.Preference) *model.AppError 181 182 // DeletePreferencesForUser deletes a user's preferences. 183 // 184 // @tag User 185 // @tag Preference 186 // Minimum server version: 5.26 187 DeletePreferencesForUser(userID string, preferences []model.Preference) *model.AppError 188 189 // CreateUserAccessToken creates a new access token. 190 // @tag User 191 // Minimum server version: 5.38 192 CreateUserAccessToken(token *model.UserAccessToken) (*model.UserAccessToken, *model.AppError) 193 194 // RevokeUserAccessToken revokes an existing access token. 195 // @tag User 196 // Minimum server version: 5.38 197 RevokeUserAccessToken(tokenID string) *model.AppError 198 199 // GetTeamIcon gets the team icon. 200 // 201 // @tag Team 202 // Minimum server version: 5.6 203 GetTeamIcon(teamID string) ([]byte, *model.AppError) 204 205 // SetTeamIcon sets the team icon. 206 // 207 // @tag Team 208 // Minimum server version: 5.6 209 SetTeamIcon(teamID string, data []byte) *model.AppError 210 211 // RemoveTeamIcon removes the team icon. 212 // 213 // @tag Team 214 // Minimum server version: 5.6 215 RemoveTeamIcon(teamID string) *model.AppError 216 217 // UpdateUser updates a user. 218 // 219 // @tag User 220 // Minimum server version: 5.2 221 UpdateUser(user *model.User) (*model.User, *model.AppError) 222 223 // GetUserStatus will get a user's status. 224 // 225 // @tag User 226 // Minimum server version: 5.2 227 GetUserStatus(userID string) (*model.Status, *model.AppError) 228 229 // GetUserStatusesByIds will return a list of user statuses based on the provided slice of user IDs. 230 // 231 // @tag User 232 // Minimum server version: 5.2 233 GetUserStatusesByIds(userIds []string) ([]*model.Status, *model.AppError) 234 235 // UpdateUserStatus will set a user's status until the user, or another integration/plugin, sets it back to online. 236 // The status parameter can be: "online", "away", "dnd", or "offline". 237 // 238 // @tag User 239 // Minimum server version: 5.2 240 UpdateUserStatus(userID, status string) (*model.Status, *model.AppError) 241 242 // SetUserStatusTimedDND will set a user's status to dnd for given time until the user, 243 // or another integration/plugin, sets it back to online. 244 // @tag User 245 // Minimum server version: 5.35 246 SetUserStatusTimedDND(userId string, endtime int64) (*model.Status, *model.AppError) 247 248 // UpdateUserActive deactivates or reactivates an user. 249 // 250 // @tag User 251 // Minimum server version: 5.8 252 UpdateUserActive(userID string, active bool) *model.AppError 253 254 // GetUsersInChannel returns a page of users in a channel. Page counting starts at 0. 255 // The sortBy parameter can be: "username" or "status". 256 // 257 // @tag User 258 // @tag Channel 259 // Minimum server version: 5.6 260 GetUsersInChannel(channelID, sortBy string, page, perPage int) ([]*model.User, *model.AppError) 261 262 // GetLDAPUserAttributes will return LDAP attributes for a user. 263 // The attributes parameter should be a list of attributes to pull. 264 // Returns a map with attribute names as keys and the user's attributes as values. 265 // Requires an enterprise license, LDAP to be configured and for the user to use LDAP as an authentication method. 266 // 267 // @tag User 268 // Minimum server version: 5.3 269 GetLDAPUserAttributes(userID string, attributes []string) (map[string]string, *model.AppError) 270 271 // CreateTeam creates a team. 272 // 273 // @tag Team 274 // Minimum server version: 5.2 275 CreateTeam(team *model.Team) (*model.Team, *model.AppError) 276 277 // DeleteTeam deletes a team. 278 // 279 // @tag Team 280 // Minimum server version: 5.2 281 DeleteTeam(teamID string) *model.AppError 282 283 // GetTeam gets all teams. 284 // 285 // @tag Team 286 // Minimum server version: 5.2 287 GetTeams() ([]*model.Team, *model.AppError) 288 289 // GetTeam gets a team. 290 // 291 // @tag Team 292 // Minimum server version: 5.2 293 GetTeam(teamID string) (*model.Team, *model.AppError) 294 295 // GetTeamByName gets a team by its name. 296 // 297 // @tag Team 298 // Minimum server version: 5.2 299 GetTeamByName(name string) (*model.Team, *model.AppError) 300 301 // GetTeamsUnreadForUser gets the unread message and mention counts for each team to which the given user belongs. 302 // 303 // @tag Team 304 // @tag User 305 // Minimum server version: 5.6 306 GetTeamsUnreadForUser(userID string) ([]*model.TeamUnread, *model.AppError) 307 308 // UpdateTeam updates a team. 309 // 310 // @tag Team 311 // Minimum server version: 5.2 312 UpdateTeam(team *model.Team) (*model.Team, *model.AppError) 313 314 // SearchTeams search a team. 315 // 316 // @tag Team 317 // Minimum server version: 5.8 318 SearchTeams(term string) ([]*model.Team, *model.AppError) 319 320 // GetTeamsForUser returns list of teams of given user ID. 321 // 322 // @tag Team 323 // @tag User 324 // Minimum server version: 5.6 325 GetTeamsForUser(userID string) ([]*model.Team, *model.AppError) 326 327 // CreateTeamMember creates a team membership. 328 // 329 // @tag Team 330 // @tag User 331 // Minimum server version: 5.2 332 CreateTeamMember(teamID, userID string) (*model.TeamMember, *model.AppError) 333 334 // CreateTeamMembers creates a team membership for all provided user ids. 335 // 336 // @tag Team 337 // @tag User 338 // Minimum server version: 5.2 339 CreateTeamMembers(teamID string, userIds []string, requestorId string) ([]*model.TeamMember, *model.AppError) 340 341 // CreateTeamMembersGracefully creates a team membership for all provided user ids and reports the users that were not added. 342 // 343 // @tag Team 344 // @tag User 345 // Minimum server version: 5.20 346 CreateTeamMembersGracefully(teamID string, userIds []string, requestorId string) ([]*model.TeamMemberWithError, *model.AppError) 347 348 // DeleteTeamMember deletes a team membership. 349 // 350 // @tag Team 351 // @tag User 352 // Minimum server version: 5.2 353 DeleteTeamMember(teamID, userID, requestorId string) *model.AppError 354 355 // GetTeamMembers returns the memberships of a specific team. 356 // 357 // @tag Team 358 // @tag User 359 // Minimum server version: 5.2 360 GetTeamMembers(teamID string, page, perPage int) ([]*model.TeamMember, *model.AppError) 361 362 // GetTeamMember returns a specific membership. 363 // 364 // @tag Team 365 // @tag User 366 // Minimum server version: 5.2 367 GetTeamMember(teamID, userID string) (*model.TeamMember, *model.AppError) 368 369 // GetTeamMembersForUser returns all team memberships for a user. 370 // 371 // @tag Team 372 // @tag User 373 // Minimum server version: 5.10 374 GetTeamMembersForUser(userID string, page int, perPage int) ([]*model.TeamMember, *model.AppError) 375 376 // UpdateTeamMemberRoles updates the role for a team membership. 377 // 378 // @tag Team 379 // @tag User 380 // Minimum server version: 5.2 381 UpdateTeamMemberRoles(teamID, userID, newRoles string) (*model.TeamMember, *model.AppError) 382 383 // CreateChannel creates a channel. 384 // 385 // @tag Channel 386 // Minimum server version: 5.2 387 CreateChannel(channel *model.Channel) (*model.Channel, *model.AppError) 388 389 // DeleteChannel deletes a channel. 390 // 391 // @tag Channel 392 // Minimum server version: 5.2 393 DeleteChannel(channelId string) *model.AppError 394 395 // GetPublicChannelsForTeam gets a list of all channels. 396 // 397 // @tag Channel 398 // @tag Team 399 // Minimum server version: 5.2 400 GetPublicChannelsForTeam(teamID string, page, perPage int) ([]*model.Channel, *model.AppError) 401 402 // GetChannel gets a channel. 403 // 404 // @tag Channel 405 // Minimum server version: 5.2 406 GetChannel(channelId string) (*model.Channel, *model.AppError) 407 408 // GetChannelByName gets a channel by its name, given a team id. 409 // 410 // @tag Channel 411 // Minimum server version: 5.2 412 GetChannelByName(teamID, name string, includeDeleted bool) (*model.Channel, *model.AppError) 413 414 // GetChannelByNameForTeamName gets a channel by its name, given a team name. 415 // 416 // @tag Channel 417 // @tag Team 418 // Minimum server version: 5.2 419 GetChannelByNameForTeamName(teamName, channelName string, includeDeleted bool) (*model.Channel, *model.AppError) 420 421 // GetChannelsForTeamForUser gets a list of channels for given user ID in given team ID. 422 // 423 // @tag Channel 424 // @tag Team 425 // @tag User 426 // Minimum server version: 5.6 427 GetChannelsForTeamForUser(teamID, userID string, includeDeleted bool) ([]*model.Channel, *model.AppError) 428 429 // GetChannelStats gets statistics for a channel. 430 // 431 // @tag Channel 432 // Minimum server version: 5.6 433 GetChannelStats(channelId string) (*model.ChannelStats, *model.AppError) 434 435 // GetDirectChannel gets a direct message channel. 436 // If the channel does not exist it will create it. 437 // 438 // @tag Channel 439 // @tag User 440 // Minimum server version: 5.2 441 GetDirectChannel(userId1, userId2 string) (*model.Channel, *model.AppError) 442 443 // GetGroupChannel gets a group message channel. 444 // If the channel does not exist it will create it. 445 // 446 // @tag Channel 447 // @tag User 448 // Minimum server version: 5.2 449 GetGroupChannel(userIds []string) (*model.Channel, *model.AppError) 450 451 // UpdateChannel updates a channel. 452 // 453 // @tag Channel 454 // Minimum server version: 5.2 455 UpdateChannel(channel *model.Channel) (*model.Channel, *model.AppError) 456 457 // SearchChannels returns the channels on a team matching the provided search term. 458 // 459 // @tag Channel 460 // Minimum server version: 5.6 461 SearchChannels(teamID string, term string) ([]*model.Channel, *model.AppError) 462 463 // CreateChannelSidebarCategory creates a new sidebar category for a set of channels. 464 // 465 // @tag ChannelSidebar 466 // Minimum server version: 5.38 467 CreateChannelSidebarCategory(userID, teamID string, newCategory *model.SidebarCategoryWithChannels) (*model.SidebarCategoryWithChannels, *model.AppError) 468 469 // GetChannelSidebarCategories returns sidebar categories. 470 // 471 // @tag ChannelSidebar 472 // Minimum server version: 5.38 473 GetChannelSidebarCategories(userID, teamID string) (*model.OrderedSidebarCategories, *model.AppError) 474 475 // UpdateChannelSidebarCategories updates the channel sidebar categories. 476 // 477 // @tag ChannelSidebar 478 // Minimum server version: 5.38 479 UpdateChannelSidebarCategories(userID, teamID string, categories []*model.SidebarCategoryWithChannels) ([]*model.SidebarCategoryWithChannels, *model.AppError) 480 481 // SearchUsers returns a list of users based on some search criteria. 482 // 483 // @tag User 484 // Minimum server version: 5.6 485 SearchUsers(search *model.UserSearch) ([]*model.User, *model.AppError) 486 487 // SearchPostsInTeam returns a list of posts in a specific team that match the given params. 488 // 489 // @tag Post 490 // @tag Team 491 // Minimum server version: 5.10 492 SearchPostsInTeam(teamID string, paramsList []*model.SearchParams) ([]*model.Post, *model.AppError) 493 494 // SearchPostsInTeamForUser returns a list of posts by team and user that match the given 495 // search parameters. 496 // @tag Post 497 // Minimum server version: 5.26 498 SearchPostsInTeamForUser(teamID string, userID string, searchParams model.SearchParameter) (*model.PostSearchResults, *model.AppError) 499 500 // AddChannelMember joins a user to a channel (as if they joined themselves) 501 // This means the user will not receive notifications for joining the channel. 502 // 503 // @tag Channel 504 // @tag User 505 // Minimum server version: 5.2 506 AddChannelMember(channelId, userID string) (*model.ChannelMember, *model.AppError) 507 508 // AddUserToChannel adds a user to a channel as if the specified user had invited them. 509 // This means the user will receive the regular notifications for being added to the channel. 510 // 511 // @tag User 512 // @tag Channel 513 // Minimum server version: 5.18 514 AddUserToChannel(channelId, userID, asUserId string) (*model.ChannelMember, *model.AppError) 515 516 // GetChannelMember gets a channel membership for a user. 517 // 518 // @tag Channel 519 // @tag User 520 // Minimum server version: 5.2 521 GetChannelMember(channelId, userID string) (*model.ChannelMember, *model.AppError) 522 523 // GetChannelMembers gets a channel membership for all users. 524 // 525 // @tag Channel 526 // @tag User 527 // Minimum server version: 5.6 528 GetChannelMembers(channelId string, page, perPage int) (model.ChannelMembers, *model.AppError) 529 530 // GetChannelMembersByIds gets a channel membership for a particular User 531 // 532 // @tag Channel 533 // @tag User 534 // Minimum server version: 5.6 535 GetChannelMembersByIds(channelId string, userIds []string) (model.ChannelMembers, *model.AppError) 536 537 // GetChannelMembersForUser returns all channel memberships on a team for a user. 538 // 539 // @tag Channel 540 // @tag User 541 // Minimum server version: 5.10 542 GetChannelMembersForUser(teamID, userID string, page, perPage int) ([]*model.ChannelMember, *model.AppError) 543 544 // UpdateChannelMemberRoles updates a user's roles for a channel. 545 // 546 // @tag Channel 547 // @tag User 548 // Minimum server version: 5.2 549 UpdateChannelMemberRoles(channelId, userID, newRoles string) (*model.ChannelMember, *model.AppError) 550 551 // UpdateChannelMemberNotifications updates a user's notification properties for a channel. 552 // 553 // @tag Channel 554 // @tag User 555 // Minimum server version: 5.2 556 UpdateChannelMemberNotifications(channelId, userID string, notifications map[string]string) (*model.ChannelMember, *model.AppError) 557 558 // GetGroup gets a group by ID. 559 // 560 // @tag Group 561 // Minimum server version: 5.18 562 GetGroup(groupId string) (*model.Group, *model.AppError) 563 564 // GetGroupByName gets a group by name. 565 // 566 // @tag Group 567 // Minimum server version: 5.18 568 GetGroupByName(name string) (*model.Group, *model.AppError) 569 570 // GetGroupMemberUsers gets a page of users belonging to the given group. 571 // 572 // @tag Group 573 // Minimum server version: 5.35 574 GetGroupMemberUsers(groupID string, page, perPage int) ([]*model.User, *model.AppError) 575 576 // GetGroupsBySource gets a list of all groups for the given source. 577 // 578 // @tag Group 579 // Minimum server version: 5.35 580 GetGroupsBySource(groupSource model.GroupSource) ([]*model.Group, *model.AppError) 581 582 // GetGroupsForUser gets the groups a user is in. 583 // 584 // @tag Group 585 // @tag User 586 // Minimum server version: 5.18 587 GetGroupsForUser(userID string) ([]*model.Group, *model.AppError) 588 589 // DeleteChannelMember deletes a channel membership for a user. 590 // 591 // @tag Channel 592 // @tag User 593 // Minimum server version: 5.2 594 DeleteChannelMember(channelId, userID string) *model.AppError 595 596 // CreatePost creates a post. 597 // 598 // @tag Post 599 // Minimum server version: 5.2 600 CreatePost(post *model.Post) (*model.Post, *model.AppError) 601 602 // AddReaction add a reaction to a post. 603 // 604 // @tag Post 605 // Minimum server version: 5.3 606 AddReaction(reaction *model.Reaction) (*model.Reaction, *model.AppError) 607 608 // RemoveReaction remove a reaction from a post. 609 // 610 // @tag Post 611 // Minimum server version: 5.3 612 RemoveReaction(reaction *model.Reaction) *model.AppError 613 614 // GetReaction get the reactions of a post. 615 // 616 // @tag Post 617 // Minimum server version: 5.3 618 GetReactions(postId string) ([]*model.Reaction, *model.AppError) 619 620 // SendEphemeralPost creates an ephemeral post. 621 // 622 // @tag Post 623 // Minimum server version: 5.2 624 SendEphemeralPost(userID string, post *model.Post) *model.Post 625 626 // UpdateEphemeralPost updates an ephemeral message previously sent to the user. 627 // EXPERIMENTAL: This API is experimental and can be changed without advance notice. 628 // 629 // @tag Post 630 // Minimum server version: 5.2 631 UpdateEphemeralPost(userID string, post *model.Post) *model.Post 632 633 // DeleteEphemeralPost deletes an ephemeral message previously sent to the user. 634 // EXPERIMENTAL: This API is experimental and can be changed without advance notice. 635 // 636 // @tag Post 637 // Minimum server version: 5.2 638 DeleteEphemeralPost(userID, postId string) 639 640 // DeletePost deletes a post. 641 // 642 // @tag Post 643 // Minimum server version: 5.2 644 DeletePost(postId string) *model.AppError 645 646 // GetPostThread gets a post with all the other posts in the same thread. 647 // 648 // @tag Post 649 // Minimum server version: 5.6 650 GetPostThread(postId string) (*model.PostList, *model.AppError) 651 652 // GetPost gets a post. 653 // 654 // @tag Post 655 // Minimum server version: 5.2 656 GetPost(postId string) (*model.Post, *model.AppError) 657 658 // GetPostsSince gets posts created after a specified time as Unix time in milliseconds. 659 // 660 // @tag Post 661 // @tag Channel 662 // Minimum server version: 5.6 663 GetPostsSince(channelId string, time int64) (*model.PostList, *model.AppError) 664 665 // GetPostsAfter gets a page of posts that were posted after the post provided. 666 // 667 // @tag Post 668 // @tag Channel 669 // Minimum server version: 5.6 670 GetPostsAfter(channelId, postId string, page, perPage int) (*model.PostList, *model.AppError) 671 672 // GetPostsBefore gets a page of posts that were posted before the post provided. 673 // 674 // @tag Post 675 // @tag Channel 676 // Minimum server version: 5.6 677 GetPostsBefore(channelId, postId string, page, perPage int) (*model.PostList, *model.AppError) 678 679 // GetPostsForChannel gets a list of posts for a channel. 680 // 681 // @tag Post 682 // @tag Channel 683 // Minimum server version: 5.6 684 GetPostsForChannel(channelId string, page, perPage int) (*model.PostList, *model.AppError) 685 686 // GetTeamStats gets a team's statistics 687 // 688 // @tag Team 689 // Minimum server version: 5.8 690 GetTeamStats(teamID string) (*model.TeamStats, *model.AppError) 691 692 // UpdatePost updates a post. 693 // 694 // @tag Post 695 // Minimum server version: 5.2 696 UpdatePost(post *model.Post) (*model.Post, *model.AppError) 697 698 // GetProfileImage gets user's profile image. 699 // 700 // @tag User 701 // Minimum server version: 5.6 702 GetProfileImage(userID string) ([]byte, *model.AppError) 703 704 // SetProfileImage sets a user's profile image. 705 // 706 // @tag User 707 // Minimum server version: 5.6 708 SetProfileImage(userID string, data []byte) *model.AppError 709 710 // GetEmojiList returns a page of custom emoji on the system. 711 // 712 // The sortBy parameter can be: "name". 713 // 714 // @tag Emoji 715 // Minimum server version: 5.6 716 GetEmojiList(sortBy string, page, perPage int) ([]*model.Emoji, *model.AppError) 717 718 // GetEmojiByName gets an emoji by it's name. 719 // 720 // @tag Emoji 721 // Minimum server version: 5.6 722 GetEmojiByName(name string) (*model.Emoji, *model.AppError) 723 724 // GetEmoji returns a custom emoji based on the emojiId string. 725 // 726 // @tag Emoji 727 // Minimum server version: 5.6 728 GetEmoji(emojiId string) (*model.Emoji, *model.AppError) 729 730 // CopyFileInfos duplicates the FileInfo objects referenced by the given file ids, 731 // recording the given user id as the new creator and returning the new set of file ids. 732 // 733 // The duplicate FileInfo objects are not initially linked to a post, but may now be passed 734 // to CreatePost. Use this API to duplicate a post and its file attachments without 735 // actually duplicating the uploaded files. 736 // 737 // @tag File 738 // @tag User 739 // Minimum server version: 5.2 740 CopyFileInfos(userID string, fileIds []string) ([]string, *model.AppError) 741 742 // GetFileInfo gets a File Info for a specific fileId 743 // 744 // @tag File 745 // Minimum server version: 5.3 746 GetFileInfo(fileId string) (*model.FileInfo, *model.AppError) 747 748 // GetFileInfos gets File Infos with options 749 // 750 // @tag File 751 // Minimum server version: 5.22 752 GetFileInfos(page, perPage int, opt *model.GetFileInfosOptions) ([]*model.FileInfo, *model.AppError) 753 754 // GetFile gets content of a file by it's ID 755 // 756 // @tag File 757 // Minimum server version: 5.8 758 GetFile(fileId string) ([]byte, *model.AppError) 759 760 // GetFileLink gets the public link to a file by fileId. 761 // 762 // @tag File 763 // Minimum server version: 5.6 764 GetFileLink(fileId string) (string, *model.AppError) 765 766 // ReadFile reads the file from the backend for a specific path 767 // 768 // @tag File 769 // Minimum server version: 5.3 770 ReadFile(path string) ([]byte, *model.AppError) 771 772 // GetEmojiImage returns the emoji image. 773 // 774 // @tag Emoji 775 // Minimum server version: 5.6 776 GetEmojiImage(emojiId string) ([]byte, string, *model.AppError) 777 778 // UploadFile will upload a file to a channel using a multipart request, to be later attached to a post. 779 // 780 // @tag File 781 // @tag Channel 782 // Minimum server version: 5.6 783 UploadFile(data []byte, channelId string, filename string) (*model.FileInfo, *model.AppError) 784 785 // OpenInteractiveDialog will open an interactive dialog on a user's client that 786 // generated the trigger ID. Used with interactive message buttons, menus 787 // and slash commands. 788 // 789 // Minimum server version: 5.6 790 OpenInteractiveDialog(dialog model.OpenDialogRequest) *model.AppError 791 792 // Plugin Section 793 794 // GetPlugins will return a list of plugin manifests for currently active plugins. 795 // 796 // @tag Plugin 797 // Minimum server version: 5.6 798 GetPlugins() ([]*model.Manifest, *model.AppError) 799 800 // EnablePlugin will enable an plugin installed. 801 // 802 // @tag Plugin 803 // Minimum server version: 5.6 804 EnablePlugin(id string) *model.AppError 805 806 // DisablePlugin will disable an enabled plugin. 807 // 808 // @tag Plugin 809 // Minimum server version: 5.6 810 DisablePlugin(id string) *model.AppError 811 812 // RemovePlugin will disable and delete a plugin. 813 // 814 // @tag Plugin 815 // Minimum server version: 5.6 816 RemovePlugin(id string) *model.AppError 817 818 // GetPluginStatus will return the status of a plugin. 819 // 820 // @tag Plugin 821 // Minimum server version: 5.6 822 GetPluginStatus(id string) (*model.PluginStatus, *model.AppError) 823 824 // InstallPlugin will upload another plugin with tar.gz file. 825 // Previous version will be replaced on replace true. 826 // 827 // @tag Plugin 828 // Minimum server version: 5.18 829 InstallPlugin(file io.Reader, replace bool) (*model.Manifest, *model.AppError) 830 831 // KV Store Section 832 833 // KVSet stores a key-value pair, unique per plugin. 834 // Provided helper functions and internal plugin code will use the prefix `mmi_` before keys. Do not use this prefix. 835 // 836 // @tag KeyValueStore 837 // Minimum server version: 5.2 838 KVSet(key string, value []byte) *model.AppError 839 840 // KVCompareAndSet updates a key-value pair, unique per plugin, but only if the current value matches the given oldValue. 841 // Inserts a new key if oldValue == nil. 842 // Returns (false, err) if DB error occurred 843 // Returns (false, nil) if current value != oldValue or key already exists when inserting 844 // Returns (true, nil) if current value == oldValue or new key is inserted 845 // 846 // @tag KeyValueStore 847 // Minimum server version: 5.12 848 KVCompareAndSet(key string, oldValue, newValue []byte) (bool, *model.AppError) 849 850 // KVCompareAndDelete deletes a key-value pair, unique per plugin, but only if the current value matches the given oldValue. 851 // Returns (false, err) if DB error occurred 852 // Returns (false, nil) if current value != oldValue or key does not exist when deleting 853 // Returns (true, nil) if current value == oldValue and the key was deleted 854 // 855 // @tag KeyValueStore 856 // Minimum server version: 5.16 857 KVCompareAndDelete(key string, oldValue []byte) (bool, *model.AppError) 858 859 // KVSetWithOptions stores a key-value pair, unique per plugin, according to the given options. 860 // Returns (false, err) if DB error occurred 861 // Returns (false, nil) if the value was not set 862 // Returns (true, nil) if the value was set 863 // 864 // Minimum server version: 5.20 865 KVSetWithOptions(key string, value []byte, options model.PluginKVSetOptions) (bool, *model.AppError) 866 867 // KVSet stores a key-value pair with an expiry time, unique per plugin. 868 // 869 // @tag KeyValueStore 870 // Minimum server version: 5.6 871 KVSetWithExpiry(key string, value []byte, expireInSeconds int64) *model.AppError 872 873 // KVGet retrieves a value based on the key, unique per plugin. Returns nil for non-existent keys. 874 // 875 // @tag KeyValueStore 876 // Minimum server version: 5.2 877 KVGet(key string) ([]byte, *model.AppError) 878 879 // KVDelete removes a key-value pair, unique per plugin. Returns nil for non-existent keys. 880 // 881 // @tag KeyValueStore 882 // Minimum server version: 5.2 883 KVDelete(key string) *model.AppError 884 885 // KVDeleteAll removes all key-value pairs for a plugin. 886 // 887 // @tag KeyValueStore 888 // Minimum server version: 5.6 889 KVDeleteAll() *model.AppError 890 891 // KVList lists all keys for a plugin. 892 // 893 // @tag KeyValueStore 894 // Minimum server version: 5.6 895 KVList(page, perPage int) ([]string, *model.AppError) 896 897 // PublishWebSocketEvent sends an event to WebSocket connections. 898 // event is the type and will be prepended with "custom_<pluginid>_". 899 // payload is the data sent with the event. Interface values must be primitive Go types or mattermost-server/model types. 900 // broadcast determines to which users to send the event. 901 // 902 // Minimum server version: 5.2 903 PublishWebSocketEvent(event string, payload map[string]interface{}, broadcast *model.WebsocketBroadcast) 904 905 // HasPermissionTo check if the user has the permission at system scope. 906 // 907 // @tag User 908 // Minimum server version: 5.3 909 HasPermissionTo(userID string, permission *model.Permission) bool 910 911 // HasPermissionToTeam check if the user has the permission at team scope. 912 // 913 // @tag User 914 // @tag Team 915 // Minimum server version: 5.3 916 HasPermissionToTeam(userID, teamID string, permission *model.Permission) bool 917 918 // HasPermissionToChannel check if the user has the permission at channel scope. 919 // 920 // @tag User 921 // @tag Channel 922 // Minimum server version: 5.3 923 HasPermissionToChannel(userID, channelId string, permission *model.Permission) bool 924 925 // LogDebug writes a log message to the Mattermost server log file. 926 // Appropriate context such as the plugin name will already be added as fields so plugins 927 // do not need to add that info. 928 // 929 // @tag Logging 930 // Minimum server version: 5.2 931 LogDebug(msg string, keyValuePairs ...interface{}) 932 933 // LogInfo writes a log message to the Mattermost server log file. 934 // Appropriate context such as the plugin name will already be added as fields so plugins 935 // do not need to add that info. 936 // 937 // @tag Logging 938 // Minimum server version: 5.2 939 LogInfo(msg string, keyValuePairs ...interface{}) 940 941 // LogError writes a log message to the Mattermost server log file. 942 // Appropriate context such as the plugin name will already be added as fields so plugins 943 // do not need to add that info. 944 // 945 // @tag Logging 946 // Minimum server version: 5.2 947 LogError(msg string, keyValuePairs ...interface{}) 948 949 // LogWarn writes a log message to the Mattermost server log file. 950 // Appropriate context such as the plugin name will already be added as fields so plugins 951 // do not need to add that info. 952 // 953 // @tag Logging 954 // Minimum server version: 5.2 955 LogWarn(msg string, keyValuePairs ...interface{}) 956 957 // SendMail sends an email to a specific address 958 // 959 // Minimum server version: 5.7 960 SendMail(to, subject, htmlBody string) *model.AppError 961 962 // CreateBot creates the given bot and corresponding user. 963 // 964 // @tag Bot 965 // Minimum server version: 5.10 966 CreateBot(bot *model.Bot) (*model.Bot, *model.AppError) 967 968 // PatchBot applies the given patch to the bot and corresponding user. 969 // 970 // @tag Bot 971 // Minimum server version: 5.10 972 PatchBot(botUserId string, botPatch *model.BotPatch) (*model.Bot, *model.AppError) 973 974 // GetBot returns the given bot. 975 // 976 // @tag Bot 977 // Minimum server version: 5.10 978 GetBot(botUserId string, includeDeleted bool) (*model.Bot, *model.AppError) 979 980 // GetBots returns the requested page of bots. 981 // 982 // @tag Bot 983 // Minimum server version: 5.10 984 GetBots(options *model.BotGetOptions) ([]*model.Bot, *model.AppError) 985 986 // UpdateBotActive marks a bot as active or inactive, along with its corresponding user. 987 // 988 // @tag Bot 989 // Minimum server version: 5.10 990 UpdateBotActive(botUserId string, active bool) (*model.Bot, *model.AppError) 991 992 // PermanentDeleteBot permanently deletes a bot and its corresponding user. 993 // 994 // @tag Bot 995 // Minimum server version: 5.10 996 PermanentDeleteBot(botUserId string) *model.AppError 997 998 // PluginHTTP allows inter-plugin requests to plugin APIs. 999 // 1000 // Minimum server version: 5.18 1001 PluginHTTP(request *http.Request) *http.Response 1002 1003 // PublishUserTyping publishes a user is typing WebSocket event. 1004 // The parentId parameter may be an empty string, the other parameters are required. 1005 // 1006 // @tag User 1007 // Minimum server version: 5.26 1008 PublishUserTyping(userID, channelId, parentId string) *model.AppError 1009 1010 // CreateCommand creates a server-owned slash command that is not handled by the plugin 1011 // itself, and which will persist past the life of the plugin. The command will have its 1012 // CreatorId set to "" and its PluginId set to the id of the plugin that created it. 1013 // 1014 // @tag SlashCommand 1015 // Minimum server version: 5.28 1016 CreateCommand(cmd *model.Command) (*model.Command, error) 1017 1018 // ListCommands returns the list of all slash commands for teamID. E.g., custom commands 1019 // (those created through the integrations menu, the REST api, or the plugin api CreateCommand), 1020 // plugin commands (those created with plugin api RegisterCommand), and builtin commands 1021 // (those added internally through RegisterCommandProvider). 1022 // 1023 // @tag SlashCommand 1024 // Minimum server version: 5.28 1025 ListCommands(teamID string) ([]*model.Command, error) 1026 1027 // ListCustomCommands returns the list of slash commands for teamID that where created 1028 // through the integrations menu, the REST api, or the plugin api CreateCommand. 1029 // 1030 // @tag SlashCommand 1031 // Minimum server version: 5.28 1032 ListCustomCommands(teamID string) ([]*model.Command, error) 1033 1034 // ListPluginCommands returns the list of slash commands for teamID that were created 1035 // with the plugin api RegisterCommand. 1036 // 1037 // @tag SlashCommand 1038 // Minimum server version: 5.28 1039 ListPluginCommands(teamID string) ([]*model.Command, error) 1040 1041 // ListBuiltInCommands returns the list of slash commands that are builtin commands 1042 // (those added internally through RegisterCommandProvider). 1043 // 1044 // @tag SlashCommand 1045 // Minimum server version: 5.28 1046 ListBuiltInCommands() ([]*model.Command, error) 1047 1048 // GetCommand returns the command definition based on a command id string. 1049 // 1050 // @tag SlashCommand 1051 // Minimum server version: 5.28 1052 GetCommand(commandID string) (*model.Command, error) 1053 1054 // UpdateCommand updates a single command (commandID) with the information provided in the 1055 // updatedCmd model.Command struct. The following fields in the command cannot be updated: 1056 // Id, Token, CreateAt, DeleteAt, and PluginId. If updatedCmd.TeamId is blank, it 1057 // will be set to commandID's TeamId. 1058 // 1059 // @tag SlashCommand 1060 // Minimum server version: 5.28 1061 UpdateCommand(commandID string, updatedCmd *model.Command) (*model.Command, error) 1062 1063 // DeleteCommand deletes a slash command (commandID). 1064 // 1065 // @tag SlashCommand 1066 // Minimum server version: 5.28 1067 DeleteCommand(commandID string) error 1068 1069 // CreateOAuthApp creates a new OAuth App. 1070 // 1071 // @tag OAuth 1072 // Minimum server version: 5.38 1073 CreateOAuthApp(app *model.OAuthApp) (*model.OAuthApp, *model.AppError) 1074 1075 // GetOAuthApp gets an existing OAuth App by id. 1076 // 1077 // @tag OAuth 1078 // Minimum server version: 5.38 1079 GetOAuthApp(appID string) (*model.OAuthApp, *model.AppError) 1080 1081 // UpdateOAuthApp updates an existing OAuth App. 1082 // 1083 // @tag OAuth 1084 // Minimum server version: 5.38 1085 UpdateOAuthApp(app *model.OAuthApp) (*model.OAuthApp, *model.AppError) 1086 1087 // DeleteOAuthApp deletes an existing OAuth App by id. 1088 // 1089 // @tag OAuth 1090 // Minimum server version: 5.38 1091 DeleteOAuthApp(appID string) *model.AppError 1092 1093 // PublishPluginClusterEvent broadcasts a plugin event to all other running instances of 1094 // the calling plugin that are present in the cluster. 1095 // 1096 // This method is used to allow plugin communication in a High-Availability cluster. 1097 // The receiving side should implement the OnPluginClusterEvent hook 1098 // to receive events sent through this method. 1099 // 1100 // Minimum server version: 5.36 1101 PublishPluginClusterEvent(ev model.PluginClusterEvent, opts model.PluginClusterEventSendOptions) error 1102 1103 // RequestTrialLicense requests a trial license and installs it in the server 1104 // 1105 // Minimum server version: 5.36 1106 RequestTrialLicense(requesterID string, users int, termsAccepted bool, receiveEmailsAccepted bool) *model.AppError 1107} 1108 1109var handshake = plugin.HandshakeConfig{ 1110 ProtocolVersion: 1, 1111 MagicCookieKey: "MATTERMOST_PLUGIN", 1112 MagicCookieValue: "Securely message teams, anywhere.", 1113} 1114