Notifications

All available operations for sending and manipulating notifications


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

POST https://api.cord.com/v1/notifications
Copy

Request Body


actorID

optional
string
ID of user who is the "actor" sending the notification

recipientID

required
string
ID of user who is 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

type

required
string
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
object
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.

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 "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:

{
    "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:

{
  "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 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.


Current Limitations

  • The notification must be "from" an existing user (the actor); it is not possible to have an actor-less notification due to current product limitations. We anticipate lifting this restriction in the future.
  • Similarly, the template must have the {{ actor }} expression. We anticipate lifting this restriction in the future as well.
  • Sending a notification does not currently have the ability to additionally notify the recipient via Email and/or Slack.