Messages

Send, edit, and react to messages in a conversation.

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.

struct MessageRef

References the message with a given message ID.

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

func messageRef.delete() async

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

Void

deleteFields

func messageRef.deleteFields(_:) async

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

fields (unnamed)

: String...

Returns

Void

edit

func messageRef.edit(text:custom:) async
func messageRef.edit(content:custom:) async

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

text (optional)

: String?

The new text to set as the message body.

custom (optional)

: [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

content

: [any 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 Link, ActionLink, or ActionButton, as they can be used to trick the recipient.

Returns

Void

get

func messageRef.get() async -> MessageSnapshot?

Fetches a snapshot of the message.

Returns

MessageSnapshot?

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

reaction

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

Reacting to the message with a Unicode emoji


1await MessageRef.reaction(emoji: "🚀").add()

Removing your custom emoji reaction from the message


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

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

struct MessageSnapshot

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

Method Overview

==	Inherited from `Equatable.==(_:_:)`.

Properties

content

: [any ContentBlock]

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

createdAt

: Int64

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

custom

: [String : String]

Custom metadata you have set on the message

editedAt (optional)

: Int64?

Time at which the message was last edited, as a unix timestamp in milliseconds. nil 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

: [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 nil 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 nil 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 .UserMessage messages and never present for .SystemMessage messages.

==

func messageSnapshot.==(_:_:) -> Bool

Inherited from Equatable.==(_:_:).

Parameters

lhs (unnamed)

: MessageSnapshot

rhs (unnamed)

: MessageSnapshot

Returns

Bool

struct ReferencedMessageSnapshot

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

Method Overview

==	Inherited from `Equatable.==(_:_:)`.

Properties

content

: [any ContentBlock]

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

createdAt

: Int64

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

custom

: [String : String]

Custom metadata you have set on the message

editedAt (optional)

: Int64?

Time at which the message was last edited, as a unix timestamp in milliseconds. nil 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

: [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 nil 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 .UserMessage because you cannot reply to a system message.

==

func referencedMessageSnapshot.==(_:_:) -> Bool

Inherited from Equatable.==(_:_:).

Parameters

lhs (unnamed)

: ReferencedMessageSnapshot

rhs (unnamed)

: ReferencedMessageSnapshot

Returns

Bool

struct MessageSubscription

A subscription to the messages in a specific conversation.

Method Overview

loadMore	Expand the window to include older messages
unsubscribe	Unsubscribe from this resource and stop receiving updates.

Properties

connected

: Deferred<MessageSubscriptionState>

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.

state

: MessageSubscriptionState { get }

The current state of the subscription

An enum with the following fields:

type is one of “pending”, “active”, “unsubscribed”, or “error”.

When type is “pending”, this property is MessageSubscriptionState.pending.

When type is “active”, this property is MessageSubscriptionState.active(latestSnapshot:loadedAll:).

When type is “unsubscribed”, this property is MessageSubscriptionState.unsubscribed.

When type is “error”, this property is MessageSubscriptionState.error(_:).

terminated

: Deferred<MessageSubscriptionState>

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.

loadMore

func messageSubscription.loadMore(count:) async

Expand the window to include older messages

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

Parameters

count (optional)

: Int?

The number of additional messages to load. Must be between 1 and 100

Returns

Void

unsubscribe

func messageSubscription.unsubscribe()

Unsubscribe from this resource and stop receiving updates.

If the subscription is already in the MessageSubscriptionState.unsubscribed or MessageSubscriptionState.error(_:) state, this is a no-op.

Returns

Void

enum MessageSubscriptionState

Values:

pending
unsubscribed
active(latestSnapshot:loadedAll:)
latestSnapshot: The most recently received snapshot for the messages, or nil if you’re not a participant in the conversation.
loadedAll: True if latestSnapshot contains all messages in the conversation. Use MessageSubscription.loadMore to load more.
latestSnapshot (optional)
: [MessageSnapshot]?
loadedAll
: Bool
error(_:)
The error that caused the subscription to be terminated
_ (unnamed)
: TalkJSError

enum MessageType

Values:

UserMessage
SystemMessage

enum MessageOrigin

Values:

web
rest
import
email

struct ReactionRef

References a specific emoji reaction on a message.

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.

Unicode emoji “👍”

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

func reactionRef.add() async

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

Void

remove

func reactionRef.remove() async

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

Void

struct 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

: Bool

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
2let sent = "👍"
3
4// React with thumbs up,
5await message.reaction(emoji: emoji).add()
6
7// Fetch the reaction
8let snapshot = await message.get()
9let received = snapshot!.reactions[0].emoji
10
11// Fails because TalkJS removed the variation selector
12assert(sent == received)

Unicode emoji “👍”

Custom emoji “:cat-roomba:”

Messages

struct MessageRef

Method Overview

Properties

conversationId

id

delete

Returns

deleteFields

Parameters

fields (unnamed)

Returns

edit

Parameters

text (optional)

custom (optional)

content

Returns

get

Returns

reaction

Parameters

emoji

Returns

struct MessageSnapshot

Method Overview

Properties

content

createdAt

custom

editedAt (optional)

id

origin

plaintext

reactions

referencedMessage (optional)

sender (optional)

type

==

Parameters

lhs (unnamed)

rhs (unnamed)

Returns

struct ReferencedMessageSnapshot

Method Overview

Properties

content

createdAt

custom

editedAt (optional)

id

origin

plaintext

reactions

referencedMessageId (optional)

sender (optional)

type

==

Parameters

lhs (unnamed)

rhs (unnamed)

Returns

struct MessageSubscription

Method Overview

Properties

connected

state

terminated

loadMore

Parameters

count (optional)

Returns

unsubscribe

Returns

enum MessageSubscriptionState

pending

unsubscribed

active(latestSnapshot:loadedAll:)

latestSnapshot (optional)

loadedAll