Cord LogoDocs
Sign inStart now

Notifications

REST API /
Ask the Community

All available operations for sending and manipulating notifications

List all notifications #

This endpoint returns information about all of the notifications that a specific user has received.

HTTP Request #

HTTP:
GET https://api.cord.com/v1/users/<USER_ID>/notifications
cURL:
curl "https://api.cord.com/v1/users/<USER_ID>/notifications" \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'
CLI:
# you can install @cord-sdk/cli for a simpler experience
cord notification ls <USER_ID>
GET https://api.cord.com/v1/users/<USER_ID>/notifications
Copy

Request Body #

This REST endpoint has no request body.

Request Parameters #

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:

Show property details

Response #

The response is a JSON array of objects with the following fields:

id
string
The ID for this notification.
senderUserIDs
string[]
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).
NotificationHeaderNode[]
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:

    Show property details

  • NotificationUserHeader

    This is an object with the following fields:

    Show property details

headerTranslation
Translation | null
A translation that can be used to translate the header of the notification. All Cord-created notifications will have a translation, but this may be null for notifications you create through the REST API. See the translations documentation for more information.

This is an object with the following fields:

Show property details

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:

    Show property details

  • NotificationMessageAttachment

    This is an object with the following fields:

    Show property details

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).

Create a notification #

This endpoint creates and sends a notification. These notifications will appear in the standalone notification list, the notification list launcher, and the notification API.

HTTP Request #

HTTP:
POST https://api.cord.com/v1/notifications
cURL:
curl "https://api.cord.com/v1/users/<USER_ID>/notifications" \
  -X POST \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'\
  -H 'Content-Type: application/json'
CLI:
# you can install @cord-sdk/cli for a simpler experience
cord notification create
POST https://api.cord.com/v1/notifications
Copy

Request Body #

actorID
optional
string
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.

Example Request #

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:
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"
  }'
CLI:
cord notification create 
--author-id=123 
--recipient-id=456 
--template="{{actor}} send {{recipient}} a delicious sandwich" 
--url=http://www.example.com
--type=url
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"
  }'
Copy

If the request succeeds, the response will be:

JSON:
{
    "success": true,
    "message": "Notification created.",
    "notificationID": "<NEW_ID>"
}
{
    "success": true,
    "message": "Notification created.",
    "notificationID": "<NEW_ID>"
}
Copy

If the request does not succeed, the response will instead contain anerror and message explaining what went wrong:

JSON:
{
  "error": "<ERROR_CODE>",
  "message": "An explanation of the error code."
}
{
  "error": "<ERROR_CODE>",
  "message": "An explanation of the error code."
}
Copy

Another Example #

Suppose a new user with ID 789 and name "Carol Capable" joins the project, 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.

JSON:
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"
  }'
CLI:
# you can install @cord-sdk/cli for a simpler experience
cord notification create
    --actor-id=789
    --recipient-id=123
    --template="{{actor}} joined the team"
    --url=http://www.example.com/
    --type=url
  }'
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.

Current Limitations #

  • Sending a notification does not currently have the ability to additionally notify the recipient via Email and/or Slack.

Delete a notification #

This endpoint deletes a notification.

HTTP Request #

HTTP:
DELETE https://api.cord.com/v1/notifications/<NOTIFICATION_ID>
cURL:
curl "https://api.cord.com/v1/notifications/<NOTIFICATION_ID>" \
  -X DELETE \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'
CLI:
# you can install @cord-sdk/cli for a simpler experience
cord notification delete <ID>
DELETE https://api.cord.com/v1/notifications/<NOTIFICATION_ID>
Copy

Request Body #

This REST endpoint has no request body.

Response #

If successful, the response will be:

JSON:
{
  "success": true,
  "message": "💀 You successfully deleted notification abc123"
}
{
  "success": true,
  "message": "💀 You successfully deleted notification abc123"
}
Copy

Not finding the answer you need? Ask our Developer Community

Ask Cordy