Cord LogoDocs
Sign inStart now

Observe thread counts

Thread API /

Build thread previews with detailed counts about all threads visible to the current user

Overview #

This API allows you to observe the count of all the threads in an application that are visible to the current user.
React:
import { thread } from '@cord-sdk/react';
const threadCounts = thread.useThreadCounts(
    { filter: {
       location: {
             'value' {'page': 'document_details'},
             'partialMatch': false
            },
       metadata: {'category': 'sales'}
   }}
);
return (
  <div>
    {!threadCounts && "Loading..."}
    {threadCounts && (
      <p>Total threads: {threadCounts.total}</p>
      <p>Unread threads: {threadCounts.unread}</p>
      <p>Unread subscribed threads: {threadCounts.unreadSubscribed}</p>
      <p>Resolved threads: {threadCounts.resolved}</p>
    )}
  </div>
);
Vanilla JavaScript:
const ref = window.CordSDK.thread.observeThreadCounts(
  (threadCounts) => {
     // Received an update!
     console.log("Total threads", threadCounts.total);
     console.log("Unread threads", threadCounts.unread);
     console.log("Unread subscribed threads", threadCounts.unreadSubscribed);
     console.log("Resolved threads", threadCounts.resolved);
  },
   { filter: {
       location: {
             'value': { 'page': 'document_details'},
             'partialMatch': true
            },
       metadata: {'category': 'sales'}
   }}
);
// ... Later, when updates are no longer needed ...
window.CordSDK.thread.unobserveThreadCounts(ref);
import { thread } from '@cord-sdk/react';
const threadCounts = thread.useThreadCounts(
    { filter: {
       location: {
             'value' {'page': 'document_details'},
             'partialMatch': false
            },
       metadata: {'category': 'sales'}
   }}
);
return (
  <div>
    {!threadCounts && "Loading..."}
    {threadCounts && (
      <p>Total threads: {threadCounts.total}</p>
      <p>Unread threads: {threadCounts.unread}</p>
      <p>Unread subscribed threads: {threadCounts.unreadSubscribed}</p>
      <p>Resolved threads: {threadCounts.resolved}</p>
    )}
  </div>
);
Copy

Available Data #

Graphic showing example uses of the Cord Thread Counts API

The API provides an object which has the following fields:

total #

number
The total number of threads, both resolved and unresolved. This does not include threads in which all messages have been deleted.

unread #

number
The total number of threads that contain at least one unread message in the thread.
This will count all threads with unread messages, whether the current user is subscribed to the thread or not.

unreadSubscribed #

number
The number of threads that have messages the current user hasn't seen yet and is subscribed to.
A user is automatically subscribed to threads relevant to them, for example because they have sent a message or have been @-mentioned in them. unreadSubscribed is always less than or equal to unread.

new #

number
The total number of threads that the user has never seen before at all, i.e., every message in the thread is unread.
This will count all threads with unread messages, whether the current user is subscribed to the thread or not.

resolved #

number
The number of resolved threads. This refers to threads that users have manually marked as resolved within Cord's UI components.

empty #

number
The number of thread with no visible messages. This refers to threads in which all the messages have been deleted.

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 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 #

options #

optional
ObserveThreadCountsOptions
Options that control which threads are counted.

This is an object with the following fields:

filter #

optional
ClientThreadFilter
An object that can be used to filter the threads returned.

This is an object with the following fields:

location
optional
The Location of the threads. This can either be just the location value or an object with a value for both the location and partialMatch properties.
The value for partialMatch will default to false if only location is provided.

This property can be one of the following:

  • Location
  • LocationFilterOptions

    This is an object with the following fields:

    value
    Location
    The Location of the threads.
    partialMatch
    boolean
    If true, perform partial matching on the specified location. If false, fetch information for only exactly the location specified.
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 any.
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" } }.

Ask Cordy