Message Search

Search messages across channels using full-text search or specific field filters. Enable or disable search indexing per channel type in the Stream Dashboard.

Searching Messages

Search requires a channel filter and either a text query or message filter conditions.

let controller = client.messageSearchController()

// Search for messages containing text
let textQuery = MessageSearchQuery(
  channelFilter: .containMembers(userIds: ["john"]),
  messageFilter: .queryText("supercalifragilisticexpialidocious"),
  pageSize: 10
)

// Search with message filters
let filteredQuery = MessageSearchQuery(
  channelFilter: .containMembers(userIds: ["john"]),
  messageFilter: .and([.autocomplete(.text, text: "super"), .withAttachments]),
  pageSize: 10
)

// Each search replaces the controller's previous results
controller.search(query: textQuery) { error in
  if let error = error {
    // Handle error
    print(error)
    return
  }
  let results = controller.messages

  controller.search(query: filteredQuery) { error in
    guard error == nil else { return }
    let filtered = controller.messages
  }
}

Query Parameters

Name Type Description Default Optional
filter_conditions object Channel filters. Maximum 500 channels are searched. See Querying Channels. -
message_filter_conditions object Message filters. See Message Filter Conditions below. Either this or query is required. - ✓
query string Full-text search string. Equivalent to {text: {$q: <query>}}. Either this or message_filter_conditions is required. - ✓
limit integer Number of messages to return. 100 ✓
offset integer Pagination offset. Cannot be used with sort or next. 0 ✓
sort array Sort order, as a list of { field, direction } objects. direction is 1 (ascending) or -1 (descending). [{ field: "relevance", direction: -1 }, { field: "id", direction: 1 }] ✓
next string Pagination cursor. See Pagination below. - ✓

Message Filter Conditions

For the full list of supported query operators, see Query Syntax Operators.

Field Description Operators
id Message ID $eq, $gt, $gte, $lt, $lte, $in
text Message text $q, $autocomplete, $eq, $gt, $gte, $lt, $lte, $in
type Message type. System and deleted messages are excluded $eq, $gt, $gte, $lt, $lte, $in
parent_id Parent message ID (for replies) $eq, $gt, $gte, $lt, $lte, $in
reply_count Number of replies $eq, $gt, $gte, $lt, $lte, $in
attachments Whether message has attachments $exists, $eq, $gt, $gte, $lt, $lte, $in
attachments.type Attachment type $eq, $in
mentioned_users.id Mentioned user ID $contains
user.id Sender user ID $eq, $gt, $gte, $lt, $lte, $in
created_at Creation timestamp $eq, $gt, $gte, $lt, $lte, $in
updated_at Update timestamp $eq, $gt, $gte, $lt, $lte, $in
pinned Whether message is pinned $eq
custom field Any custom field on the message $eq, $gt, $gte, $lt, $lte, $in

Sorting

Results are sorted by relevance by default, with message ID as a tiebreaker. If your query does not use $q or $autocomplete, all results are equally relevant.

Sort by any filterable field, including custom fields. Numeric custom fields are sorted numerically; string fields are sorted lexicographically.

Pagination

Two pagination methods are available:

Offset pagination allows access to up to 1,000 results. Results are sorted by relevance and message ID. You cannot use custom sorting with offset pagination.

Cursor pagination (using next/previous) allows access to all matching results with custom sorting. The response includes next and previous cursors to navigate between pages.

let controller = client.messageSearchController()
let query = MessageSearchQuery(
  channelFilter: .equal(.cid, to: ChannelId(type: .messaging, id: "my-channel")),
  messageFilter: .autocomplete(.text, text: "supercali"),
  sort: [.init(key: .updatedAt, isAscending: true)],
  pageSize: 10
)

// First page with custom sorting
controller.search(query: query) { error in
  guard error == nil else { return }

  // Next page: when the query has a sort, the controller uses the `next` cursor
  // of the previous response and appends the results to `controller.messages`
  controller.loadNextMessages(limit: 10) { error in
    print(controller.messages)
  }
}