Query Channels

Use channel queries to build inboxes, public channel discovery, event chat lists, and moderation views. Query support is similar across platforms, but not identical: TypeScript and Flutter expose keyword/display-name style searching, while Android’s public channel query builder focuses on type, membership, tags, and deleted-state filters.

Filter Surface

Filter	TypeScript	iOS	Android	Flutter
Types	`types`	`types`	`.types(...)` or type helpers	`.types(...)` or type helpers
Membership	`membership`	`filter`	`.filter(...)` where the builder exposes it	`.filter(...)`
Tags	`tags`, `excludeTags`	`includingTags`, `excludingTags`	`.includingTags(...)`, `.excludingTags(...)`	`.includingTags(...)`, `.excludingTags(...)`
Deleted state	`isDeleted`	`includeDeleted`	`.includeDeleted(...)`	`.includeDeleted(...)`
Name or keyword	`displayName`	Not exposed on `AmityChannelQueryOptions`	Not exposed on public query builder	`.withKeyword(...)`
Archive exclusion	`excludeArchives`	`excludeArchives` on `AmityChannelQueryOptions`	`.excludeArchived(...)`	`.excludeArchives(...)`
Sort	`sortBy`	`sortBy` with `.lastActivity` or `.lastMessage`	`.sortBy(...)` with `LAST_ACTIVITY` or `LAST_MESSAGE`	`.sortBy(...)` with `LAST_ACTIVITY`
Known IDs	`channelIds`	`getChannels(channelIds:)`	`getChannels(channelIds)`	Not exposed in the current public repository

Parameters

Parameter	Required	Platforms	Description
`types`	No	TypeScript, iOS, Android, Flutter	Channel types to include, such as community, live, or conversation.
`membership` / `filter`	No	TypeScript, iOS, Android, Flutter	Restrict results by the current user’s relationship to the channel.
`tags` / `includingTags`	No	TypeScript, iOS, Android, Flutter	Include channels with specific app-defined tags.
`excludeTags` / `excludingTags`	No	TypeScript, iOS, Android, Flutter	Exclude channels with specific app-defined tags.
`isDeleted` / `includeDeleted`	No	TypeScript, iOS, Android, Flutter	Include or exclude deleted channels where the platform exposes the filter.
`displayName` / `keyword`	No	TypeScript, Flutter	Search by name or keyword where supported by the platform SDK.
`excludeArchives`	No	TypeScript, iOS, Android, Flutter	Exclude channels archived by the current user where supported.
`sortBy`	No	TypeScript, iOS, Android, Flutter	Sort channel lists where the platform exposes sort options. Choose `lastActivity` (default) or `lastMessage`; see Sort A Channel List.
Pagination controls	No	TypeScript, iOS, Android, Flutter	Use collection callbacks, live collections, or paging data to load additional channels.

Query A Channel List

Query channels with type, membership, tag, deletion, archive, search, and pagination options where each platform exposes them.

val includingTags = AmityTags().apply { add("support") }
val excludingTags = AmityTags().apply { add("hidden") }

val disposable = channelRepository
    .getChannels()
    .types(listOf(AmityChannel.Type.COMMUNITY, AmityChannel.Type.LIVE))
    .filter(AmityChannelFilter.MEMBER)
    .sortBy(AmityChannelSortBy.LAST_MESSAGE)
    .includingTags(includingTags)
    .excludingTags(excludingTags)
    .includeDeleted(includeDeleted = false)
    .build()
    .query()
    .subscribe(
        { pagingData -> showSuccessMessage(pagingData) },
        { error -> handleGeneralError(error) },
    )

let options = AmityChannelQueryOptions(
    types: Set([AmityChannelQueryType.community, AmityChannelQueryType.live]),
    filter: .userIsMember,
    includingTags: ["support"],
    excludingTags: ["hidden"],
    includeDeleted: false,
    sortBy: .lastMessage
)

let channels = channelRepository.getChannels(with: options)
token = channels.observe { collection, error in
    if let error {
        handleError(error)
        return
    }

    showSuccessMessage(collection.snapshots.count)
}

import { ChannelRepository } from '@amityco/ts-sdk';

const unsubscribe = ChannelRepository.getChannels(
  {
    displayName: 'support',
    membership: 'member',
    types: ['community', 'live'],
    tags: ['support'],
    excludeTags: ['hidden'],
    isDeleted: false,
    excludeArchives: true,
    sortBy: 'lastMessage',
  },
  ({ data: channels, onNextPage, hasNextPage, loading, error }) => {
    if (error) handleError(error);

    if (!loading && channels) {
      renderResults(channels);
    }

    if (hasNextPage) onNextPage?.();
  },
);

unsubscribe();

final liveCollection = AmityChatClient.newChannelRepository()
    .getChannels()
    .withKeyword('support')
    .filter(AmityChannelFilter.MEMBER)
    .types([AmityChannelType.COMMUNITY, AmityChannelType.LIVE])
    .includingTags(['support'])
    .excludingTags(['hidden'])
    .includeDeleted(false)
    .excludeArchives(true)
    .sortBy(AmityChannelSortOption.LAST_ACTIVITY)
    .getLiveCollection();

liveCollection.getStreamController().stream.listen((channels) {
  final count = channels.length;
});

await liveCollection.loadNext();

Sort A Channel List

