Disclaimer
This repository is community supported and not maintained by Mattermost. Mattermost disclaims liability for integrations, including Third Party Integrations and Mattermost Integrations. Integrations may be modified or discontinued at any time.
Welcome Bot Plugin
Maintainer: @mickmister
Use this plugin to improve onboarding and HR processes. It adds a Welcome Bot that helps welcome users to teams and/or channels as well as easily join channels based on selections.
Welcome a new team member to Mattermost Contributors team. Then add the user to a set of channels based on their selection.
Configuration
-
Go to System Console > Plugins > Management and click Enable to enable the Welcome Bot plugin.
- If you are running Mattermost v5.11 or earlier, you must first go to the releases page of this GitHub repository, download the latest release, and upload it to your Mattermost instance following this documentation.
-
Modify your
config.jsonfile to include your Welcome Bot's messages and actions, under thePluginSettings. See below for an example of what this should look like.
Usage
To configure the Welcome Bot, edit your config.json file with a message you want to send to a user in the following format:
"Plugins": {
"com.mattermost.welcomebot": {
"WelcomeMessages": [
{
"TeamName": "your-team-name",
"DelayInSeconds": 3,
"IncludeGuests": false,
"Message": [
"Your welcome message here. Each list item specifies one line in the message text."
],
"AttachmentMessage": [
"Attachment message containing user actions"
],
"Actions" : [
{
"ActionType": "button",
"ActionDisplayName": "User Action",
"ActionName": "action-name",
"ActionSuccessfulMessage": [
"Message posted after the user takes this action and joins channels specified by 'ChannelsAddedTo'."
],
"ChannelsAddedTo": ["channel-1", "channel-2"]
},
{
"ActionType": "automatic",
"ChannelsAddedTo": ["channel-3", "channel-4"]
}
]
}
]
}
},where
- TeamName: The team for which the Welcome Bot sends a message for. Must be the team handle used in the URL, in lowercase. For example, in the following URL the TeamName value is
my-team: https://example.com/my-team/channels/my-channel - DelayInSeconds: The number of seconds after joining a team that the user receives a welcome message.
- Message: The message posted to the user.
- (Optional) IncludeGuests: Whether or not to include guest users.
- (Optional) AttachmentMessage: Message text in attachment containing user action buttons.
- (Optional) Actions: Use this to add new team members to channels automatically or based on which action button they pressed.
- ActionType: One of
buttonorautomatic. Whenbutton: enables uses to select which types of channels they want to join. Whenautomatic: the user is automatically added to the specified channels. - ActionDisplayName: Sets the display name for the user action buttons.
- ActionName: Sets the action name used by the plugin to identify which action is taken by a user.
- ActionSuccessfulMessage: Message posted after the user takes this action and joins the specified channels.
- ChannelsAddedTo: List of channel names the user is added to. Must be the channel handle used in the URL, in lowercase. For example, in the following URL the channel name value is
my-channel: https://example.com/my-team/channels/my-channel
- ActionType: One of
The preview of the configured messages, as well as the creation of a channel welcome message, can be done via bot commands:
/welcomebot help- Displays usage information./welcomebot list- Lists the teams for which greetings were defined./welcomebot preview [team-name]- Sends ephemeral messages to the user calling the command, with the preview of the welcome message[s] for the given team name and the user that requested the preview./welcomebot set_channel_welcome [welcome-message]- Sets the given text as current's channel welcome message./welcomebot get_channel_welcome- Gets the current channel's welcome message./welcomebot delete_channel_welcome- Deletes the current channel's welcome message.
Example
Suppose you have two teams: one for Staff (with team handle staff) which all staff members join, and another for DevSecOps (team handle devsecops), which only security engineers join.
Those who join the Staff team should be added to a set of channels based on their role:
- Developers added to Bugs, Jira Tasks, and Sprint Planning channels
- Account Managers added to Leads, Sales Discussion, and Win-Loss Analysis channels
- Support added to Bugs, Customer Support and Leads channels
Moreover, those who join the DevSecOps team should automatically be added to Escalation Process and Incidents channels.
To accomplish the above, you can specify the following configuration in your config.json file.
"Plugins": {
"com.mattermost.welcomebot": {
"WelcomeMessages": [
{
"TeamName": "staff",
"DelayInSeconds": 5,
"Message": [
"### Welcome {{.UserDisplayName}} to the Staff {{.Team.DisplayName}} team!",
"",
"If you have any questions about your account, please message your @system-admin.",
"",
"For feedback about the Mattermost app, please share in the ~mattermost channel."
]
},
{
"TeamName": "staff",
"DelayInSeconds": 10,
"AttachmentMessage": [
"Let's get started by adding you to key channels! What's your role in the company?"
],
"Actions" : [
{
"ActionType": "button",
"ActionDisplayName": "Developer",
"ActionName": "developer-action",
"ChannelsAddedTo": ["bugs", "jira-tasks", "sprint-planning"],
"ActionSuccessfulMessage": [
"### Awesome! I've added you to the following developer channels:",
"~bugs - To help investigate or report bugs",
"~jira-tasks - To stay updated on Jira tasks",
"~sprint-planning - To plan and manage your team's Jira sprint"
]
},
{
"ActionType": "button",
"ActionDisplayName": "Customer Engineer",
"ActionName": "customer-engineer-action",
"ChannelsAddedTo": ["leads", "sales-discussion", "win-loss-analysis"],
"ActionSuccessfulMessage": [
"### Awesome! I've added you to the following developer channels:",
"~leads - To stay updated on incoming leads",
"~sales-discussion - To collaborate with your fellow Customer Engineers,
"~win-loss-analysis - To conduct win-loss analysis of closed deals"
]
},
{
"ActionType": "button",
"ActionDisplayName": "Support",
"ActionName": "support-action",
"ChannelsAddedTo": ["bugs", "customer-support", "leads"],
"ActionSuccessfulMessage": [
"### Awesome! I've added you to the following developer channels:",
"~bugs - To help investigate or report bugs",
"~customer-support - To troubleshoot and resolve customer issues",
"~leads - To discuss potential accounts with other Customer Engineers"
]
}
]
},
{
"TeamName": "devsecops",
"DelayInSeconds": 5,
"Message": [
"### Welcome {{.UserDisplayName}} to the {{.Team.DisplayName}} team!",
"",
"**If you're not a member of the Security Meta Team and ended up on this team by accident, please report this issue and leave the team!**",
"",
"##### I've added you to a few channels to get you started:",
"",
"~escalation-process - To review the DevSecOps escalation process",
"~incidents - To collaborate on and resolve security incidents"
],
"Actions" : [
{
"ActionType": "automatic",
"ChannelsAddedTo": ["escalation-process", "incidents"]
}
]
}
]
}
},
"PluginStates": {
"com.mattermost.welcomebot": {
"Enable": true
}
}We've used {{.UserDisplayName}} and {{.Team.DisplayName}} in the example config.json. You can insert any variable from the MessageTemplate struct, which has the following fields:
type MessageTemplate struct {
WelcomeBot *model.User
User *model.User
Team *model.Team
Townsquare *model.Channel
DirectMessage *model.Channel
UserDisplayName string
}Development
This plugin contains a server portion. Read our documentation about the Developer Workflow and Developer Setup for more information about developing and extending plugins.
Releasing new versions
The version of a plugin is determined at compile time, automatically populating a version field in the plugin manifest:
- If the current commit matches a tag, the version will match after stripping any leading
v, e.g.1.3.1. - Otherwise, the version will combine the nearest tag with
git rev-parse --short HEAD, e.g.1.3.1+d06e53e1. - If there is no version tag, an empty version will be combined with the short hash, e.g.
0.0.0+76081421.
To disable this behaviour, manually populate and maintain the version field.