Threads
Rest API /
All available operations for listing and editing threads
Trying to create a thread?
To create a new thread, please use our Message API. You can create a new Thread by posting the first message in the Thread. The Message API accepts createThread attributes which will be used to initialize a new Thread on-the-fly. We do this to avoid empty threads which cannot be resolved by the user.
List all threads #
This endpoint returns information about all threads in an application.
HTTP Request #
GET https://api.cord.com/v1/threads/Copy
Request Body #
This REST endpoint has no request body.
Request Parameters #
The endpoint supports an optional query request parameter. The filter parameter allows you to specify any/all of the multiple optional filters which the threads must match. This is a partial match where as long as the value you filter by is on the thread it will be returned.
filter
optional
Omit<FilterParameters, "organizationID">
Threads will be matched against the filters specified. This is a partial match, which means any keys other than the ones you specify are ignored when checking for a match. Please note that because this is a query parameter in a REST API, this JSON object must be URI encoded before being sent.
This is an object with the following fields:
metadata
optional
EntityMetadata
Arbitrary key-value pairs of data associated with the object.
location
optional
Location
The location for the thread.
firstMessageTimestamp
optional
TimestampRange
Timestamp when the first message in a thread was created.
This is an object with the following fields:
from
optional
Date
Timestamp from where to start the interval. If not present, the interval will have no start date and any data will include everything up to the provided
to timestamp.to
optional
Date
Timestamp where to end the interval. If not present, the interval will have no end date and any data will include everything from the provided
from timestamp.mostRecentMessageTimestamp
optional
TimestampRange
Timestamp when a message in a thread was last created or updated.
This is an object with the following fields:
from
optional
Date
Timestamp from where to start the interval. If not present, the interval will have no start date and any data will include everything up to the provided
to timestamp.to
optional
Date
Timestamp where to end the interval. If not present, the interval will have no end date and any data will include everything from the provided
from timestamp.Response #
The response is a JSON Array with objects with the following fields:
id
string
The ID for this thread.
organizationID
string
The organization 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 an organization 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.
Get a thread #
This endpoint gets information about a specific thread.
HTTP Request #
GET https://api.cord.com/v1/threads/<ID>Copy
Request Body #
This REST endpoint has no request body.
Response #
The response is a JSON object with the following fields:
id
string
The ID for this thread.
organizationID
string
The organization 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 an organization 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.
Update a thread #
This endpoint updates an existing thread.
HTTP Request #
PUT https://api.cord.com/v1/threads/<ID>Copy
Request Body #
Listed below are the fields of the request body to be added as part of the HTTP PUT request.
name
optional
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.
id
optional
string
The ID for this thread.
metadata
optional
EntityMetadata
Arbitrary key-value pairs that can be used to store additional information.
url
optional
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.
organizationID
optional
string
The organization ID this thread is in.
extraClassnames
optional
string | null
An optional space separated list of classnames to add to the thread.
location
optional
Location
The location of this thread.
resolvedTimestamp
optional
Date | null
The timestamp when this thread was resolved. Set to
null if this thread is not resolved.userID
optional
string
Certain changes to the thread may post a message into the thread -- in particular, resolving or unresolving a thread posts a message into the thread saying "User un/resolved this thread". This parameter is the ID of the User who will be listed as the author of that message. It's optional -- if no user is specified, then those messages won't get posted.
typing
optional
string[]
Marks the specified users as typing in this thread. The typing indicator expires after 3 seconds, so to continually show the indicator it needs to be called on an interval. Pass an empty array to clear all users' typing indicators.
resolved
optional
boolean
Whether the thread is resolved. Setting this to
true is equivalent to setting resolvedTimestamp to the current time, and setting this to false is equivalent to setting resolvedTimestamp to null.Response #
If successful, the response will be:
{
"success": true,
"message": "✅ You successfully updated thread abc123"
}Copy
Delete a thread #
This endpoint deletes a thread.
HTTP Request #
DELETE https://api.cord.com/v1/threads/<ID>Copy
Request Body #
This REST endpoint has no request body.
Response #
If successful, the response will be:
{
"success": true,
"message": "💀 You successfully deleted thread abc123"
}Copy