Skip to main content

​
Overview

The Search request allows you to search for messages within a chat using text queries. You can search within a specific channel or across an entire community, with support for pagination.

​
Proto Definition

// messages.search -> messages.Messages
message Search {
  refs.ChatRef chat_ref = 1;
  string query = 2;
  bool scoped = 3;
  oneof offset {
    fixed64 since = 4;   // @snowflake<Message>
    fixed64 before = 5;  // @snowflake<Message>
  }
}

​
Request Fields

​
chat_ref
ChatRef
required
The chat context for the search. The behavior depends on the scoped parameter:
  • If scoped is true: Search only in this specific chat
  • If scoped is false and chat_ref is a channel: Search across the entire parent community
  • If scoped is false and chat_ref is not a channel: Search only in this chat (equivalent to scoped)
​
query
string
required
The search query text. Messages matching this query will be returned.The exact matching behavior (case-sensitivity, partial matches, etc.) depends on the server implementation.
​
scoped
bool
default:"false"
Controls the search scope:
  • true: Search only the specific channel/chat specified in chat_ref
  • false: For channels, search across the entire parent community (all channels)
Note: For global search across all your chats, use messages.searchAll (not documented here).
​
since
fixed64
Return search results after this message ID (exclusive). Useful for pagination when loading more results.Type: Snowflake ID representing a MessageNote: Only one of since or before can be specified.
​
before
fixed64
Return search results before this message ID (exclusive). Useful for pagination when loading previous results.Type: Snowflake ID representing a MessageNote: Only one of since or before can be specified.

​
Response

The response uses the same Messages structure as GetHistory: 
message Messages {
  repeated types.Message messages = 1;
  repeated types.User users = 2;
  repeated types.CommunityMember members = 3;
  repeated reactions.MessageReactions reactions = 4;
}
​
messages
Message[]
required
Array of messages matching the search query, sorted by relevance or chronological order.
​
users
User[]
required
Array of user objects for all users referenced in the search results (authors, mentioned users, etc.).
​
members
CommunityMember[]
required
Array of community member data for community channels (includes roles, nicknames, etc.).
​
reactions
MessageReactions[]
required
Array of reactions for the returned messages.

​
Examples

​
Search Within a Specific Channel

{
  "chat_ref": {
    "channel": {
      "community_id": "987654321098765432",
      "channel_id": "111111111111111111"
    }
  },
  "query": "important announcement",
  "scoped": true
}
Searches only within channel 111111111111111111 for messages containing “important announcement”.

​
Search Across Entire Community

{
  "chat_ref": {
    "channel": {
      "community_id": "987654321098765432",
      "channel_id": "111111111111111111"
    }
  },
  "query": "meeting notes",
  "scoped": false
}
Searches across all channels in community 987654321098765432 for messages containing “meeting notes”.

​
Search in a Direct Message

{
  "chat_ref": {
    "user": {
      "user_id": "123456789012345678"
    }
  },
  "query": "invoice",
  "scoped": true
}
Searches for “invoice” in the direct message conversation with user 123456789012345678.

​
Search in a Group Chat

{
  "chat_ref": {
    "group": {
      "group_id": "222222222222222222"
    }
  },
  "query": "vacation plans",
  "scoped": true
}
Searches for “vacation plans” in group chat 222222222222222222.

​
Paginated Search (Load More Results)

{
  "chat_ref": {
    "channel": {
      "community_id": "987654321098765432",
      "channel_id": "111111111111111111"
    }
  },
  "query": "project update",
  "scoped": false,
  "before": "555555555555555555"
}
Searches for “project update” across the community, returning results before message ID 555555555555555555.

​
Search Behavior

Scoped Search

  • Searches only the specific chat in chat_ref
  • Faster and more focused results
  • Best for finding messages in a known location

Unscoped Search

  • For channels: Searches all channels in the parent community
  • For other chat types: Behaves the same as scoped
  • Broader results, may be slower
  • Best for finding messages when you’re unsure of the exact channel

​
Pagination

Search results support pagination using the since and before parameters:
  1. Initial search: Omit both since and before to get the first page of results
  2. Load more recent results: Use since with the newest message ID from current results
  3. Load older results: Use before with the oldest message ID from current results
Message IDs are snowflakes, which are chronologically sortable, making pagination efficient.

​
Use Cases

​
Finding Specific Content

{
  "chat_ref": { /* ... */ },
  "query": "feature request",
  "scoped": true
}
Find all mentions of “feature request” in a specific channel. 
{
  "chat_ref": {
    "channel": {
      "community_id": "987654321098765432",
      "channel_id": "111111111111111111"
    }
  },
  "query": "@username",
  "scoped": false
}
Find all messages mentioning a user across all channels in a community.

​
Historical Message Lookup

{
  "chat_ref": { /* ... */ },
  "query": "bug report",
  "scoped": true,
  "before": "<oldest_message_in_results>"
}
Find older bug reports by paginating through search results.

​
Notes

  • Search queries are text-based; the server determines matching logic
  • The scoped parameter only affects channels; for other chat types, search is always within that chat
  • For global search across all your conversations, use messages.searchAll instead
  • Search results include all necessary user and member data for rendering
  • Pagination works the same way as in GetHistory, using snowflake IDs for efficient ordering
  • Search performance may vary based on chat size and query complexity

Build docs developers (and LLMs) love

Get started for freeTalk to us