Create a channel bookmark.

Creates a link bookmark (URL) or file bookmark (attached file). For link type, link_url is required. For file type, file_id is required (from upload_file).

Note: Requires Entry, Professional, Enterprise, or Enterprise Advanced edition (not available in Team Edition). Minimum version: v10.1.

Delete a channel bookmark.

Archives the bookmark (soft delete via delete_at timestamp). The bookmark will no longer appear in the channel.

Note: Requires Entry, Professional, Enterprise, or Enterprise Advanced edition (not available in Team Edition). Minimum version: v10.1.

List all bookmarks in a channel.

Returns bookmarks in sort order. Use to see saved links and files pinned to a channel. For searching messages, use search_messages instead.

Note: Requires Entry, Professional, Enterprise, or Enterprise Advanced edition (not available in Team Edition). Minimum version: v10.1.

Update a channel bookmark.

Partially updates bookmark properties. Only provided fields are updated; others remain unchanged.

Note: Requires Entry, Professional, Enterprise, or Enterprise Advanced edition (not available in Team Edition). Minimum version: v10.1.

Reorder a channel bookmark.

Moves the bookmark to the specified position. Other bookmarks are automatically adjusted. Returns all affected bookmarks with updated positions.

Note: Requires Entry, Professional, Enterprise, or Enterprise Advanced edition (not available in Team Edition). Minimum version: v10.1.

Add a user to a channel.

Requires permission to manage channel members. Adding a user who is already in the channel has no additional effect.

Create a new channel in a team.

Creates either a public (O) or private (P) channel. The authenticated user becomes the channel admin. Each call creates a new channel; use get_channel_by_name to check if it exists.

Create a direct message channel between two users.

Returns an existing DM channel if one already exists between the users. Use this to get a channel ID for sending private messages. Then use post_message with the returned channel_id to send messages.

Get detailed information about a specific channel.

Returns channel metadata including name, purpose, header, and member count. Use when you have the channel ID. For lookup by channel name, use get_channel_by_name instead.

Get a channel by its name within a team.

Returns channel metadata including name, purpose, header, and member count. Use when you know the channel name but not the ID. For lookup by ID, use get_channel instead.

Get members of a channel.

Returns list of users who are members of the channel. Use to see who can receive messages in a channel.

Join a public channel.

Adds the authenticated user to the channel. Cannot be used to join private channels. Joining a channel you're already in has no additional effect.

Leave a channel.

Removes the authenticated user from the channel. Cannot leave Town Square or other default channels. Can rejoin public channels later with join_channel.

List channels you are a member of in a team.

Returns your channels with unread counters and the read marker for the authenticated user. Two counter pairs are provided:

• unread_msg_count / mention_count count thread replies too (the channel badge with Collapsed Reply Threads off — the team default).

• unread_msg_count_root / mention_count_root count only root posts (the badge with Collapsed Reply Threads on).

last_viewed_at is the user's read marker for the channel. Pass it as get_channel_messages(channel_id, since=last_viewed_at) for incremental sync, or use get_channel_messages(channel_id, unread_only=True) for the unread window (preferred — deterministic and edit-noise-free).

Channels without a membership record report 0 for all counters and last_viewed_at.

Use channel_types to narrow results: ["O", "P"] for workspace channels without DMs, or ["D"] for direct messages only. Use only_unread=True to get only channels with unread messages. For discovering public channels you haven't joined yet, use list_public_channels.

List public channels available in a team.

Returns all public channels for discovery, including ones you haven't joined. Results are paginated. Use page/per_page to retrieve all channels. Useful for finding channels to join. For channels you are already a member of (including private), use list_my_channels.

Mark a channel as read for the authenticated user.

Clears unread counters and advances last_viewed_at. Use when the user asks to clear unreads, when a bot has processed get_channel_messages(unread_only=True) and needs to advance read state for the next poll, or as a one-shot bootstrap on a channel with last_viewed_at == 0 so unread_only queries return posts.

Do NOT call on accounts shared with humans — it clears their UI badge.

Download a file attachment and save it to a local directory.

