Messages

A message contains some content that was sent in a conversation. Users send messages using ConversationRef.send. You can track the a conversation's messages in real-time using ConversationRef.subscribeMessages.

class 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 and .

Method Overview

delete	Deletes this message, or does nothing if the message does not exist.
deleteFields	Deletes properties of this message.
edit	Edits this message.
get	Fetches a snapshot of the message.
reaction	Get a reference to a specific emoji reaction on this 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(): Unit

Deletes this message, or does nothing if the message does not exist.

Deleting a nonexistent message is treated as success.

This function will throw if you are not a participant in the conversation or if your role does not give you permission to delete this message.

Returns

Unit

deleteFields

messageRef.deleteFields(vararg fields): Unit

Deletes properties of this message.

Pass the name of each property to delete as a separate parameter to this function. To delete a field in the custom property, pass it as custom.FIELD_TO_DELETE.

Parameters

vararg fields

: String

Returns

Unit

edit (1)

messageRef.edit(params): Unit

Edits this message.

The function will throw if the request is invalid, the message doesn't exist, or you do not have permission to edit that message.

Parameters

params

: String

Returns

Unit

edit (2)

messageRef.edit(params): Unit

Edits this message.

The function will throw if the request is invalid, the message doesn't exist, or you do not have permission to edit that message.

Parameters

params

: EditTextMessageParams

Returns

Unit

edit (3)

messageRef.edit(params): Unit

Edits this message.

The function will throw if the request is invalid, the message doesn't exist, or you do not have permission to edit that message.

Parameters

params

: EditMessageParams

Returns

Unit

get

messageRef.get(): MessageSnapshot?

Fetches a snapshot of the message.

Returns

MessageSnapshot?

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.

reaction

messageRef.reaction(emoji): ReactionRef

Get a reference to a specific emoji reaction on this message

If you call .reaction with an invalid emoji, it will still succeed and you will still get a ReactionRef. However, the TalkJS server will reject any calls that use an invalid emoji.

In the future, this will also be used to fetch a full list of people who used that specific reaction on the message.

Parameters

emoji

: String

The emoji for the reaction you want to reference. a single Unicode emoji like "🚀" or a custom emoji like ":cat_roomba:". Custom emoji can be up to 50 characters long.

Returns

ReactionRef

A ReactionRef for the reaction with that emoji on this message. Throws If the emoji is not a string or is an empty string

Usage

Example 1

Reacting to the message with a Unicode emoji


1MessageRef.reaction("🚀").add()

Example 2

Removing your custom emoji reaction from the message


1MessageRef.reaction(":cat-roomba:").remove()

data class EditTextMessageParams

Parameters you can pass when editing a message.

Properties that are null will not be changed. To clear / reset a property to the default, call MessageRef.deleteFields instead.

Properties

custom (optional)

: Map<String, String?>?

Custom metadata you have set on the user. This value acts as a patch. Remove specific properties by calling MessageRef.deleteFields Default = no custom metadata

text (optional)

: String?

The new text to set as the message body

data class EditMessageParams

Parameters you can pass to MessageRef.edit.

Properties that are null will not be changed. To clear / reset a property to the default, call MessageRef.deleteFields instead.

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.

Properties

content (optional)

: List<ContentBlock>?

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)

: Map<String, String?>?

Custom metadata you have set on the message. This value acts as a patch. Remove specific properties by calling MessageRef.deleteFields Default = no custom metadata

data class 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.

Properties

content

: List<ContentBlock>

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

createdAt

: Long

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

custom

: Map<String, String>

Custom metadata you have set on the message

editedAt (optional)

: Long?

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

: MessageOrigin

Where this message origiranted from:

WEB = Message sent via the UI or via ConversationBuilder.sendMessage

REST = Message sent via the REST API's "send message" endpoint

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.

reactions

: List<ReactionSnapshot>

All the emoji reactions that have been added to this message.

There can be up to 50 different reactions on each message.

referencedMessage (optional)

: ReferencedMessageSnapshot?

A snapshot of the message that this message is aa 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 (optional)

: UserSnapshot?

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.

type

: MessageType

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

The sender property is always present for USER_MESSAGE messages and never present for SYSTEM_MESSAGE messages.

data class 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

content

: List<ContentBlock>

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

createdAt

: Long

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

custom

: Map<String, String>

Custom metadata you have set on the message

editedAt (optional)

: Long?

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

: MessageOrigin

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

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.

reactions

: List<ReactionSnapshot>

All the emoji reactions that have been added to this message.

referencedMessageId (optional)

: String?

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 (optional)

: 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

type

: MessageType

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

data class MessageSubscription

A subscription to the messages in a specific conversation.

