Skip to main content

Get channels

The client SDK generates channels in the local database based on sent and received messages. Use query objects to paginate through the channel list, and use identifier-based lookups when you already know which channels you need.

note

Use the callback to read the final result. For query objects such as ChannelsQuery, pagination results come from loadNextPage().

Get the channel list​

Retrieve channels from the local database with pagination. Channels are sorted by operation time, and pinned channels can be returned first.

Method​

Dart
static ChannelsQuery createChannelsQuery(ChannelsQueryParams params)

ChannelsQueryParams​

ParameterTypeDefaultDescription
channelTypesList<ChannelType>RequiredChannel types to include in the query.
startTimeint0Start timestamp in milliseconds. Use the operationTime of the last channel in the previous page to continue pagination.
pageSizeint20Number of channels per page. Must be greater than 0 and no more than 50.
topPrioritybooltrueWhether pinned channels should be returned before non-pinned channels.

Code example​

Dart
final query = BaseChannel.createChannelsQuery(
  ChannelsQueryParams(
    channelTypes: [ChannelType.direct, ChannelType.group, ChannelType.system],
    startTime: 0,
    pageSize: 20,
    topPriority: true,
  ),
);

await query.loadNextPage((result, error) {
  if (error == null) {
    print('Channel count: ${result?.data.length}');
  } else {
    print('Failed, error code: ${error?.code}');
  }
});

PageData<BaseChannel>​

PropertyTypeDescription
dataList<BaseChannel>Channels returned in the current page.

Get specific channels by identifiers​

Use BaseChannel.getChannels() when you already know the exact channels you want to read from the local database.

Method​

Dart
static Future<int> getChannels(List<ChannelIdentifier> identifiers, OperationHandler<List<BaseChannel>> handler)

ChannelIdentifier properties​

PropertyTypeDescription
channelTypeChannelTypeChannel type.
channelIdStringChannel ID.
subChannelIdString?Subchannel ID for community channels only.

Code example​

Dart
await BaseChannel.getChannels(
  [
    ChannelIdentifier(channelType: ChannelType.direct, channelId: 'user1'),
    ChannelIdentifier(channelType: ChannelType.group, channelId: 'group1'),
  ],
  (channels, error) {
    if (error == null) {
      print('Matched channels: ${channels?.length}');
    }
  },
);

Reload a channel​

Reload the latest details for a specific channel from the local database. This is a BaseChannel instance method.

Method​

Dart
Future<int> reload(OperationHandler<BaseChannel> handler)

Code example​

Dart
BaseChannel channel = ...;

await channel.reload((updated, error) {
  if (error == null) {
    print('Unread count: ${updated?.unreadCount}');
  }
});

Get channels with unread messages​

Retrieve channels that have unread messages. Supports direct, group, and system channels.

Method​

Dart
static Future<int> getUnreadChannels(List<ChannelType> channelTypes, OperationHandler<List<BaseChannel>> handler)

Code example​

Dart
final channelTypes = [ChannelType.direct, ChannelType.group, ChannelType.system];

await BaseChannel.getUnreadChannels(channelTypes, (channels, error) {
  if (error == null) {
    print('Channels with unread messages: ${channels?.length}');
  }
});

Search channels​

Use BaseChannel.searchChannels() to search channels by keyword and message type.

Method​

Dart
static Future<int> searchChannels(SearchChannelsParams params, OperationHandler<List<SearchChannelResult>> handler)

SearchChannelsParams​

ParameterTypeDescription
channelTypesList<ChannelType>Channel types to search.
messageTypesList<MessageType>Message types to include in the search.
keywordStringSearch keyword.

Code example​

Dart
await BaseChannel.searchChannels(
  SearchChannelsParams(
    channelTypes: [ChannelType.direct, ChannelType.group],
    messageTypes: [MessageType.text, MessageType.image],
    keyword: 'release',
  ),
  (results, error) {
    if (error == null) {
      print('Matched channels: ${results?.length}');
      print('First count: ${results?.first.count}');
    }
  },
);

SearchChannelResult​

PropertyTypeDescription
channelBaseChannel?The matched channel.
countint?Number of matching messages in the channel.

FAQ​

Q: After reinstalling the app, the channel list is empty or partially missing?

A: The channel list is stored in the SDK's local database, which is cleared when the app is uninstalled. If missed message compensation is enabled, logging in on a new device triggers compensation to retrieve some historical channels (default: current day). To extend the compensation period (up to 7 days), submit a ticket. Setting a long period may cause processing pressure on clients with high message volumes.

Last updated on