The endpoint accepts an optional filter query request parameter. Use this to filter notifications based on their properties.
filter
optional
NotificationListFilter
Notifications will be matched against the filters specified. 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
An arbitrary JSON object specified when the notification is created. The value for a metadata entry should be an object representing the metadata key/value to filter on. For example, to show only notifications with the metadata key of "category" set to "sales", set the filter to { metadata: { category: "sales" } }.
location
optional
Location
The location where the notifications live. This will be the location of the thread containing the message which prompted the notification.
organizationID
optional
string
The organization to which the message that prompted the notification belongs.
The IDs of the user(s) who sent this notification. The Cord backend will sometimes aggregate multiple notifications together, causing them to have multiple senders. For example, if multiple people react to the same message, that will generate only one notification (but with multiple senders, one for each person who reacted).
iconUrl
string | null
The URL of an icon image for this notification, if one was specified when it was created. This will always be null for Cord's internally-generated notifications (i.e., it can only be non-null for notifications you create via the REST API).
header
array
The "header" or "text" of the notification. This will represent text like "Alice replied to your thread." or similar. For notifications you create via the REST API, this will be based upon the template parameter, see below.
This is an array of items. Each item can be one of the following:
NotificationTextHeader
This is an object with the following fields:
type
"text"
Indicator that this is a string header node.
text
string
The text to display. This text may start and/or end with whitespace, which should typically not be trimmed. For example, in order to display the notification "Alice replied to your thread.", this would typically be composed of two nodes -- a user node for Alice, and then a text node containing " replied to your thread.", with a meaningful space at the front, to separate this node from Alice's name.
bold
boolean
Whether the text should be formatted in bold.
NotificationUserHeader
This is an object with the following fields:
type
"user"
Indicator that this is a user reference header node.
user
ClientUserData
The indicated user.
This is an object with the following fields:
id
string
The user's ID. This is unique within an application.
name
string | null
The user's name.
shortName
string | null
The user's short name. In most cases, Cord components will prefer using this name over name when set.
profilePictureURL
string | null
A URL to the user's profile picture.
metadata
EntityMetadata
Any metadata that has been set for the user.
attachment
Additional context attached to the notification. For example, if this notification is about a new reaction on a message, the attachment will specify what message received that new reaction.
A renderer will typically check the type field of the attachment and render that attachment type below the header.
This property can be one of the following:
null
NotificationURLAttachment
This is an object with the following fields:
type
"url"
Indicator that this is a URL attachment.
url
string
The URL this attachment points to. This would typically be the URL to send the browser to if this notification is clicked.
NotificationMessageAttachment
This is an object with the following fields:
type
"message"
Indicator that this is a message attachment.
message
CoreMessageData
The relevant message.
This is an object with the following fields:
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.
organizationID
string
The ID for the organization 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.
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.
seenBy
string[]
A list of IDs of the users that have seen the message.
readStatus
"unread" | "read"
Whether this notification has been read by the recipient yet.
timestamp
Date
The time this notification was sent.
extraClassnames
string | null
A space separated list of classnames to add to the notification.
metadata
EntityMetadata
An arbitrary JSON object specified when the notification was created. This will always be an empty object for Cord's internally-generated notifications (i.e., it can only be non-null for notifications you create via the REST API).
ID of user who is the "actor" sending the notification, i.e., the user taking the action the notification is about.
Required if template includes {{actor}}.
recipientID
required
string
ID of user receiving the notification.
template
required
string
Template for the header of the notification. The expressions {{actor}} and {{recipient}} will be replaced respectively with the notification's actor and recipient. (See below for an example.)
url
required
string
URL of page to go to when the notification is clicked.
iconUrl
optional
string
URL of an icon image if a specific one is desired. For notifications with an actor_id this will default to the sender's profile picture, otherwise it will default to a bell icon.
type
required
"url"
Currently must be set to url. In the future this may specify different types of notifications, but for now only url is defined.
metadata
optional
EntityMetadata
An arbitrary JSON object that can be used to set additional metadata on the notification. When displaying a list of notifications, you can filter the list by metadata value.
Keys are strings, and values can be strings, numbers or booleans.
extraClassnames
optional
string | null
An optional space separated list of classnames to add to the notification.
In this example, suppose a user with the ID 123 and name "Alice Applegate" exists, as well as another user with the ID 456 and name "Bob Bloke". Here is an example request to send a notification from Alice to Bob. When Bob receives this notification, it will say "Alice Applegate sent Bob Bloke a delicious sandwich", and will link tohttp://www.example.com/ when Bob clicks it.
curl"https://api.cord.com/v1/notifications"\ -X POST \ -H 'Authorization: Bearer <ACCESS_TOKEN>'\ -H 'Content-Type: application/json'\ -d '{
"actorID": "123",
"recipientID": "456",
"template": "{{actor}} sent {{recipient}} a delicious sandwich",
"url": "http://www.example.com/",
"type": "url"
}'
Suppose a new user with ID 789 and name "Carol Capable" joins the application, and we would like to notify Alice that this happened. Here is an example request to send such a notification to Alice. When Alice receives this notification, it will say "Carol Capable joined the team", and will link to http://www.example.com/ when Alice clicks it.
curl "https://api.cord.com/v1/notifications" \
-X POST \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{"actorID":"789","recipientID":"123","template":"{{actor}} joined the team","url":"http://www.example.com/","type":"url"}'
Copy
The response to this request will look the same as the response to the first example.