notification-created

This event is fired when a new notification is created, whether via the UI or API or anywhere else.


Payload #


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

recipientUserID #

string

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

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 property 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 a project.

    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.

    displayName
    string
    The primary display name of the user. This is a readonly field that's provided as a convenience. Its value is the user's shortName or name, preferring shortName if both are set, or the string "unknown" if neither is set.

    secondaryDisplayName
    string
    The secondary display name of the user, in cases where you might want to display a secondary name (such as in a subtitle). This is a readonly field that's provided as a convenience. Its value is the user's name or shortName, preferring name if both are set, or the string "Unknown" if neither is 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.

    groupID
    string
    The ID for the group 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.

    translationKey
    string | null
    An optional translation key used for this message. This is useful for system-generated messages where you might want to translate or customize them at runtime. See the translations documentation for more information.

    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
    The items attached to this message.

    This property can be one of the following:

    • MessageFileAttachment

      This is an object with the following fields:


      type
      "file"
      The type of this attachment, which is always file for file attachments.

      id
      string
      The ID of the file.

      name
      string
      The name of the file.

      url
      string
      The URL that a user can use to download the file. This is a signed URL that will expire after 24 hours.

      mimeType
      string
      The MIME type of the file.

      size
      number
      The size of the file, in bytes.

      uploadStatus
      "uploading" | "uploaded" | "failed" | "cancelled"
      The status of the file upload. uploading means that the user has not yet completed uploading the file, uploaded means the file is successfully uploaded, failed means the upload encountered an error, and cancelled means the user cancelled the upload before it was finished.
    • MessageAnnotationAttachment

      This is an object with the following fields:


      type
      "annotation"
      The type of this attachment, which is always annotation for annotation attachments.

      screenshot
      UploadedFile | null
      The screenshot attached to the annotation, if any.

      This is an object with the following fields:


      id
      string
      The ID of the file.

      name
      string
      The name of the file.

      url
      string
      The URL that a user can use to download the file. This is a signed URL that will expire after 24 hours.

      mimeType
      string
      The MIME type of the file.

      size
      number
      The size of the file, in bytes.

      uploadStatus
      "uploading" | "uploaded" | "failed" | "cancelled"
      The status of the file upload. uploading means that the user has not yet completed uploading the file, uploaded means the file is successfully uploaded, failed means the upload encountered an error, and cancelled means the user cancelled the upload before it was finished.

      locationData
      string | null
      The opaque location data generated by Cord. This field may or may not be set, depending on how the annotation was created. The value will be an opaque string that can be passed to stringToViewportCoordinates.

      customData
      CustomAnnotationData | null
      The custom location data for this annotation. This will only be set if you're using the Annotations API to customize your annotation locations.

      This is an object with the following fields:


      location
      Location
      The custom location you produced for this annotation at annotation capture time.

      coordsRelativeToTarget
      object
      The offset of the annotation relative to the element identified by location, in pixels, at the time the annotation was captured. The location and coordsRelativeToTarget will be supplied to the Annotations API render handler in order to position the annotation.

      This is an object with the following fields:


      x
      number

      y
      number

      label
      string | null
      Your custom user-visible label for the annotation, if any.

      textContent
      string | null
      The text that was selected when creating the annotation, if any.
    • MessageScreenshotAttachment

      This is an object with the following fields:


      type
      "screenshot"
      The type of this attachment, which is always screenshot for screenshot attachments.

      screenshot
      UploadedFile
      The screenshot attached to the message. Screenshots are attached via screenshotOptions.captureWhen API.

      This is an object with the following fields:


      id
      string
      The ID of the file.

      name
      string
      The name of the file.

      url
      string
      The URL that a user can use to download the file. This is a signed URL that will expire after 24 hours.

      mimeType
      string
      The MIME type of the file.

      size
      number
      The size of the file, in bytes.

      uploadStatus
      "uploading" | "uploaded" | "failed" | "cancelled"
      The status of the file upload. uploading means that the user has not yet completed uploading the file, uploaded means the file is successfully uploaded, failed means the upload encountered an error, and cancelled means the user cancelled the upload before it was finished.
    • MessageLinkPreviewAttachment

      This is an object with the following fields:


      type
      "link_preview"
      The type of this attachment, which is always link_preview for file link previews.

      url
      string
      The url from which the preview was generated.

      imageURL
      string | null
      URL of the image to show in the link preview. It is usually specified in the meta or og tags of the page.

      title
      string | null
      Title for the link preview. Sometimes it's the page title, sometimes it is specified in meta or og tags.

      description
      string | null
      Description for the link preview. Generated from the url provided from meta or og tags in the page.

    reactions
    Reaction[]
    The reactions to this message.

    This is an array of objects, each of which has the following fields:


    reaction
    string
    The emoji reaction.

    userID
    string
    The ID of the user who reacted to the message.

    timestamp
    Date
    The timestamp of when the reaction was created.

    seenBy
    string[]
    A list of IDs of the users that have seen the message.

    skipLinkPreviews
    boolean
    If set, Cord won't analyze links in the message to generate previews.

readStatus #

"unread" | "read"
Whether this notification has been read by the recipient yet.

timestamp #

Date
The time this notification was sent.

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

Ask Cordy