Messages

Users can send messages in conversations.

interface MessageRef

References the message with a given message ID.

Used in all Data API operations affecting that message, such as fetching or editing the message attributes, or deleting the message. Created via ConversationRef​.message and ConversationRef​.send.

Method Overview

delete

Deletes this message, or does nothing if they are already not a participant.

edit

Edits this message.

get

Fetches a snapshot of the message.

Properties

conversationId
: string

The ID of the conversation that the referenced message belongs to.

Immutable: if you want to reference a message from a different conversation, get a new MessageRef from that conversation.

id
: string

The ID of the referenced message.

Immutable: if you want to reference a different message, get a new MessageRef instead.

delete

messageRef.delete(): Promise<void>

Deletes this message, or does nothing if they are already not a participant.

Deleting a nonexistent message is treated as success, and the promise will resolve.

Returns

Promise<void>

A promise that resolves when the operation completes. This promise will reject if you are not a participant in the conversation or if your role does not give you permission to delete this message.

edit

messageRef.edit(params): Promise<void>

Edits this message.

Parameters

interface EditTextMessageParams

Parameters you can pass to MessageRef​.edit.

Properties that are undefined will not be changed. To clear / reset a property to the default, pass null.

This is a simpler version of EditMessageParams that only supports setting the message content to text.

custom (optional)
: Record<string, string | null> | null

Custom metadata you have set on the message. This value acts as a patch. Remove specific properties by setting them to null. Default = no custom metadata

text (optional)
: string

The new text to set in the message body.

This is parsed the same way as the text entered in the message field. For example, *hi* will appear as hi in bold.

See the message formatting documentation for more details.

interface EditMessageParams

Parameters you can pass to MessageRef​.edit.

Properties that are undefined will not be changed. To clear / reset a property to the default, pass null.

This is the more advanced method for editing a message. It gives you full control over the message content. You can decide exactly how a text message should be formatted, edit an attachment, or even turn a text message into a location.

content (optional)
: [SendContentBlock]

The new content for the message.

Any value provided here will overwrite the existing message content.

By default users do not have permission to send LinkNode, ActionLinkNode, or ActionButtonNode, as they can be used to trick the recipient.

custom (optional)
: Record<string, string | null> | null

Custom metadata you have set on the message. This value acts as a patch. Remove specific properties by setting them to null. Default = no custom metadata

Returns

Promise<void>

A promise that resolves when the operation completes. The promise will reject if the request is invalid, the message doesn't exist, or you do not have permission to edit that message.

get

messageRef.get(): Promise<MessageSnapshot | null>

Fetches a snapshot of the message.

Supports Cached Fetch

Returns

Promise<MessageSnapshot | null>

A snapshot of the message's attributes, or null if the message doesn't exist, the conversation doesn't exist, or you're not a participant in the conversation.

interface MessageSnapshot

A snapshot of a message's attributes at a given moment in time.

Automatically expanded to include a snapshot of the user that sent the message, and a snapshot of the referenced message, if this message is a reply.

Snapshots are immutable and we try to reuse them when possible. You should only re-render your UI when oldSnapshot !== newSnapshot.

Properties

type
: "UserMessage" | "SystemMessage"

Whether this message was "from a user" or a general system message without a specific sender.

The sender property is always present for "UserMessage" messages and never present for "SystemMessage" messages.

content
: ContentBlock[]

The main body of the message, as a list of blocks that are rendered top-to-bottom.

createdAt
: number

Time at which the message was sent, as a unix timestamp in milliseconds

custom
: Record<string, string>

Custom metadata you have set on the message

editedAt
: number | null

Time at which the message was last edited, as a unix timestamp in milliseconds. null if the message has never been edited.

id
: string

The unique ID that is used to identify the message in TalkJS

origin
: "web" | "rest" | "import" | "email"

Where this message originated from:

- "web" = Message sent via the UI or via ConversationBuilder​.sendMessage

- "rest" = Message sent via the REST API's "send message" endpoint or ConversationRef​.send

- "import" = Message sent via the REST API's "import messages" endpoint

- "email" = Message sent by replying to an email notification

plaintext
: string

The contents of the message, as a plain text string without any formatting or attachments. Useful for showing in a conversation list or in notifications.

referencedMessage
: ReferencedMessageSnapshot | null

A snapshot of the message that this message is a reply to, or null if this message is not a reply.

Only UserMessages can reference other messages. The referenced message snapshot does not have a referencedMessage field. Instead, it has referencedMessageId. This prevents TalkJS fetching an unlimited number of messages in a long chain of replies.

sender
: UserSnapshot | null

A snapshot of the user who sent the message, or null if it is a system message. The user's attributes may have been updated since they sent the message, in which case this snapshot contains the updated data. It is not a historical snapshot.

interface ReferencedMessageSnapshot

A snapshot of a message's attributes at a given moment in time, used in MessageSnapshot​.referencedMessage.

Automatically expanded to include a snapshot of the user that sent the message. Since this is a snapshot of a referenced message, its referenced message is not automatically expanded, to prevent fetching an unlimited number of messages in a long chain of replies. Instead, contains the referencedMessageId field.

Snapshots are immutable and we try to reuse them when possible. You should only re-render your UI when oldSnapshot !== newSnapshot.

Properties

type
: "UserMessage"

Referenced messages are always "UserMessage" because you cannot reply to a system message.

content
: ContentBlock[]

The main body of the message, as a list of blocks that are rendered top-to-bottom.

createdAt
: number

Time at which the message was sent, as a unix timestamp in milliseconds

custom
: Record<string, string>

Custom metadata you have set on the message

editedAt
: number | null

Time at which the message was last edited, as a unix timestamp in milliseconds. null if the message has never been edited.

id
: string

The unique ID that is used to identify the message in TalkJS

origin
: "web" | "rest" | "import" | "email"

Where this message originated from:

- "web" = Message sent via the UI or via ConversationBuilder​.sendMessage

- "rest" = Message sent via the REST API's "send message" endpoint or ConversationRef​.send

- "import" = Message sent via the REST API's "import messages" endpoint

- "email" = Message sent by replying to an email notification

plaintext
: string

The contents of the message, as a plain text string without any formatting or attachments. Useful for showing in a conversation list or in notifications.

referencedMessageId
: string | null

The ID of the message that this message is a reply to, or null if this message is not a reply.

Since this is a snapshot of a referenced message, we do not automatically expand its referenced message. The ID of its referenced message is provided here instead.

sender
: UserSnapshot

A snapshot of the user who sent the message. The user's attributes may have been updated since they sent the message, in which case this snapshot contains the updated data. It is not a historical snapshot.

Guaranteed to be set, unlike in MessageSnapshot, because you cannot reference a SystemMessage