Channels
- class matterapi.endpoints.async_api.ChannelsApi(client: matterapi.client.base.BaseClient, skip_response_parsing: bool = False)
Endpoints for creating, getting and interacting with channels.
- async add_channel_member(channel_id: str, *, json_body: Union[matterapi.models.AddChannelMemberJsonBody, Dict]) matterapi.models.ChannelMember
Add user to channel
Add a user to a channel by creating a channel member object.
- Api Reference:
- async autocomplete_channels_for_team(team_id: str, *, name: str) List[matterapi.models.Channel]
Autocomplete channels
Autocomplete public channels on a team based on the search term provided in the request URL.
- Permissions:
Must have the list_team_channels permission.
- Minimum Server Version:
4.7
- Api Reference:
- async autocomplete_channels_for_team_for_search(team_id: str, *, name: str) List[matterapi.models.Channel]
Autocomplete channels for search
Autocomplete your channels on a team based on the search term provided in the request URL.
- Permissions:
Must have the list_team_channels permission.
- Minimum Server Version:
5.4
- Api Reference:
- async channel_members_minus_group_members(channel_id: str, *, group_ids: str = '', page: Optional[int] = 0, per_page: Optional[int] = 0) None
Channel members minus group members.
Get the set of users who are members of the channel minus the set of users who are members of the given groups. Each user object contains an array of group objects representing the group memberships for that user. Each user object contains the boolean fields scheme_guest, scheme_user, and scheme_admin representing the roles that user has for the given channel.
- Permissions:
Must have manage_system permission.
- Minimum Server Version:
5.14
- Api Reference:
- async create_channel(*, json_body: Union[matterapi.models.CreateChannelJsonBody, Dict]) matterapi.models.Channel
Create a channel
Create a new channel.
- Permissions:
If creating a public channel, create_public_channel permission is required. If creating a private channel, create_private_channel permission is required.
- Api Reference:
- async create_direct_channel(*, json_body: Union[List[str], Dict]) matterapi.models.Channel
Create a direct message channel
Create a new direct message channel between two users.
- Permissions:
Must be one of the two users and have create_direct_channel permission. Having the manage_system permission voids the previous requirements.
- Api Reference:
- async create_group_channel(*, json_body: Union[List[str], Dict]) matterapi.models.Channel
Create a group message channel
Create a new group message channel to group of users. If the logged in user’s id is not included in the list, it will be appended to the end.
- Permissions:
Must have create_group_channel permission.
- Api Reference:
- async create_sidebar_category_for_team_for_user(team_id: str, user_id: str, *, json_body: Union[matterapi.models.SidebarCategory, Dict]) matterapi.models.SidebarCategory
Create user’s sidebar category
Create a custom sidebar category for the user on the given team.
- Permissions:
Must be authenticated and have the list_team_channels permission.
- Minimum Server Version:
5.26
- Api Reference:
- async delete_channel(channel_id: str) matterapi.models.StatusOK
Delete a channel
Archives a channel. This will set the deleteAt to the current timestamp in the database. Soft deleted channels may not be accessible in the user interface. They can be viewed and unarchived in the System Console > User Management > Channels based on your license. Direct and group message channels cannot be deleted.
As of server version 5.28, optionally use the permanent=true query parameter to permanently delete the channel for compliance reasons. To use this feature ServiceSettings.EnableAPIChannelDeletion must be set to true in the server’s configuration. If you permanently delete a channel this action is not recoverable outside of a database backup.
delete_private_channel permission if the channel is private, or have manage_system permission.
- Permissions:
delete_public_channel permission if the channel is public,
- Api Reference:
- async get_all_channels(*, not_associated_to_group: Optional[str] = None, page: Optional[int] = 0, per_page: Optional[int] = 0, exclude_default_channels: Optional[bool] = False, include_deleted: Optional[bool] = False, include_total_count: Optional[bool] = False, exclude_policy_constrained: Optional[bool] = False) matterapi.models.ChannelListWithTeamData
Get a list of all channels
- Permissions:
manage_system
- Api Reference:
- async get_channel(channel_id: str) matterapi.models.Channel
Get a channel
Get channel from the provided channel id string.
- Permissions:
read_channel permission for the channel.
- Api Reference:
- async get_channel_by_name(team_id: str, channel_name: str, *, include_deleted: Optional[bool] = False) matterapi.models.Channel
Get a channel by name
Gets channel from the provided team id and channel name strings.
- Permissions:
read_channel permission for the channel.
- Api Reference:
- async get_channel_by_name_for_team_name(team_name: str, channel_name: str, *, include_deleted: Optional[bool] = False) matterapi.models.Channel
Get a channel by name and team name
Gets a channel from the provided team name and channel name strings.
- Permissions:
read_channel permission for the channel.
- Api Reference:
- async get_channel_member(channel_id: str, user_id: str) matterapi.models.ChannelMember
Get channel member
Get a channel member.
- Permissions:
read_channel permission for the channel.
- Api Reference:
- async get_channel_member_counts_by_group(channel_id: str, *, include_timezones: Optional[bool] = False) None
Channel members counts for each group that has atleast one member in the channel
Returns a set of ChannelMemberCountByGroup objects which contain a group_id, channel_member_count and a channel_member_timezones_count.
- Permissions:
Must have read_channel permission for the given channel.
- Minimum Server Version:
5.24
- Api Reference:
- async get_channel_members(channel_id: str, *, page: Optional[int] = 0, per_page: Optional[int] = 60) List[matterapi.models.ChannelMember]
Get channel members
Get a page of members for a channel.
- Permissions:
read_channel permission for the channel.
- Api Reference:
- async get_channel_members_by_ids(channel_id: str, *, json_body: Union[List[str], Dict]) List[matterapi.models.ChannelMember]
Get channel members by ids
Get a list of channel members based on the provided user ids.
- Permissions:
Must have the read_channel permission.
- Api Reference:
- async get_channel_members_for_user(user_id: str, team_id: str) List[matterapi.models.ChannelMember]
Get channel memberships and roles for a user
Get all channel memberships and associated membership roles (i.e. channel_user, channel_admin) for a user on a specific team.
- Permissions:
Logged in as the user and view_team permission for the team. Having manage_system permission voids the previous requirements.
- Api Reference:
- async get_channel_members_timezones(channel_id: str) List[str]
Get timezones in a channel
Get a list of timezones for the users who are in this channel.
- Permissions:
Must have the read_channel permission.
- Minimum Server Version:
5.6
- Api Reference:
- async get_channel_moderations(channel_id: str) List[matterapi.models.ChannelModeration]
Get information about channel’s moderation.
- Permissions:
Must have manage_system permission.
- Minimum Server Version:
5.22
- Api Reference:
- async get_channel_stats(channel_id: str) matterapi.models.ChannelStats
Get channel statistics
Get statistics for a channel.
- Permissions:
Must have the read_channel permission.
- Api Reference:
- async get_channel_unread(user_id: str, channel_id: str) matterapi.models.ChannelUnread
Get unread messages
Get the total unread messages and mentions for a channel for a user.
- Permissions:
Must be logged in as user and have the read_channel permission, or have edit_other_usrs permission.
- Api Reference:
- async get_channels_for_team_for_user(user_id: str, team_id: str, *, include_deleted: Optional[bool] = False, last_delete_at: Optional[int] = 0) List[matterapi.models.Channel]
Get channels for user
Get all the channels on a team for a user.
- Permissions:
Logged in as the user, or have edit_other_users permission, and view_team permission for the team.
- Api Reference:
- async get_channels_for_user(user_id: str, *, last_delete_at: Optional[int] = 0, include_deleted: Optional[bool] = False) List[matterapi.models.Channel]
Get all channels from all teams
Get all channels from all teams that a user is a member of.
- Permissions:
Logged in as the user, or have edit_other_users permission.
- Minimum Server Version:
6.1
- Api Reference:
- async get_deleted_channels_for_team(team_id: str, *, page: Optional[int] = 0, per_page: Optional[int] = 60) List[matterapi.models.Channel]
Get deleted channels
Get a page of deleted channels on a team based on query string parameters - team_id, page and per_page.
- Minimum Server Version:
3.10
- Api Reference:
- async get_pinned_posts(channel_id: str) matterapi.models.PostList
Get a channel’s pinned posts
Get a list of pinned posts for channel.
- Api Reference:
- async get_private_channels_for_team(team_id: str, *, page: Optional[int] = 0, per_page: Optional[int] = 60) List[matterapi.models.Channel]
Get private channels
Get a page of private channels on a team based on query string parameters - team_id, page and per_page.
- Permissions:
Must have manage_system permission.
- Minimum Server Version:
5.26
- Api Reference:
- async get_public_channels_by_ids_for_team(team_id: str, *, json_body: Union[List[str], Dict]) List[matterapi.models.Channel]
Get a list of channels by ids
Get a list of public channels on a team by id.
- Permissions:
view_team for the team the channels are on.
- Api Reference:
- async get_public_channels_for_team(team_id: str, *, page: Optional[int] = 0, per_page: Optional[int] = 60) List[matterapi.models.Channel]
Get public channels
Get a page of public channels on a team based on query string parameters - page and per_page.
- Permissions:
Must be authenticated and have the list_team_channels permission.
- Api Reference:
- async get_sidebar_categories_for_team_for_user(team_id: str, user_id: str) List[matterapi.models.OrderedSidebarCategories]
Get user’s sidebar categories
Get a list of sidebar categories that will appear in the user’s sidebar on the given team, including a list of channel IDs in each category.
- Permissions:
Must be authenticated and have the list_team_channels permission.
- Minimum Server Version:
5.26
- Api Reference:
- async get_sidebar_category_for_team_for_user(team_id: str, user_id: str, category_id: str) matterapi.models.SidebarCategory
Get sidebar category
Returns a single sidebar category for the user on the given team.
- Permissions:
Must be authenticated and have the list_team_channels permission.
- Minimum Server Version:
5.26
- Api Reference:
- async get_sidebar_category_order_for_team_for_user(team_id: str, user_id: str) List[str]
Get user’s sidebar category order
Returns the order of the sidebar categories for a user on the given team as an array of IDs.
- Permissions:
Must be authenticated and have the list_team_channels permission.
- Minimum Server Version:
5.26
- Api Reference:
- async move_channel(channel_id: str, *, json_body: Union[matterapi.models.MoveChannelJsonBody, Dict]) matterapi.models.Channel
Move a channel
Move a channel to another team.
- Permissions:
Must have manage_system permission.
- Minimum Server Version:
5.26
- Api Reference:
- async patch_channel(channel_id: str, *, json_body: Union[matterapi.models.PatchChannelJsonBody, Dict]) matterapi.models.Channel
Patch a channel
Partially update a channel by providing only the fields you want to update. Omitted fields will not be updated. The fields that can be updated are defined in the request body, all other provided fields will be ignored.
- Permissions:
If updating a public channel, manage_public_channel_members permission is required. If updating a private channel, manage_private_channel_members permission is required.
- Api Reference:
- async patch_channel_moderations(channel_id: str, *, json_body: Union[matterapi.models.ChannelModerationPatch, Dict]) List[matterapi.models.ChannelModeration]
Update a channel’s moderation settings.
- Permissions:
Must have manage_system permission.
- Minimum Server Version:
5.22
- Api Reference:
- async remove_sidebar_category_for_team_for_user(team_id: str, user_id: str, category_id: str) matterapi.models.SidebarCategory
Delete sidebar category
Deletes a single sidebar category for the user on the given team. Only custom categories can be deleted.
- Permissions:
Must be authenticated and have the list_team_channels permission.
- Minimum Server Version:
5.26
- Api Reference:
- async remove_user_from_channel(channel_id: str, user_id: str) matterapi.models.StatusOK
Remove user from channel
Delete a channel member, effectively removing them from a channel.
In server version 5.3 and later, channel members can only be deleted from public or private channels. manage_private_channel_members permission if the channel is private.
- Permissions:
manage_public_channel_members permission if the channel is public.
- Api Reference:
- async restore_channel(channel_id: str) matterapi.models.Channel
Restore a channel
Restore channel from the provided channel id string.
- Permissions:
manage_team permission for the team of the channel.
- Minimum Server Version:
3.10
- Api Reference:
- async search_all_channels(*, json_body: Union[matterapi.models.SearchAllChannelsJsonBody, Dict], system_console: Optional[bool] = True) matterapi.models.SearchAllChannelsResponse200
Search all private and open type channels across all teams
Returns all private and open type channels where ‘term’ matches on the name, display name, or purpose of the channel.
Configured ‘default’ channels (ex Town Square and Off-Topic) can be excluded from the results with the exclude_default_channels boolean parameter.
Channels that are associated (via GroupChannel records) to a given group can be excluded from the results with the not_associated_to_group parameter and a group id string.
- Api Reference:
- async search_archived_channels(team_id: str, *, json_body: Union[matterapi.models.SearchArchivedChannelsJsonBody, Dict]) List[matterapi.models.Channel]
Search archived channels
Search archived channels on a team based on the search term provided in the request body.
In server version 5.18 and later, a user without the list_team_channels permission will be able to use this endpoint, with the search results limited to the channels that the user is a member of.
- Permissions:
Must have the list_team_channels permission.
- Minimum Server Version:
5.18
- Api Reference:
- async search_channels(team_id: str, *, json_body: Union[matterapi.models.SearchChannelsJsonBody, Dict]) List[matterapi.models.Channel]
Search channels
Search public channels on a team based on the search term provided in the request body.
In server version 5.16 and later, a user without the list_team_channels permission will be able to use this endpoint, with the search results limited to the channels that the user is a member of.
- Permissions:
Must have the list_team_channels permission.
- Api Reference:
- async search_group_channels(*, json_body: Union[matterapi.models.SearchGroupChannelsJsonBody, Dict]) List[matterapi.models.Channel]
Search Group Channels
Get a list of group channels for a user which members’ usernames match the search term.
- Minimum Server Version:
5.14
- Api Reference:
- async update_channel(channel_id: str, *, json_body: Union[matterapi.models.UpdateChannelJsonBody, Dict]) matterapi.models.Channel
Update a channel
Update a channel. The fields that can be updated are listed as parameters. Omitted fields will be treated as blanks.
- Permissions:
If updating a public channel, manage_public_channel_members permission is required. If updating a private channel, manage_private_channel_members permission is required.
- Api Reference:
- async update_channel_member_scheme_roles(channel_id: str, user_id: str, *, json_body: Union[matterapi.models.UpdateChannelMemberSchemeRolesJsonBody, Dict]) matterapi.models.StatusOK
Update the scheme-derived roles of a channel member.
Update a channel member’s scheme_admin/scheme_user properties. Typically this should either be scheme_admin=false, scheme_user=true for ordinary channel member, or scheme_admin=true, scheme_user=true for a channel admin.
- Permissions:
Must be authenticated and have the manage_channel_roles permission.
- Minimum Server Version:
5.0
- Api Reference:
- async update_channel_notify_props(channel_id: str, user_id: str, *, json_body: Union[matterapi.models.ChannelNotifyProps, Dict]) matterapi.models.StatusOK
Update channel notifications
Update a user’s notification properties for a channel. Only the provided fields are updated.
- Permissions:
Must be logged in as the user or have edit_other_users permission.
- Api Reference:
- async update_channel_privacy(channel_id: str, *, json_body: Union[matterapi.models.UpdateChannelPrivacyJsonBody, Dict]) matterapi.models.Channel
Update channel’s privacy
Updates channel’s privacy allowing changing a channel from Public to Private and back.
- Permissions:
manage_team permission for the channels team on version < 5.28. convert_public_channel_to_private permission for the channel if updating privacy to ‘P’ on version >= 5.28. convert_private_channel_to_public permission for the channel if updating privacy to ‘O’ on version >= 5.28.
- Minimum Server Version:
5.16
- Api Reference:
- async update_channel_roles(channel_id: str, user_id: str, *, json_body: Union[matterapi.models.UpdateChannelRolesJsonBody, Dict]) matterapi.models.StatusOK
Update channel roles
Update a user’s roles for a channel.
- Permissions:
Must have manage_channel_roles permission for the channel.
- Api Reference:
- async update_channel_scheme(channel_id: str, *, json_body: Union[matterapi.models.UpdateChannelSchemeJsonBody, Dict]) matterapi.models.StatusOK
Set a channel’s scheme
Set a channel’s scheme, more specifically sets the scheme_id value of a channel record.
- Permissions:
Must have manage_system permission.
- Minimum Server Version:
4.10
- Api Reference:
- async update_sidebar_categories_for_team_for_user(team_id: str, user_id: str, *, json_body: Union[List[matterapi.models.SidebarCategory], Dict]) matterapi.models.SidebarCategory
Update user’s sidebar categories
Update any number of sidebar categories for the user on the given team. This can be used to reorder the channels in these categories.
- Permissions:
Must be authenticated and have the list_team_channels permission.
- Minimum Server Version:
5.26
- Api Reference:
- async update_sidebar_category_for_team_for_user(team_id: str, user_id: str, category_id: str, *, json_body: Union[matterapi.models.SidebarCategory, Dict]) matterapi.models.SidebarCategory
Update sidebar category
Updates a single sidebar category for the user on the given team.
- Permissions:
Must be authenticated and have the list_team_channels permission.
- Minimum Server Version:
5.26
- Api Reference:
- async update_sidebar_category_order_for_team_for_user(team_id: str, user_id: str, *, json_body: Union[List[str], Dict]) List[str]
Update user’s sidebar category order
Updates the order of the sidebar categories for a user on the given team. The provided array must include the IDs of all categories on the team.
- Permissions:
Must be authenticated and have the list_team_channels permission.
- Minimum Server Version:
5.26
- Api Reference:
- async view_channel(user_id: str, *, json_body: Union[matterapi.models.ViewChannelJsonBody, Dict]) matterapi.models.ViewChannelResponse200
View channel
Perform all the actions involved in viewing a channel. This includes marking channels as read, clearing push notifications, and updating the active channel.
__Response only includes last_viewed_at_times in Mattermost server 4.3 and newer.__
- Permissions:
Must be logged in as user or have edit_other_users permission.
- Api Reference: