Cord LogoDocs
Sign inStart now

Observe thread data

Thread API /

Build rich integrations with detailed data about the thread and all of its messages

Overview #

This method allows you to observe all messages and data for a thread, including live updates.
React:
import { thread } from '@cord-sdk/react';
const { messages, thread, loading, hasMore, fetchMore } = thread.useThread('my-awesome-thread-id');

return (
  <div>
    {thread ?
      <p> {thread.unread} / {thread.total} unread messages </p>
      : null}
    {messages.map((messageSummary) => (
      <div key={messageSummary.id}>
        Message ID {messageSummary.id} was created at {messageSummary.createdTimestamp}!
      </div>
    ))}
    {loading ? (
      <div>Loading...</div>
    ) : hasMore ? (
      <div onClick={() => fetchMore(10)}>Fetch 10 more</div>
    ) : null}
  </div>
);
Vanilla JavaScript:
const ref = window.CordSDK.thread.observeThread(
  'my-awesome-thread-id',
  ({ messages, loading, hasMore, fetchMore, thread }) => {
    console.log('Got a thread data update:');
    if (loading) {
      console.log('Loading...');
    }
    if (thread) {
      console.log(`${thread.unread}/${thread.total} unread`)
    }
    messages.forEach((messageSummary) =>
      console.log(`Message ${messageSummary.id} was created at ${messageSummary.createdTimestamp}!`),
    );
    if (!loading && hasMore && messages.length < 25) {
      // Get the first 25 threads, 10 at a time.
      fetchMore(10);
    }
  },
);
// ... Later, when updates are no longer needed ...
window.CordSDK.thread.unobserveThread(ref);
import { thread } from '@cord-sdk/react';
const { messages, thread, loading, hasMore, fetchMore } = thread.useThread('my-awesome-thread-id');

return (
  <div>
    {thread ?
      <p> {thread.unread} / {thread.total} unread messages </p>
      : null}
    {messages.map((messageSummary) => (
      <div key={messageSummary.id}>
        Message ID {messageSummary.id} was created at {messageSummary.createdTimestamp}!
      </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:

messages #

ClientMessageData[]
An array of objects, one for each message in the specified thread.
This array is paginated. At first, it will contain only the latest (newest) messages. Calling fetchMore will cause further messages to be appended to the array.

This is an array of objects, each of which has 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.

thread #

Information about the thread. This will be undefined if the thread is still loading and null if the thread does not exist.

This property can be one of the following:

  • undefined
  • null
  • ThreadSummary

    This is an object with 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.

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.

What this function returns #

Returns an object containing the fields described under "Available Data" above. Initially, loading will be true, thread will be undefined, and messages an empty array while the data loads from our API. Once it has loaded, your component will re-render and the hook will return an object containing the full data. The component will automatically re-render if any of the data changes, i.e., this data is always "live".

Arguments this function takes #

threadID #

required
string
The thread ID to fetch data for.

options #

optional
ThreadObserverOptions
Options for creating new threads.

This is an object with the following fields:

threadName #

optional
string
Loading information for a thread ID which does not exist will create that thread. If that happens, this will be the name of the new thread.
If unset, this will default to the current page's title.

location #

optional
Location
Loading information for a thread ID which does not exist will create that thread. If that happens, this will be the location of the new thread.
If unset, this will default to the location provided to the useCordLocation hook if that was used. Otherwise, will default to the current page's URL.

Ask Cordy