Search messages

Search messages the current user has access to


Overview #

This method allows you search for messages by content.
React:
import { thread } from '@cord-sdk/react';
const results = thread.useSearchMessages({textToMatch: 'hello'});

return (
  <div>
    {results.map((result) => (
      <div key={result.id}>
        Found match in message {result.id}: {result.plaintext}
      </div>
    ))}
  </div>
);
Vanilla JavaScript:
await window.CordSDK.thread.searchMessages({textToMatch: 'hello'});
import { thread } from '@cord-sdk/react';
const results = thread.useSearchMessages({textToMatch: 'hello'});

return (
  <div>
    {results.map((result) => (
      <div key={result.id}>
        Found match in message {result.id}: {result.plaintext}
      </div>
    ))}
  </div>
);
Copy

What this function returns #

The hook will initially return undefined while the data loads from our API. Once it has loaded, your component will re-render and the hook will return an array containing message objects including thread location.
Please note that the results are limited to 50 messages by default, but you can use the limit option to override that. To get more specific results, consider using one or more of the other search options provided.

Arguments this function takes #


searchOptions #

required
SearchOptionsType
Various options for how to search the messages. Each option is optional, but if you supply no options the result will be an empty array.

This is an object with the following fields:


textToMatch #

optional
string
The string you want to find in message content.

authorID #

optional
string
The user ID of the person who sent the message.

groupID #

optional
string
The ID of the group the message belongs to. If omitted, the search will be across all groups the current user is a member of.

metadata #

optional
EntityMetadata
Arbitrary key-value pairs of data associated with the message.

locationOptions #

optional
object
Location to filter the messages by.
Set locationOptions.location to a specific thread location to search. If locationOptions.partialMatch is true, we perform partial matching on the specified location. If false, we fetch information only from the specified location.

This is an object with the following fields:


location
required
Location

partialMatch
required
boolean

timestampRange #

optional
TimestampRange
Optional date objects used to scope search.

This is an object with the following fields:


from
optional
Date
Timestamp from where to start the interval. The thread's timestamp must be newer than (or equal to) this in order to match the filter.
If not present, the interval will have no start date and any data will include everything older than the provided to timestamp.

to
optional
Date
Timestamp where to end the interval. The thread's timestamp must be older than (or equal to) this in order to match the filter.
If not present, the interval will have no end date and any data will include everything newer than the provided from timestamp.

limit #

optional
number
Number of messages to return. This will default to 50 if no value is provided but will be capped at 1000 if a value is provided.

sortBy #

optional
"created_timestamp" | "relevance"
Sort the messages returned based on either their creation timestamp or relevance. Relevance refers to how closely the provided textToMatch string matches the content of the messages. Combine this with sortDirection to fine-tune the sorting order.
By default, sorting is performed by relevance if textToMatch is provided, but will fallback to created_timestamp if it's not.

sortDirection #

optional
"ascending" | "descending"
Property to control the order in which the messages returned are sorted. Using sortBy value of relevance and sortDirection of descending are the best options for getting the most relevant results at the top and is the default sorting criteria.
The default value for this is 'descending'.

Ask Cordy