Observe detailed location data
Build thread previews with detailed data about all threads in a location
Overview #
This method allows you to observe detailed data about a location, including live updates.
import { thread } from '@cord-sdk/react';
const { threads, loading, hasMore, fetchMore } = thread.useLocationData({
page: 'document_details',
});
return (
<div>
{threads.map((threadSummary) => (
<div key={threadSummary.id}>
Thread ID {threadSummary.id} has {threadSummary.total} messages!
</div>
))}
{loading ? (
<div>Loading...</div>
) : hasMore ? (
<div onClick={() => fetchMore(10)}>Fetch 10 more</div>
) : null}
</div>
);Copy
Available Data #
The API provides an object which has the following fields:
loading #
boolean
When this is
true, Cord is in the process of fetching additional data from its backend. Once the fetch is complete, the additional items will be appended to the result list, and loading will become false.Both the initial data load and a call to
fetchMore will start a fetch and cause loading to become true.fetchMore #
FetchMoreCallback
Call this function to fetch additional data from Cord's backend. It takes a single argument, the number of additional items to fetch.
Once called,
loading will become true while the data is fetched. Once the fetch is complete, the additional items will be appended to the result list, and loading will return to false.This function returns a promise that is resolved once the fetch is complete.
hasMore #
boolean
If this is
true, then the list of results is incomplete, and you need to call fetchMore to continue paginating through them. Once this becomes false, all results are available, and calls to fetchMore won't do anything.threads #
ThreadSummary[]
An array of thread summary objects. There will be one of each thread at the specified location.
This array is paginated. At first, it will contain summaries of only the first few threads. Calling
fetchMore will cause further thread summaries to be appended to the array.The order in which you will receive the threads is determined by the sorting options.
This is an array of objects, each of which has the following fields:
unread #
number
The number of messages that the current user hasn't seen yet. This count excludes deleted messages.
viewerIsThreadParticipant #
boolean
Whether the current viewer has either left a message or reacted to this thread.
firstMessage #
ClientMessageData | null
Contains information about the first (i.e., oldest) message in the thread.
null if the thread is empty.This is an object with the following fields:
seen
boolean
Whether the message has been seen by the current viewer.
id
string
The ID for the message. If a message is created with no ID, a random UUID-based ID will be automatically created for it.
authorID
string
The ID for the user that sent the message.
groupID
string
The ID for the group this message belongs to.
threadID
string
The ID for the thread this message is part of.
content
object[]
The content of the message.
plaintext
string
A plaintext version of the structured message content.
url
string | null
A URL where the message can be seen. This determines where a user is sent when they click on a reference to this message, such as in a notification. If unset, it defaults to the thread's URL.
createdTimestamp
Date
The timestamp when this message was created. The default value is the current time.
deletedTimestamp
Date | null
The timestamp when this message was deleted, if it was. If unset, the message is not deleted.
updatedTimestamp
Date | null
The timestamp when this message was last edited, if it ever was. If unset, the message does not show as edited.
iconURL
string | null
The URL of the icon to show next to the message. This is only used for
action_message messages; other messages show the avatar of the author. If an action_message does not have an icon set, no icon is shown.translationKey
string | null
An optional translation key used for this message. This is useful for system-generated messages where you might want to translate or customize them at runtime. See the translations documentation for more information.
type
"action_message" | "user_message"
The type of message this is. A
user_message is a message that the author sent. An action_message is a message about something that happened, such as the thread being resolved. The default value is user_message.metadata
EntityMetadata
Arbitrary key-value pairs that can be used to store additional information.
extraClassnames
string | null
A optional space separated list of classnames to add to the message.
attachments
array
The items attached to this message.
reactions
Reaction[]
The reactions to this message.
This is an array of objects, each of which has the following fields:
reaction
string
The emoji reaction.
userID
string
The ID of the user who reacted to the message.
timestamp
Date
The timestamp of when the reaction was created.
seenBy
string[]
A list of IDs of the users that have seen the message.
skipLinkPreviews
boolean
If set, Cord won't analyze links in the message to generate previews.
lastMessage #
ClientMessageData | null
Contains information about the last (i.e., newest) message in the thread.
null if the thread is empty.This is an object with the following fields:
seen
boolean
Whether the message has been seen by the current viewer.
id
string
The ID for the message. If a message is created with no ID, a random UUID-based ID will be automatically created for it.
authorID
string
The ID for the user that sent the message.
groupID
string
The ID for the group this message belongs to.
threadID
string
The ID for the thread this message is part of.
content
object[]
The content of the message.
plaintext
string
A plaintext version of the structured message content.
url
string | null
A URL where the message can be seen. This determines where a user is sent when they click on a reference to this message, such as in a notification. If unset, it defaults to the thread's URL.
createdTimestamp
Date
The timestamp when this message was created. The default value is the current time.
deletedTimestamp
Date | null
The timestamp when this message was deleted, if it was. If unset, the message is not deleted.
updatedTimestamp
Date | null
The timestamp when this message was last edited, if it ever was. If unset, the message does not show as edited.
iconURL
string | null
The URL of the icon to show next to the message. This is only used for
action_message messages; other messages show the avatar of the author. If an action_message does not have an icon set, no icon is shown.translationKey
string | null
An optional translation key used for this message. This is useful for system-generated messages where you might want to translate or customize them at runtime. See the translations documentation for more information.
type
"action_message" | "user_message"
The type of message this is. A
user_message is a message that the author sent. An action_message is a message about something that happened, such as the thread being resolved. The default value is user_message.metadata
EntityMetadata
Arbitrary key-value pairs that can be used to store additional information.
extraClassnames
string | null
A optional space separated list of classnames to add to the message.
attachments
array
The items attached to this message.
reactions
Reaction[]
The reactions to this message.
This is an array of objects, each of which has the following fields:
reaction
string
The emoji reaction.
userID
string
The ID of the user who reacted to the message.
timestamp
Date
The timestamp of when the reaction was created.
seenBy
string[]
A list of IDs of the users that have seen the message.
skipLinkPreviews
boolean
If set, Cord won't analyze links in the message to generate previews.
id #
string
The ID for this thread.
groupID #
string
The group ID this thread is in.
total #
number
The total number of messages in this thread. Equal to user messages + action messages. Deleted messages are excluded from this count.
userMessages #
number
The number of messages in this thread that were sent by users (i.e., not action messages).
actionMessages #
number
The number of action messages sent in this thread. An example is the message that appears when a thread is resolved.
deletedMessages #
number
The number of deleted messages in this thread.
resolved #
boolean
Whether this thread is resolved. This is equivalent to checking if
resolvedTimestamp is null.resolvedTimestamp #
Date | null
The timestamp when this thread was resolved. Set to
null if this thread is not resolved.participants #
ThreadParticipant[]
All of the users who are engaging in this thread. This includes both subscribed and unsubscribed users.
This is an array of objects, each of which has the following fields:
lastSeenTimestamp
Date | null
The timestamp of the most recent message or reaction that this user has seen in this thread. Is
null if this participant has never viewed this thread.userID
string | null
The user ID of the participant. Can be null if the current viewer no longer shares a group with this participant (and therefore can no longer access that participant's information).
subscribers #
string[]
All of the users who are subscribed to this thread.
repliers #
string[]
All of the users who have replied to this thread.
typing #
string[]
The users that are currently typing in this thread. Typing status is transient in nature, so the value is the set of users typing at a particular instant, but may change rapidly.
name #
string
The name of the thread. This is shown to users when the thread is referenced, such as in notifications. This should generally be something like the page title.
url #
string
A URL where the thread can be seen. This determines where a user is sent when they click on a reference to this thread, such as in a notification, or if they click on a reference to a message in the thread and the message doesn't have its own URL.
location #
Location
The location of this thread.
metadata #
EntityMetadata
Arbitrary key-value pairs that can be used to store additional information.
extraClassnames #
string | null
An optional space separated list of classnames to add to the thread.
What this function returns #
The hook will return an object containing the fields described under "Available Data" above. The component will automatically re-render if any of the data changes, i.e., this data is always "live".
Arguments this function takes #
The location to fetch data for.
Miscellaneous options.
This is an object with the following fields:
This option controls the criteria for how threads are sorted. Combined with
sortDirection, it determines which threads are "first".It's a string enum which can have one of the following values:
first_message_timestamp: sort threads by the timestamp of the first message in the thread. In other words, threads will be sorted based on how recently they were created.most_recent_message_timestamp: sort threads by the timestamp of the most recent message in the thread. In other words, threads will be sorted based on how recently they were responded to.
If unset, defaults to
first_message_timestamp.This option controls the direction that
sortBy sorts. Combined with sortBy, it determines which threads are "first".It's a string enum which can have one of the following values:
ascending: sort older threads in front of newer threads.descending: sort newer threads in front of older threads.
If unset, defaults to
descending (since people usually care about the most recent things).If
true, perform partial matching on the specified location. If false, fetch information for only exactly the location specified.If unset, defaults to
false.An object that can be used to filter the threads returned.
This is an object with the following fields:
metadata
optional
EntityMetadata
The value for a
metadata entry should be an object representing the metadata key/value to filter on. For example, to show only threads with the metadata key of "category" set to "sales", set the filter to { metadata: { category: "sales" } }.location
optional
Location
The Location of the threads.
resolvedStatus
optional
"resolved" | "any" | "unresolved"
If set to
resolved, only resolved threads will be returned. If set to unresolved, only unresolved threads will be returned. If set to any, both resolved and unresolved threads will be returned.If unset, defaults to
unresolved.