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.
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.
-
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. -
Please ensure that you go to System Console > Site Configuration > Users and Teams and verify the setting for Enable users to open Direct Message channels with:. If the value of this field is set to
Any member of the team, you'll need to add the welcome bot manually to all the teams where it needs to be included.
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./welcomebot welcome- Re-shows the current channel's welcome message as an ephemeral visible only to you. Use this if you missed the welcome when you first joined.
Channel welcome messages are separate from team welcome messages. Where a team welcome is a DM sent when a user joins the team, a channel welcome is an ephemeral post sent when a user joins a specific channel — visible only to that user and not stored in the channel history.
Channel welcome messages are stored in the plugin's KV store and are set per-channel. They are sent as plain text/Markdown exactly as stored — Go template variables such as {{.UserDisplayName}} and {{.SiteURL}} are not expanded. Only open (public) channels are supported.
Navigate to the channel and run:
/welcomebot set_channel_welcome Your welcome message here.
Requires system admin or channel admin role. To verify what is stored:
/welcomebot get_channel_welcome
To remove it:
/welcomebot delete_channel_welcome
Use the POST /admin/set_channel_welcome endpoint to set channel welcome messages from a script without having to manually run slash commands in each channel. This is the recommended approach for initial setup.
# Resolve the channel ID
CHANNEL_ID=$(mmctl channel list engineering --json | jq -r '.[] | select(.name=="general") | .id')
# Set the welcome message
curl -X POST \
-H "Authorization: Bearer <your-personal-access-token>" \
-H "Content-Type: application/json" \
-d "{\"channel_id\": \"${CHANNEL_ID}\", \"message\": \"Welcome to #general!\"}" \
http://<your-mattermost-url>/plugins/com.mattermost.welcomebot/admin/set_channel_welcomeThe caller must be a system admin. The bearer token authenticates to Mattermost, which injects Mattermost-User-Id into the request for the plugin to verify. Private channels are not supported — welcome messages only fire on public channel joins.
Channel welcome ephemerals are not stored server-side. If a user missed the welcome when they joined, they can re-show it at any time:
/welcomebot welcome
This works in any channel that has a welcome message configured.
Channel welcome ephemerals work reliably on a user's first-ever join to a team. At that point, the auto-added channels are cold in the client — no cached state exists — so when the user navigates to each channel, the ephemeral is still live in the WebSocket buffer and renders correctly.
On rejoin (the user left the team and rejoined), the client already has those channels in its local store. When the user opens a channel, the client rehydrates the post list from the server. Because the server never stores ephemerals, the welcome is gone before the page renders and the user never sees it.
This is a Mattermost platform limitation. The server does not provide a UserHasViewedChannel hook or any equivalent event that would allow the plugin to trigger delivery at the moment the user first opens a channel. There is no workaround that guarantees delivery on rejoin without user action.
Recovery: Run /welcomebot welcome in any channel to re-show its welcome message as an ephemeral visible only to you. Mention this command in your onboarding documentation so new users know it exists.
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
SiteURL string
}This plugin contains a server portion. Read our documentation about the Developer Workflow and Developer Setup for more information about developing and extending plugins.
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.