Use sortBy to choose how a channel list is ordered. Choose lastMessage for an inbox that should follow the conversation, so that joining or leaving a channel does not push it to the top.

Value	Order	What moves a channel to the top
`lastActivity` (default)	Newest activity first	A new message, or a member being added, removed, or banned
`lastMessage`	Newest message first	A new message. Membership changes do not reorder the list.

Each platform names the values in its own style:

Platform	Option	`lastActivity`	`lastMessage`
TypeScript	`sortBy`	`'lastActivity'`	`'lastMessage'`
iOS	`AmityChannelQueryOptions.sortBy` (`AmityChannelSortBy`)	`.lastActivity`	`.lastMessage`
Android	`.sortBy(...)` (`AmityChannelSortBy`)	`LAST_ACTIVITY`	`LAST_MESSAGE`

// Newest message first
val disposable = channelRepository
    .getChannels()
    .all()
    .filter(AmityChannelFilter.MEMBER)
    .sortBy(AmityChannelSortBy.LAST_MESSAGE)
    .build()
    .query()
    .subscribe(
        { pagingData -> submitData(pagingData) },
        { error -> handleGeneralError(error) },
    )

// Newest message first
let options = AmityChannelQueryOptions(
    filter: .userIsMember,
    sortBy: .lastMessage
)

let channels = channelRepository.getChannels(with: options)
token = channels.observe { collection, error in
    if let error {
        handleError(error)
        return
    }

    for channel in collection.snapshots {
        showRow(name: channel.displayName, lastMessageAt: channel.lastMessageAt)
    }
}

import { ChannelRepository } from '@amityco/ts-sdk';

// Newest message first
const unsubscribe = ChannelRepository.getChannels(
  { membership: 'member', sortBy: 'lastMessage' },
  ({ data: channels, error }) => {
    if (error) handleError(error);

    if (channels) {
      renderResults(channels);
    }
  },
);

unsubscribe();

Live order. The collection reorders as messages arrive. When the current user sends a message, that channel moves to the top right away, before the server responds.
lastMessageAt. The channel’s lastMessageAt is the time of its newest message, or its creation time if it has none. Unlike lastActivity, membership changes and closing the channel do not change it. It is null (nil on iOS) when the backend has no value for the channel yet, and those channels are listed last, ordered by creation time. Read it as channel.getLastMessageAt() on Android, channel.lastMessageAt on iOS, and channel.lastMessageAt on TypeScript.
Backend support. lastMessage needs backend support for your network. Until it is available, the query fails with HTTP status 422 and error code 500000. The SDK does not retry and does not fall back to lastActivity, so handle the error in your query callback. On iOS, error.isAmityErrorCode(.business) identifies it, and on TypeScript the code is Amity.ServerError.BUSINESS_ERROR. On Android, the error arrives as LoadState.Error in the paging load state, not in the subscribe error callback. AmityError.from(error) == AmityError.BUSINESS_ERROR identifies it.

Flutter’s sortBy currently accepts LAST_ACTIVITY only. On TypeScript, sortBy also accepts lastCreated, firstCreated, and displayName.

Query A Specific Type

Use the type-specific helpers when the platform exposes them. Some helpers apply membership defaults: for example, Flutter’s conversationType() and liveType() also set the filter to MEMBER. Use type-specific channel queries when your UI needs a focused list such as conversations or live channels.

val disposable = channelRepository
    .getChannels()
    .conversationType()
    .includeDeleted(includeDeleted = false)
    .build()
    .query()
    .subscribe(
        { pagingData -> showSuccessMessage(pagingData) },
        { error -> handleGeneralError(error) },
    )

let options = AmityChannelQueryOptions(
    types: Set([AmityChannelQueryType.conversation]),
    filter: .userIsMember,
    includeDeleted: false
)

let conversations = channelRepository.getChannels(with: options)
showSuccessMessage(conversations)

import { ChannelRepository } from '@amityco/ts-sdk';

const unsubscribe = ChannelRepository.getChannels(
  {
    types: ['conversation'],
    membership: 'member',
    isDeleted: false,
  },
  ({ data: channels }) => {
    renderResults(channels);
  },
);

unsubscribe();

final conversations = AmityChatClient.newChannelRepository()
    .getChannels()
    .conversationType()
    .includeDeleted(false)
    .excludeArchives(true)
    .getLiveCollection();

conversations.getStreamController().stream.listen((channels) {
  final count = channels.length;
});

Known IDs

If you already have channel IDs, use Get Channels instead of a filtered query. Batch get-by-IDs is currently exposed on TypeScript, iOS, and Android.

Create Channels

Create a channel before it appears in query results.

Get Channels

Retrieve a single channel or a known list of IDs.

Archive Channels

Hide or restore archived conversation channels where supported.

Query Members

Query members after selecting a channel.

Powered by

Getting Started

Fundamentals

Social

Chat

Video

Release Notes

Migration Guides

Support

Filter Surface

Parameters

Query A Channel List

Sort A Channel List

Query A Specific Type

Known IDs

Create Channels

Get Channels

Archive Channels

Query Members

​Filter Surface

​Parameters

​Query A Channel List

​Sort A Channel List

​Query A Specific Type

​Known IDs

​Related Topics

Create Channels

Get Channels

Archive Channels

Query Members

Filter Surface

Parameters

Query A Channel List

Sort A Channel List

Query A Specific Type

Known IDs

Related Topics