Query and Filter Messages

Use message queries to build timelines, reply threads, media views, and jump-to-message flows. All platforms start from a subChannelId; optional filters narrow the result set. For chat timelines, prefer live collections or reactive streams where the platform provides them. They keep edits, deletes, reactions, and newly created messages in sync without a manual refresh loop.

Filter Surface

Filter	TypeScript	iOS	Android	Flutter
Subchannel	`subChannelId`	`subChannelId`	`getMessages(subChannelId)`	`getMessages(subChannelId)`
Tags	`includingTags`, `excludingTags`	`includingTags`, `excludingTags`	`includingTags()`, `excludingTags()`	`includingTags()`, `excludingTags()`
Type	`type`	`type`	`type()`	`type()`
Deleted messages	`includeDeleted`	Not exposed on query options	`includeDeleted()`	`includeDeleted()`
Replies	`parentId`	`messageParentFilter`	`parentId()`	`parentId()`
Jump context	`aroundMessageId`	`aroundMessageId`	`aroundMessageId()`	`aroundMessageId()`

Parameters

Parameter	Required	Description
`subChannelId`	Yes	Target subchannel whose messages should be queried.
`includingTags` / `excludingTags`	No	Include or exclude messages with specific app-defined tags.
`type`	No	Restrict results to one message type, such as text, image, file, video, audio, or custom.
`includeDeleted`	No	Include soft-deleted messages where the platform exposes the filter.
`parentId` / `messageParentFilter`	No	Query replies for a parent message instead of the main timeline.
`aroundMessageId`	No	Load messages around a target message for deep-link or jump-to-message flows.
`sortBy` / `stackFromEnd`	No	Control timeline ordering where the platform exposes sort options.
Pagination controls	No	Use callbacks, live collections, or paging data to load additional results.

Query A Timeline

Query the main message timeline for a subchannel with optional tag and sort filters.

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

const unsubscribe = MessageRepository.getMessages(
  {
    subChannelId,
    includingTags: ['public'],
    excludingTags: ['hidden'],
    sortBy: 'segmentDesc',
  },
  ({ data: messages, onNextPage, hasNextPage, loading, error }) => {
    if (error) handleError(error);

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

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

unsubscribe();

let options = AmityMessageQueryOptions(
    subChannelId: "sub-channel-id",
    includingTags: ["public"],
    excludingTags: ["hidden"],
    sortOption: .lastCreated
)

let messages = messageRepository.getMessages(options: options)
token = messages.observe { collection, error in
    if let error {
        handleError(error)
        return
    }

    showSuccessMessage(collection.snapshots.count)
}

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

val disposable = messageRepository
    .getMessages(subChannelId = subChannelId)
    .includingTags(includingTags)
    .excludingTags(excludingTags)
    .sortBy(AmityMessageQuerySortOption.LAST_CREATED)
    .build()
    .query()
    .subscribe(
        { pagingData -> getPagingData(pagingData) },
        { error -> handleGeneralError(error) },
    )

final liveCollection = AmityChatClient.newMessageRepository()
    .getMessages(subChannelId)
    .includingTags(['public'])
    .excludingTags(['hidden'])
    .stackFromEnd(true)
    .getLiveCollection();

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

liveCollection.loadNext();

Query By Type Or Deleted State

Use message type and deleted-state filters to build focused views such as media galleries or moderation queues.

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

const unsubscribe = MessageRepository.getMessages(
  {
    subChannelId,
    type: 'image',
    includeDeleted: false,
  },
  ({ data: messages }) => {
    renderResults(messages);
  },
);

unsubscribe();

let options = AmityMessageQueryOptions(
    subChannelId: "sub-channel-id",
    type: .image,
    sortOption: .lastCreated
)

let messages = messageRepository.getMessages(options: options)
showSuccessMessage(messages)

val disposable = messageRepository
    .getMessages(subChannelId = subChannelId)
    .type(AmityMessage.DataType.IMAGE)
    .includeDeleted(includeDeleted = false)
    .build()
    .query()
    .subscribe(
        { pagingData -> getPagingData(pagingData) },
        { error -> handleGeneralError(error) },
    )

final imageMessages = await AmityChatClient.newMessageRepository()
    .getMessages(subChannelId)
    .type(AmityMessageDataType.IMAGE)
    .includeDeleted(false)
    .query();

final count = imageMessages.length;

Query Replies

Use a parent message ID to fetch replies to that message. Use the no-parent/default query for the main timeline. Query replies with parentId when rendering a message thread.

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

const unsubscribe = MessageRepository.getMessages(
  {
    subChannelId,
    parentId: messageId,
    sortBy: 'segmentAsc',
  },
  ({ data: replies }) => {
    renderResults(replies);
  },
);

unsubscribe();

let options = AmityMessageQueryOptions(
    subChannelId: "sub-channel-id",
    messageParentFilter: .parent(id: "parent-message-id"),
    sortOption: .firstCreated
)

let replies = messageRepository.getMessages(options: options)
showSuccessMessage(replies)

val disposable = messageRepository
    .getMessages(subChannelId = subChannelId)
    .parentId(parentId = messageId)
    .sortBy(AmityMessageQuerySortOption.FIRST_CREATED)
    .build()
    .query()
    .subscribe(
        { pagingData -> getPagingData(pagingData) },
        { error -> handleGeneralError(error) },
    )

final replies = await AmityChatClient.newMessageRepository()
    .getMessages(subChannelId)
    .parentId(messageId)
    .query();

final replyCount = replies.length;

Jump To A Message

Use aroundMessageId when your app opens a deep link or search result and needs the target message plus nearby context. Query around a target message to load nearby context for deep links and search results.

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

const unsubscribe = MessageRepository.getMessages(
  {
    subChannelId,
    aroundMessageId: messageId,
  },
  ({ data: messages, hasPrevPage, hasNextPage }) => {
    renderResults({ messages, hasPrevPage, hasNextPage });
  },
);

unsubscribe();

let options = AmityMessageQueryOptions(
    subChannelId: "sub-channel-id",
    aroundMessageId: "message-id",
    sortOption: .lastCreated
)

let messages = messageRepository.getMessages(options: options)
showSuccessMessage(messages)

val disposable = messageRepository
    .getMessages(subChannelId = subChannelId)
    .aroundMessageId(messageId = messageId)
    .build()
    .query()
    .subscribe(
        { pagingData -> getPagingData(pagingData) },
        { error -> handleGeneralError(error) },
    )

final messagesAroundTarget = await AmityChatClient.newMessageRepository()
    .getMessages(subChannelId)
    .aroundMessageId(messageId)
    .query();

final count = messagesAroundTarget.length;

Send Messages

Create messages that appear in the queried subchannel.

Get a Message

Retrieve or observe one message by ID.

Edit and Delete

Update queried messages after creation.

Powered by

Getting Started

Fundamentals

Social

Chat

Video

Release Notes

Migration Guides

Support

Query and Filter Messages

Filter Surface

Parameters

Query A Timeline

Query By Type Or Deleted State

Query Replies

Jump To A Message

Send Messages

Get a Message

Edit and Delete

​Filter Surface

​Parameters

​Query A Timeline

​Query By Type Or Deleted State

​Query Replies

​Jump To A Message

​Related Topics

Send Messages

Get a Message

Edit and Delete

Filter Surface

Parameters

Query A Timeline

Query By Type Or Deleted State

Query Replies

Jump To A Message

Related Topics