https://github.com/mattermost-community/mattermost-plugin-welcomebot
https://github.com/mattermost-community/mattermost-plugin-welcomebot
hacktoberfest mattermost mattermost-plugin
Last synced: about 1 month ago
JSON representation
- Host: GitHub
- URL: https://github.com/mattermost-community/mattermost-plugin-welcomebot
- Owner: mattermost-community
- License: apache-2.0
- Created: 2018-09-15T03:25:48.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2026-04-23T18:28:08.000Z (about 2 months ago)
- Last Synced: 2026-04-23T20:19:21.828Z (about 1 month ago)
- Topics: hacktoberfest, mattermost, mattermost-plugin
- Language: Go
- Homepage:
- Size: 708 KB
- Stars: 72
- Watchers: 30
- Forks: 41
- Open Issues: 39
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# 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
[](https://circleci.com/gh/mattermost/mattermost-plugin-welcomebot)
[](https://codecov.io/gh/mattermost/mattermost-plugin-welcomebot)
[](https://github.com/mattermost/mattermost-plugin-welcomebot/releases/latest)
[](https://github.com/mattermost/mattermost-plugin-welcomebot/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22Up+For+Grabs%22+label%3A%22Help+Wanted%22)
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
1. 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](https://github.com/mattermost/mattermost-plugin-welcomebot/releases), download the latest release, and upload it to your Mattermost instance [following this documentation](https://docs.mattermost.com/administration/plugins.html#plugin-uploads).
2. Modify your `config.json` file to include your Welcome Bot's messages and actions, under the `PluginSettings`. See below for an example of what this should look like.
3. 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.
## 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 `button` or `automatic`. When `button`: enables uses to select which types of channels they want to join. When `automatic`: 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
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
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.
### Setting a channel welcome manually
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
```
### Setting channel welcomes programmatically
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.
```bash
# 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 " \
-H "Content-Type: application/json" \
-d "{\"channel_id\": \"${CHANNEL_ID}\", \"message\": \"Welcome to #general!\"}" \
http:///plugins/com.mattermost.welcomebot/admin/set_channel_welcome
```
The 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.
### Re-showing a missed welcome
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.
## Known Limitations
### Channel welcome ephemerals can be missed on auto-join
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.
## 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:
```go
type MessageTemplate struct {
WelcomeBot *model.User
User *model.User
Team *model.Team
Townsquare *model.Channel
DirectMessage *model.Channel
UserDisplayName string
SiteURL string
}
```
## Development
This plugin contains a server portion. Read our documentation about the [Developer Workflow](https://developers.mattermost.com/integrate/plugins/developer-workflow/) and [Developer Setup](https://developers.mattermost.com/integrate/plugins/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](plugin.json):
* 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.