Conversations
A conversation is a chat channel where messages can be sent. Users can participate in many conversations at once.
| createIfNotExists | Creates this conversation if it does not already exist. |
| deleteFields | Deletes properties of this conversation. |
| get | Fetches a snapshot of the conversation. |
| markAsRead | Marks the conversation as read. |
| markAsTyping | Marks the current user as typing in this conversation for 10 seconds. |
| markAsUnread | Marks the conversation as unread. |
| message | Get a reference to a message in this conversation |
| participant | Get a reference to a participant in this conversation |
| send | Sends a message in the conversation |
| set | Sets properties of this conversation and your participation in it. |
| subscribe | Subscribes to the conversation. |
| subscribeMessages | Subscribes to the messages in the conversation. |
| subscribeParticipants | Subscribes to the participants in the conversation. |
| subscribeTyping | Subscribes to the typing status of the conversation. |
The ID of the referenced conversation.
Immutable: if you want to reference a different conversation, get a new ConversationRef instead.
conversationRef.createIfNotExists(data): Unit
Creates this conversation if it does not already exist.
Adds you as a participant in this conversation, if you are not already a participant.
If the conversation already exists or you are already a participant, this operation is still considered successful. The function throws if you are not already a participant and client-side conversation syncing is disabled.
Parameters
data class CreateConversationParams
Parameters you can pass when creating a conversation.
Properties that are null will be set to the default
Your access to the conversation. Default = READ_WRITE access.
Custom metadata you have set on the conversation. Default = no custom metadata
Your notification settings. Default = TRUE
The URL for the conversation photo to display in the chat header. Default = no photo, show a placeholder image.
The conversation subject to display in the chat header. Default = no subject, list participant names instead
System messages which are sent at the beginning of a conversation. Default = no messages.
Returns
conversationRef.get(): ConversationSnapshot?
Fetches a snapshot of the conversation.
This contains all of the information related to the conversation and the current user's participation in the conversation.
Returns
A snapshot of the current user's view of the conversation, or null if the current user is not a participant (including if the conversation doesn't exist)
conversationRef.markAsRead(): Unit
Marks the conversation as read.
The function throws if you are not a participant in the conversation.
Returns
conversationRef.markAsTyping(): Unit
Marks the current user as typing in this conversation for 10 seconds.
This means that other users will see a typing indicator in the UI, from the current user.
The user will automatically stop typing after 10 seconds. You cannot manually mark a user as "not typing". Users are also considered "not typing" when they send a message, even if that message was sent from a different tab or using the REST API.
To keep the typing indicator visible for longer, call this function again to reset the 10s timer.
Returns
conversationRef.markAsUnread(): Unit
Marks the conversation as unread.
The function throws if you are not a participant in the conversation.
Returns
conversationRef.send(params): MessageRef
Sends a message in the conversation
Parameters
Returns
A reference to the newly created message. The function throws if you are not a participant with write access in this conversation.
conversationRef.send(params): MessageRef
Sends a message in the conversation
Parameters
Returns
A reference to the newly created message. The function throws if you are not a participant with write access in this conversation.
conversationRef.set(data): Unit
Sets properties of this conversation and your participation in it.
The conversation is created if a conversation with this ID doesn't already exist. You are added as a participant if you are not already a participant in the conversation. When client-side conversation syncing is disabled, you may only set your notify property, when you are already a participant. Everything else requires client-side conversation syncing to be enabled, and will cause the function to throw.
Parameters
data class SetConversationParams
Parameters you can pass when updating a conversation.
Properties that are null will not be changed. To clear / reset a property to the default, call ConversationRef.deleteFields instead.
Your access to the conversation. Default = READ_WRITE access.
Custom metadata you have set on the conversation. This value acts as a patch. Remove specific properties by calling ConversationRef.deleteFields Default = no custom metadata
Your notification settings. Default = TRUE
The URL for the conversation photo to display in the chat header. Default = no photo, show a placeholder image.
The conversation subject to display in the chat header. Default = no subject, list participant names instead.
System messages which are sent at the beginning of a conversation. Default = no messages.
Returns
conversationRef.subscribe(onSnapshot): ConversationSubscription
Subscribes to the conversation.
Whenever Subscription.state.type is "active" and something about the conversation changes, onSnapshot will fire and Subscription.state.latestSnapshot will be updated. This includes changes to nested data. As an extreme example, onSnapshot would be called if snapshot.lastMessage.referencedMessage.sender.name changes.
The snapshot is null if you are not a participant in the conversation (including when the conversation doesn't exist)
Parameters
Returns
conversationRef.subscribeMessages(onSnapshot): MessageSubscription
Subscribes to the messages in the conversation.
Initially, you will be subscribed to the 10 most recent messages and any new messages. Call loadMore to load additional older messages.
Whenever a message is edited, a new message is received, or you load more messages, onSnapshot will fire and Subscription.latestSnapshot will be updated. loadedAll is true when the snapshot contains all the messages in the conversation.
The snapshot is null if you are not a participant in the conversation (including when the conversation doesn't exist)
Parameters
function called when the list of messages is updated
Returns
A subscription to messages.
conversationRef.subscribeParticipants(onSnapshot): ParticipantSubscription
Subscribes to the participants in the conversation.
While the subscription is active, onSnapshot will be called whenever the participant snapshots change. This includes when someone joins or leaves, when their participant attributes are edited, and when you load more participants. It also includes when nested data changes, such as when snapshot[0].user.name changes. loadedAll is true when snapshot contains all the participants in the conversation, and false if you could load more.
The snapshot list is ordered chronologically with the participants who joined most recently at the start. When someone joins the conversation, they will be added to the start of the list.
The snapshot is null if you are not a participant in the conversation (including when the conversation doesn't exist)
Initially, you will be subscribed to the 10 participants who joined most recently, and any new participants. Call loadMore to load additional older participants. This will trigger onSnapshot.
Remember to call .unsubscribe on the subscription once you are done with it.
Parameters
Returns
conversationRef.subscribeTyping(onSnapshot): TypingSubscription
Subscribes to the typing status of the conversation.
Whenever Subscription.state.type is "active" and the typing status changes, onSnapshot will fire and Subscription.state.latestSnapshot will be updated. This includes changes to nested data, such as when a user who is typing changes their name.
The snapshot is null if you are not a participant in the conversation (including when the conversation doesn't exist)
Note that if there are "many" people typing and another person starts to type, onSnapshot will not be called. This is because your existing ManyTypingSnapshot is still valid and did not change when the new person started to type.
Parameters
Returns
Parameters you can pass when sending a message
Custom metadata you have set on the user. Default = no custom metadata
The message that you are replying to. Default = not a reply
The text to send in the message.
Parameters you can pass to ConversationRef.send.
Properties that are null will be set to the default.
This is the more advanced method for editing a message, giving 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.
The most important part of the message, either some text, a file attachment, or a location.
By default users do not have permission to send LinkNode, ActionLinkNode, or ActionButtonNode, as they can be used to trick the recipient.
Custom metadata you have set on the user. Default = no custom metadata
The message that you are replying to. Default = not a reply
A snapshot of a conversation's attributes at a given moment in time.
Also includes information about the current user's view of that conversation, such as whether or not notifications are enabled.
The current user's permission level in this conversation.
The date that the conversation was created, as a unix timestamp in milliseconds.
Custom metadata you have set on the conversation
Everyone in the conversation has read any messages sent on or before this date.
This is the minimum of all the participants' readUntil values. Any messages sent on or before this timestamp should show a "read" indicator in the UI.
This value will rarely change in very large conversations. If just one person stops checking their messages, everyoneReadUntil will never update.
The ID of the conversation
Whether the conversation should be considered unread.
This can be true even when unreadMessageCount is zero, if the user has manually marked the conversation as unread.
The date that the current user joined the conversation, as a unix timestamp in milliseconds.
The last message sent in this conversation, or null if not messages have been sent.
The current user's notification settings for this conversation.
FALSE means no notifications, TRUE means notifications for all messages, and MENTIONS_ONLY means that the user will only be notified when they are mentioned with an @.
Contains the URL of a photo to represent the topic of the conversation or null if the conversation does not have a photo specified.
The most recent date that the current user read the conversation.
This value is updated whenever you read a message in a chat UI, open an email notification, or mark the conversation as read using an API like ConversationRef.markAsRead.
Any messages sent after this timestamp are unread messages.
Contains the conversation subject, or null if the conversation does not have a subject specified.
The number of messages in this conversation that the current user hasn't read.
One or more welcome messages that will be rendered at the start of this conversation as system messages.
Welcome messages are rendered in the UI as messages, but they are not real messages. This means they do not appear when you list messages using the REST API or JS/Kotlin Data API, and you cannot reply or react to them.
A subscription to a specific conversation.
Get a ConversationSubscription by calling ConversationRef.subscribe
Resolves when the subscription starts receiving updates from the server.
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 ConversationActiveState.
When type is "unsubscribed", the subclass type of this property is .
When type is "error", the subclass type of this property is .
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 from this resource and stop receiving updates.
If the subscription is already in the or , this is a no-op.
The state of a conversation subscription when it is actively listening for changes
The most recently received snapshot for the conversation, or null if you are not a participant in the conversation (including when the conversation does not exist).
A subscription to your most recently active conversations.
Get a ConversationListSubscription by calling .
The subscription is 'windowed'. Initially, this window contains the 20 most recent conversations. Conversations are ordered by last activity. The last activity of a conversation is either joinedAt or lastMessage.createdAt, whichever is higher.
The window will automatically expand to include any conversations you join, and any old conversations that receive new messages after subscribing.
You can expand this window by calling ConversationListSubscription.loadMore, which extends the window further into the past.
Remember to .unsubscribe the subscription once you are done with it.
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.
Expand the window to include older conversations
Calling loadMore multiple times in parallel will still only load one page of conversations.
Avoid calling .loadMore in a loop until you have loaded all conversations. This is usually unnecessary: any time a conversation receives a message, it appears at the start of the list of conversations. If you do need to call loadMore in a loop, make sure you set a small upper bound (e.g. 100) on the number of conversations, where the loop will exit.
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 ConversationListActiveState.
When type is "unsubscribed", the subclass type of this property is .
When type is "error", the subclass type of this property is .
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 from this resource and stop receiving updates.
If the subscription is already in the or , this is a no-op.
The state of a conversation list subscription when it is actively listening for changes
The most recently received snapshot for the conversations
True if latestSnapshot contains all conversations you are in. Use ConversationListSubscription.loadMore to load more.
A snapshot of the typing indicators in a conversation at a given moment in time.
Currently when there are 5 or less people typing in the conversation, many will be false and users will contain the users who are currently typing in this conversation. When more than 5 people are typing, many will be true and users will be null. This limit may change in the future, which will not be considered a breaking change.
Converting a TypingSnapshot to text
Check this to differentiate between few people are typing (false) and many people are typing (true).
When false, you can see the list of users who are typing in the users property.
The users who are currently typing in this conversation.
The list is in chronological order, starting with the users who have been typing the longest. The current user is never contained in the list, only other users. When the many property is true, this property is null.
A subscription to the typing status in a specific conversation
Get a TypingSubscription by calling ConversationRef.subscribeTyping.
When there are "many" people typing, the next update you receive will be once enough people stop typing. Until then, your TypingSnapshot is still valid and does not need to changed, so onSnapshot will not be called.
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.
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 TypingActiveState.
When type is "unsubscribed", the subclass type of this property is .
When type is "error", the subclass type of this property is .
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 from this resource and stop receiving updates.
If the subscription is already in the or , this is a no-op.
The state of a typing subscription when it is actively listening for changes
The most recently received typing indicator snapshot, or null if you are not a participant in the conversation (including when the conversation does not exist).
Values:
- READ
- READ_WRITE
Values:
- TRUE
- FALSE
- MENTIONS_ONLY