Mattermost Notify

Mattermost Notification Skill

This skill teaches you how to send Mattermost direct messages and notifications correctly.

Prerequisites

• Mattermost MCP tools available (mattermost_*)
• Already authenticated (token set via mattermost_set_auth_token or mattermost_login)

When to Use This Skill

• Long-running tasks (5+ minutes): Notify when complete
• Task failures: Notify with error details
• User requests: When user explicitly asks for notification
• Important updates: Status changes requiring attention

Core Workflows

1. Send a DM to a Specific User

Step-by-step:

1. Find the user by username:

   mattermost_get_user_by_username({ username: "yevgeniy" })
   

   Returns: { id: "user-uuid", username: "yevgeniy", ... }

2. Create a direct channel with the user:

   mattermost_create_direct_channel({ user_id: "<user-uuid>" })
   

   Returns: { id: "channel-uuid", ... }

3. Post the message:

   mattermost_post_message({
     channel_id: "<channel-uuid>",
     message: "Your message here"
   })
   

2. Notify About Task Completion

Template for success notification:

mattermost_post_message({
  channel_id: "<dm-channel-id>",
  message: `**Task Completed**

**Task**: <task-name>
**Status**: Success
**Duration**: <time-taken>

**Summary**: <brief-description-of-what-was-done>

**Next steps**: <any-follow-up-actions-needed>`
})

3. Notify About Task Failure

Template for error notification:

mattermost_post_message({
  channel_id: "<dm-channel-id>",
  message: `**Task Failed**

**Task**: <task-name>
**Status**: Failed
**Error**: <error-message>

**Details**:
\`\`\`
<stack-trace-or-error-details>
\`\`\`

**Suggested fix**: <what-might-resolve-the-issue>
**Action needed**: <what-user-should-do-next>`
})

4. Reply to an Existing Thread

If there's an existing conversation thread:

mattermost_post_message({
  channel_id: "<channel-id>",
  message: "Your reply message",
  root_id: "<parent-post-id>"  # This makes it a threaded reply
})

Message Formatting

Mattermost supports Markdown:

• Bold: **text**
• Italic: *text*
• Strikethrough: ~~text~~
• Code: `code`
• Code blocks: ```language\ncode\n```
• Links: [text](url)
• Lists: - item or 1. item
• Headers: # H1, ## H2, etc.
• Mentions: @username

Common Notification Templates

Build/Deploy Complete

**Deployment Successful**

**Service**: my-service-name
**Environment**: production
**Version**: v1.2.3
**URL**: https://my-service.dev.hyperplane.dev

Deployment completed in 45 seconds.

Long Task Progress Update

**Progress Update**

**Task**: Data processing pipeline
**Progress**: 75% complete (750/1000 records)
**ETA**: ~5 minutes remaining

Processing continues...

Error with Context

**Error Alert**

**Service**: my-api
**Error Type**: ConnectionError
**Time**: 2026-01-19 12:30:00 UTC

**Error Message**:
\`\`\`
Failed to connect to database: connection refused
\`\`\`

**Relevant Logs**:
\`\`\`
2026-01-19 12:29:58 Attempting connection...
2026-01-19 12:30:00 Connection timeout after 30s
\`\`\`

**Suggested Actions**:
1. Check if database pod is running
2. Verify network policies allow connection
3. Check database credentials

Advanced Workflows

Send to a Channel (Not DM)

1. Get team ID:

   mattermost_get_teams()
   

2. Find channel by name:

   mattermost_get_channel_by_name({
     team_id: "<team-uuid>",
     channel_name: "general"
   })
   

3. Post to channel:

   mattermost_post_message({
     channel_id: "<channel-uuid>",
     message: "Message to channel"
   })
   

Check for User Response

After sending a message, check if user replied:

mattermost_get_thread({ post_id: "<your-message-id>" })

Or check for specific user response:

mattermost_check_user_response({
  post_id: "<your-message-id>",
  user_id: "<user-uuid>"
})

Add Reaction to a Post

mattermost_add_reaction({
  post_id: "<post-id>",
  emoji_name: "white_check_mark"  # No colons
})

Common emoji names: white_check_mark, x, eyes, rocket, thumbsup, thumbsdown

Bot Management

Creating a Bot Account

Important: The standard MCP token (shakudobabyagi) cannot create bots due to a permission restriction. You must use a token from the yevgeniy user.

Step-by-step workflow:

1. Create a token for yevgeniy (using the admin token):

   curl -X POST "http://mattermost-mattermost-enterprise-edition.hyperplane-mattermost.svc.cluster.local:8065/api/v4/users/ibzbp75tzbdc7r8ctnw91j7c6e/tokens" \
     -H "Authorization: Bearer hb1o5s59stgkimh4hfbbjuwyro" \
     -H "Content-Type: application/json" \
     -d '{"description": "bot-creation-token"}'
   

   Save the returned token value.

2. Create the bot (using yevgeniy's token):

   curl -X POST "http://mattermost-mattermost-enterprise-edition.hyperplane-mattermost.svc.cluster.local:8065/api/v4/bots" \
     -H "Authorization: Bearer <yevgeniy-token>" \
     -H "Content-Type: application/json" \
     -d '{"username": "my-new-bot", "display_name": "My New Bot", "description": "Bot purpose"}'
   

   Save the returned user_id for the bot.

3. Create an access token for the bot:

   curl -X POST "http://mattermost-mattermost-enterprise-edition.hyperplane-mattermost.svc.cluster.local:8065/api/v4/users/<bot-user-id>/tokens" \
     -H "Authorization: Bearer <yevgeniy-token>" \
     -H "Content-Type: application/json" \
     -d '{"description": "bot-access-token"}'
   

   The returned token is what the bot uses for authentication.

List Existing Bots

curl -s "http://mattermost-mattermost-enterprise-edition.hyperplane-mattermost.svc.cluster.local:8065/api/v4/bots" \
  -H "Authorization: Bearer hb1o5s59stgkimh4hfbbjuwyro" | jq '.'

Known Bots

Why Bot Creation Requires Special Handling

The shakudobabyagi user has system_admin role with create_bot permission, but Mattermost still returns 403. This appears to be a token-specific or user-specific restriction. The yevgeniy user (owner of existing bots) can create bots successfully.

Key user IDs:

• yevgeniy: ibzbp75tzbdc7r8ctnw91j7c6e
• shakudobabyagi: hyf6w6wd83887ctj7wzrmwk4nc

Best Practices

1. Be concise: Keep messages short and scannable
2. Use formatting: Bold for key info, code blocks for errors
3. Include context: Task name, status, and relevant details
4. Suggest actions: Always tell user what to do next
5. Don't spam: Only notify for significant events
6. Thread replies: Use root_id to keep conversations organized

Known Users

When sending DMs to Shakudo team members:

To find other users:

mattermost_get_teams()  # Get team ID first
mattermost_search_posts({ team_id: "<team-id>", terms: "from:username" })