--- url: https://talkjs.com/docs/Data_APIs/Kotlin/Messages title: 'Messages' minidoc-source: kotlin --- A message contains some content that was sent in a conversation. Users send messages using [ConversationRef.send](/Kotlin_Data_API/Conversations/#ConversationRef__send__1). You can track the a conversation's messages in real-time using [ConversationRef.subscribeMessages](/Kotlin_Data_API/Conversations/#ConversationRef__subscribeMessages). ## 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]. */ class MessageRef { /** The ID of the referenced message. Immutable: if you want to reference a different message, get a new MessageRef instead. */ val id: 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. */ val conversationId: String /** 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. Example 1: Reacting to the message with a Unicode emoji ```kotlin MessageRef.reaction("🚀").add() ``` Example 2: Removing your custom emoji reaction from the message ```kotlin MessageRef.reaction(":cat-roomba:").remove() ``` @param emoji 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. */ fun reaction(emoji: String): ReactionRef /** Fetches a snapshot of the message. */ suspend fun get(): MessageSnapshot? /** 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. @param text The new text to set as the message body. @param custom 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 @param content 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. @param custom 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 */ suspend fun edit(text: String?, custom: Map?): Unit #1 suspend fun edit(content: List, custom: Map?): Unit #2 /** 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`. */ suspend fun deleteFields(vararg fields: String): 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. */ suspend fun delete(): Unit } ## 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. */ data class MessageSnapshot { /** The unique ID that is used to identify the message in TalkJS */ val id: String /** 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. */ val type: MessageType /** 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. */ val sender: UserSnapshot? /** Custom metadata you have set on the message */ val custom: Map/** Time at which the message was sent, as a unix timestamp in milliseconds. */ val createdAt: Long /** Time at which the message was last edited, as a unix timestamp in milliseconds. `null` if the message has never been edited. */ val editedAt: Long? /** 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. */ val referencedMessage: ReferencedMessageSnapshot? /** 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 */ val origin: MessageOrigin /** 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. */ val plaintext: String /** The main body of the message, as a list of blocks that are rendered top-to-bottom. */ val content: List/** All the emoji reactions that have been added to this message. There can be up to 50 different reactions on each message. */ val reactions: Listconstructor(id: String, type: MessageType, sender: UserSnapshot?, custom: Map, createdAt: Long, editedAt: Long?, referencedMessage: ReferencedMessageSnapshot?, origin: MessageOrigin, plaintext: String, content: List, reactions: List) } ## 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`. */ data class ReferencedMessageSnapshot { /** The unique ID that is used to identify the message in TalkJS */ val id: String /** Referenced messages are always `USER_MESSAGE` because you cannot reply to a system message. */ val type: MessageType /** 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 */ val sender: UserSnapshot? /** Custom metadata you have set on the message */ val custom: Map/** Time at which the message was sent, as a unix timestamp in milliseconds */ val createdAt: Long /** Time at which the message was last edited, as a unix timestamp in milliseconds. `null` if the message has never been edited. */ val editedAt: Long? /** 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. */ val referencedMessageId: String? /** 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 */ val origin: MessageOrigin /** 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. */ val plaintext: String /** The main body of the message, as a list of blocks that are rendered top-to-bottom. */ val content: List/** All the emoji reactions that have been added to this message. */ val reactions: Listconstructor(id: String, type: MessageType, sender: UserSnapshot?, custom: Map, createdAt: Long, editedAt: Long?, referencedMessageId: String?, origin: MessageOrigin, plaintext: String, content: List, reactions: List) } ## MessageSubscription /** A subscription to the messages in a specific conversation. Get a MessageSubscription by calling [ConversationRef.subscribeMessages] 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. */ data class MessageSubscription { /** 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 [PendingState]. When `type` is "active", the subclass type of this property is [MessageActiveState]. When `type` is "unsubscribed", the subclass type of this property is [UnsubscribedState]. When `type` is "error", the subclass type of this property is [ErrorState]. */ val state: 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. */ val connected: Deferred/** 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. */ val terminated: Deferred/** Unsubscribe from this resource and stop receiving updates. If the subscription is already in the [UnsubscribedState] or [ErrorState], this is a no-op. */ val unsubscribe: ()->Unit /** Expand the window to include older messages Calling `loadMore` multiple times in parallel will still only load one page of messages. */ val loadMore: suspend (count: Int?)->Unit constructor(state: SubscriptionState, connected: Deferred, terminated: Deferred, unsubscribe: ()->Unit, loadMore: suspend (count: Int?)->Unit) } ## MessageActiveState /** The state of a messages subscription when it is actively listening for changes */ data class MessageActiveState { /** The most recently received snapshot for the messages, or `null` if you're not a participant in the conversation. */ val latestSnapshot: List? /** True if `latestSnapshot` contains all messages in the conversation. Use [MessageSubscription.loadMore] to load more. */ val loadedAll: Boolean val type: String constructor(latestSnapshot: List?, loadedAll: Boolean, type: String) } ## MessageType /**

Values:

  • USER_MESSAGE
  • SYSTEM_MESSAGE
*/ enum MessageType { USER_MESSAGE, SYSTEM_MESSAGE } ## MessageOrigin /**

Values:

  • WEB
  • REST
  • IMPORT
  • EMAIL
*/ enum MessageOrigin { WEB, REST, IMPORT, EMAIL } ## 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]. */ class ReactionRef { /** 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:" */ val emoji: 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. */ val messageId: 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. */ val conversationId: String /** 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. */ suspend fun add(): 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. */ suspend fun remove(): Unit } ## ReactionSnapshot /** A summary of a single emoji reaction on a message. */ data class ReactionSnapshot { /** 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](https://en.wikipedia.org/wiki/Variation_Selectors_(Unicode_block)). This codepoint forces the character to appear as an emoji. TalkJS normalises all emoji reactions to be "fully qualified" [according to this list](https://unicode.org/Public/emoji/16.0/emoji-test.txt). This prevents a message having multiple separate 👍 reactions. Be careful when processing the `emoji` property, as this normalisation might break equality checks: ```kotlin // Emoji has unnecessary variation selector 16 val sent = "👍" // React with thumbs up, message.reaction(emoji).add() // Fetch the reaction val snapshot = message.get() val received = snapshot.reactions[0].emoji // Fails because TalkJS removed the variation selector assert sent == received; ``` Example 1: Unicode emoji "👍" Example 2: Custom emoji ":cat-roomba:" */ val emoji: String /** The number of times this emoji has been added to the message. */ val count: Int /** Whether the current user has reacted to the message with this emoji. */ val currentUserReacted: Boolean constructor(emoji: String, count: Int, currentUserReacted: Boolean) }