Get message data

Fetch data for a specific message


Overview #

This method allows you fetch data for a single message, including live updates.
React:
import { thread } from '@cord-sdk/react';
const message = thread.useMessage('my-awesome-message-id');

return message && <div>Message with id: {message.id} found!</div>;
Vanilla JavaScript:
const ref = window.CordSDK.thread.observeMessage(
  'my-awesome-message-id',
  (message) => {
    console.log('Got a thread data update:');
    if (message === undefined) {
      console.log('Loading...');
    }
    if (message) {
      console.log(`Message /${message.id} was authored by: /${message.authorID}`)
    }
  }
);
// ... Later, when updates are no longer needed ...
window.CordSDK.thread.unobserveMessage(ref);
import { thread } from '@cord-sdk/react';
const message = thread.useMessage('my-awesome-message-id');

return message && <div>Message with id: {message.id} found!</div>;
Copy

Available Data #

The API provides an object which has the following fields:


seen #

boolean
Whether the message has been seen by the current viewer.

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 #

array
The items attached to this message.

This is an array of items. Each item 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.

What this function returns #

The hook will initially return undefined while the data loads from our API. Once it has loaded, your component will re-render and the hook will return an an object containing the message data. If no message matching the provided messageID is found, it will return null instead.

Arguments this function takes #


messageID #

required
string
The ID of the message.

Ask Cordy