Counterpart of upload_file: fetches the content of a file by its ID (from a post's file_ids or get_file_info) and writes it to disk. Returns the local path so the file can be read or processed further. Use on_conflict="rename" to save all same-named attachments without replacing any. Always use the returned path; parallel calls may assign numbers in any order. Each repeated call in rename mode saves another copy. overwrite=True cannot be combined with on_conflict="error" or "rename". Files larger than 100 MB are refused.

Get metadata about an uploaded file.

Returns file name, size, type, and upload information. Use to check file details before downloading or sharing.

Get a public link to download a file.

Link can be shared with users who don't have Mattermost access. Link may expire based on server settings.

Upload a file to a channel.

The file will be attached to messages in the specified channel. Returns file ID that can be used when posting messages with file_ids parameter.

Delete a message permanently.

Can only delete your own messages (unless admin). Deleted messages cannot be recovered. All reactions and thread context will be lost.

Get messages from a channel — recent history, the user's unread window, or posts changed since a watermark.

Three mutually-exclusive modes. Pick by user intent:

• "Show last N" / "what's in this channel" → default (page, per_page). Reverse-chronological. truncated=True ⇒ more posts exist; paginate.

• "What did I miss" → unread_only=True. The user's unread window anchored at last_viewed_at, with limit_before context posts. Quirk: on a never-viewed channel (last_viewed_at == 0) order is empty even when unread_msg_count > 0 — call mark_channel_viewed once to bootstrap.

• "Sync everything since " → since=<unix_ms>. Posts with update_at > since, including edits of older posts and tombstones (delete_at != 0, empty message). Server caps at 1000; on truncated=True step the watermark forward in smaller windows.

Returns {order, posts, truncated}. posts may contain more entries than order (root posts pulled in by thread replies). System posts (type starts with "system_") appear in unread_only/since responses but are NOT counted in unread_msg_count.

For keyword search use search_messages; for full threads use get_thread.

Post a message to a Mattermost channel.

Send text messages with Markdown support. Use root_id to reply in a thread. Use file_ids to attach uploaded files. Use attachments for rich formatted content. To read all messages in a thread, use get_thread.

Attachment examples:

• Status alert: {"color": "danger", "title": "Build Failed", "text": "Tests failed on main"}

• Success notification: {"color": "good", "title": "Deployed", "text": "v1.2.3 is live"}

• With fields: {"title": "Ticket", "fields": [{"title": "Status", "value": "Open", "short": true}]}

Search for messages matching specific criteria across channels.

Searches message content within a team. For simply reading recent channel messages, use get_channel_messages instead.

Search syntax examples:

• Simple text: "deployment error"

• From user: "from:username bug"

• In channel: "in:channel-name release"

• Date range: "after:2024-01-01 before:2024-02-01"

• Combined: "from:alice in:dev-ops deployment failed"

Edit an existing message.

Can only edit your own messages (unless admin). The message will show as edited. Original content is replaced; edit history is not preserved.

Attachment examples:

• Status alert: {"color": "danger", "title": "Build Failed", "text": "Tests failed on main"}

• With fields: {"title": "Ticket", "fields": [{"title": "Status", "value": "Open", "short": true}]}

Add an emoji reaction to a message.

Adds a reaction from the authenticated user. Common emojis: thumbsup, thumbsdown, smile, heart, eyes. Adding the same reaction twice has no additional effect.

Get all reactions on a message.

Returns list of reactions with emoji names and user IDs. Use to see who reacted to a message and with what emoji.

Get all messages in a thread.

Returns the root post and all replies in chronological order. Use to read full conversation context before replying.

Pin a message in a channel.

Pinned messages appear in the channel's pinned posts section. Pinning an already pinned message has no additional effect.

Remove your emoji reaction from a message.

Removes a reaction previously added by the authenticated user. Removing a non-existent reaction has no effect.

Unpin a message from a channel.

Removes the message from the channel's pinned posts. Unpinning a non-pinned message has no effect.

Get team details by ID.

Returns team name, description, and settings. Use when you have the team ID and need detailed information.

Get members of a team.

Returns list of users who belong to the team. Use to discover users before sending direct messages or mentions.

List teams the current user belongs to.

Returns team name, description, and settings. Use this to discover available teams before listing channels.

Get the current authenticated user's profile.

Returns user information including username, email, and status. Use to get your own user ID for operations like create_direct_channel.

Get a user's profile by their ID.

Returns user information including username, email, and status. Use when you have the user ID. For lookup by @username, use get_user_by_username instead.

Get a user's profile by their username.

Returns user information including username, email, and status. Use when you know the @username but not the user ID. For lookup by ID, use get_user instead.

Get a user's online/offline status.

Returns: online, away, dnd (do not disturb), or offline. Use to check if a user is available before sending a message.

Search for users by name or username.

Searches across username, first name, last name, and nickname. Use to find users when you don't know their exact username or ID.