Get a MessageSubscription by calling

The subscription is 'windowed'. It includes all messages since a certain point in time. By default, you subscribe to the 30 most recent messages, and any new messages that are sent after you subscribe.

You can expand this window by calling MessageSubscription.loadMore, which extends the window further into the past.

Remember to .unsubscribe the subscription once you are done with it.

Properties

connected

: Deferred<SubscriptionState>

Resolves when the subscription starts receiving updates from the server.

Wait for this promise if you want to perform some action as soon as the subscription is active.

The promise rejects if the subscription is terminated before it connects.

loadMore

: suspend (Int?) -> Unit

Expand the window to include older messages

Calling loadMore multiple times in parallel will still only load one page of messages.

state

: SubscriptionState

The current state of the subscription

An object with the following fields:

type is one of "pending", "active", "unsubscribed", or "error".

When type is "pending", the subclass type of this property is .

When type is "active", the subclass type of this property is MessageActiveState.

When type is "unsubscribed", the subclass type of this property is .

When type is "error", the subclass type of this property is .

terminated

: Deferred<SubscriptionState>

Resolves when the subscription permanently stops receiving updates from the server.

This is either because you unsubscribed or because the subscription encountered an unrecoverable error.

unsubscribe

: () -> Unit

Unsubscribe from this resource and stop receiving updates.

If the subscription is already in the or , this is a no-op.

data class MessageActiveState

The state of a messages subscription when it is actively listening for changes

Properties

latestSnapshot (optional)

: List<MessageSnapshot>?

The most recently received snapshot for the messages, or null if you're not a participant in the conversation.

loadedAll

: Boolean

True if latestSnapshot contains all messages in the conversation. Use MessageSubscription.loadMore to load more.

type

: String

enum MessageType

Values:

USER_MESSAGE
SYSTEM_MESSAGE

enum MessageOrigin

Values:

WEB
REST
IMPORT
EMAIL

class ReactionRef

References a specific emoji reaction on a message.

Used in all Data API operations affecting that emoji reaction, such as adding or removing the reaction. Created via MessageRef.reaction.

Method Overview

add	Adds this emoji reaction onto the message, from the current user.
remove	Removes this emoji reaction from the message, from the current user.

Properties

conversationId

: String

The ID of the conversation the message belongs to.

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

emoji

: String

Which emoji the reaction is using.

Either a single Unicode emoji, or the name of a custom emoji with a colon at the start and end. This is not validated until you send a request to the server. Since custom emoji are configured in the frontend, there are no checks to make sure a custom emoji actually exists.

Immutable: if you want to use a different emoji, get a new ReactionRef instead.

Example 1

Unicode emoji "👍"

Example 2

Custom emoji ":cat-roomba:"

messageId

: String

The ID of the message that this is a reaction to.

Immutable: if you want to react to a different message, get a new ReactionRef instead.

add

reactionRef.add(): Unit

Adds this emoji reaction onto the message, from the current user.

The function will throw if the request is invalid, the message doesn't exist, there are already 50 different reactions on this message, or if you do not have permission to use emoji reactions on that message.

Returns

Unit

remove

reactionRef.remove(): Unit

Removes this emoji reaction from the message, from the current user.

The function will throw if the request is invalid, the message doesn't exist, or you do not have permission to use emoji reactions on that message.

Returns

Unit

data class ReactionSnapshot

A summary of a single emoji reaction on a message.

Properties

count

: Int

The number of times this emoji has been added to the message.

currentUserReacted

: Boolean

Whether the current user has reacted to the message with this emoji.

emoji

: String

Which emoji the users reacted with.

Either a single Unicode emoji, or the name of a custom emoji with a colon at the start and end. Since custom emoji are defined in the frontend, they are not validated by the TalkJS server. The UI should ignore reactions that use unrecognised custom emoji.

NOTE: In unicode, it is possible to have multiple emoji that look identical but are represented differently. For example, "👍" != "👍️" because the second emoji includes a variation selector 16 codepoint. This codepoint forces the character to appear as an emoji.

TalkJS normalises all emoji reactions to be "fully qualified" according to this list. This prevents a message having multiple separate 👍 reactions.

Be careful when processing the emoji property, as this normalisation might break equality checks:


1// Emoji has unnecessary variation selector 16
2val sent = "👍"
3
4// React with thumbs up,
5message.reaction(emoji).add()
6
7// Fetch the reaction
8val snapshot = message.get()
9val received = snapshot.reactions[0].emoji
10
11// Fails because TalkJS removed the variation selector
12assert sent == received;

Example 1

Unicode emoji "👍"

Example 2

Custom emoji ":cat-roomba:"