Tag channels

info

• Create tag data before setting tags on channels. See Manage tag data.
• This feature does not apply to open channels or community channels.

Each user can create up to 20 tags, with up to 1000 channels per tag. Adding a channel beyond the 1000-channel limit succeeds but removes the earliest tagged channel.

Use cases

Channel tags allow users to categorize channels into groups. After creating tags, users can assign one or more tags to channels.

Tagged channels support grouped retrieval, display, deletion, per-tag unread counts, and per-tag pinning.

Tag a channel

Add a channel to a tag

Use tag.addChannel() on a Tag instance:

Dart

await tag.addChannel(
  ChannelIdentifier(channelType: ChannelType.direct, channelId: '<target-user-id>'),
  (error) {
    if (error == null) {
      print('Channel added to tag');
    }
  },
);

Remove a channel from a tag

Dart

await tag.deleteChannelFromTag(
  ChannelIdentifier(channelType: ChannelType.direct, channelId: '<target-user-id>'),
  (error) {
    if (error == null) {
      print('Channel removed from tag');
    }
  },
);

Remove tags from a channel

Call channel.deleteTags() on the channel instance:

Dart

final channel = DirectChannel('<target-user-id>');
await channel.deleteTags(['<tag-id>'], (error) {
  if (error == null) {
    print('Tags removed from channel');
  }
});

Get a channel's tags

Call channel.getTags() on the channel instance:

Dart

await channel.getTags((tags, error) {
  if (error == null) {
    print('Channel tags: $tags');
  }
});

Operations by tag

Pin a channel within a tag

info

Pinning a channel within a tag is not yet exposed in the Flutter SDK. This section will be updated when the API is available.

Get channels by tag (paginated)

Use tag.createTagChannelsQuery() to create a paginated query for channels under the current tag:

Dart

final query = tag.createTagChannelsQuery(TagChannelsQueryParams(
  tagId: '<tag-id>',
  pageSize: 20,
));

await query.loadNextPage((result, error) {
  if (error == null) {
    print('Channels: ${result?.data.length}');
  }
});

Get unread count by tag

Dart

await tag.getUnreadCount(
  GetUnreadCountByTagParams(containNoDisturb: false),
  (count, error) {
    print('Unread count: $count');
  },
);

Clear unread count by tag

Dart

await tag.clearUnreadCount((error) {
  print('Unread count cleared');
});

Clear channels by tag

Dart

await tag.clearChannels(
  ClearChannelsByTagParams(deleteLocalMessage: false),
  (error) {
    print('Channels cleared from tag');
  },
);