Conversations
Get and manage conversation data.
View as MarkdownA 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 text 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.
func conversationRef.createIfNotExists(access:custom:notify:photoUrl:subject:welcomeMessages:) async
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
Your access to the conversation. Default = .ReadWrite 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
func conversationRef.get() async -> 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 nil if the current user is not a participant (including if the conversation doesn’t exist)
func conversationRef.markAsRead() async
Marks the conversation as read.
The function throws if you are not a participant in the conversation.
Returns
func conversationRef.markAsTyping() async
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
func conversationRef.markAsUnread() async
Marks the conversation as unread.
The function throws if you are not a participant in the conversation.
Returns
func conversationRef.message(id:) -> MessageRef
Get a reference to a message in this conversation
Returns
A reference to the message with the given ID
func conversationRef.participant(user:) -> ParticipantRef
Get a reference to a participant in this conversation
Returns
A reference to the given participant
func conversationRef.send(text:referencedMessage:custom:) async -> MessageReffunc conversationRef.send(content:referencedMessage:custom:) async -> MessageRef
Sends a text message in the conversation.
Parameters
The text to send in the message.
The message that you are replying to. Default = not a reply
Custom metadata you have set on the message. Default = no custom metadata
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 Link, ActionLink, or ActionButton, as they can be used to trick the recipient.
Returns
A reference to the newly created message. The function throws if you are not a participant with write access in this conversation.
func conversationRef.set(subject:photoUrl:welcomeMessages:custom:access:notify:) async
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.
Properties that are nil will not be changed. To clear / reset a property to the default, call ConversationRef.deleteFields instead.
Parameters
The conversation subject to display in the chat header. Default = no subject, list participant names instead.
The URL for the conversation photo to display in the chat header. Default = no photo, show a placeholder image.
System messages which are sent at the beginning of a conversation. Default = no messages.
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 access to the conversation. Default = .ReadWrite access.
Your notification settings. Default = .True
Returns
func 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 nil if you are not a participant in the conversation (including when the conversation doesn’t exist)
Parameters
Returns
func 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 nil 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.
func 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 nil 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
func 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 nil 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 TypingSnapshot (with many set to true) is still valid and did not change when the new person started to type.
Parameters
Returns
A snapshot of a conversation’s attributes at a given moment in time.
The date that the conversation was created, as a unix timestamp in milliseconds.
Custom metadata you have set on the conversation
The ID of the conversation
The date that the current user joined the conversation, as a unix timestamp in milliseconds.
Contains the URL of a photo to represent the topic of the conversation or nil if the conversation does not have a photo specified.
Contains the conversation subject, or nil if the conversation does not have a subject specified.
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/Swift Data API, and you cannot reply or react to them.
A subscription to a specific conversation.
| unsubscribe | Unsubscribe from this resource and stop receiving updates. |
Resolves when the subscription starts receiving updates from the server.
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 ConversationSubscriptionState.pending.
When type is “active”, this property is ConversationSubscriptionState.active(latestSnapshot:).
When type is “unsubscribed”, this property is ConversationSubscriptionState.unsubscribed.
When type is “error”, this property is ConversationSubscriptionState.error(_:).
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.
func conversationSubscription.unsubscribe()
Unsubscribe from this resource and stop receiving updates.
If the subscription is already in the ConversationSubscriptionState.unsubscribed or ConversationSubscriptionState.error(_:) state, this is a no-op.
Returns
Values:
The most recently received snapshot for the conversation, or
nilif you are not a participant in the conversation (including when the conversation does not exist).The error that caused the subscription to be terminated
A subscription to your most recently active conversations.
| loadMore | Expand the window to include older conversations |
| unsubscribe | Unsubscribe from this resource and stop receiving updates. |
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 enum with the following fields:
type is one of “pending”, “active”, “unsubscribed”, or “error”.
When type is “pending”, this property is ConversationListSubscriptionState.pending.
When type is “active”, this property is ConversationListSubscriptionState.active(latestSnapshot:loadedAll:).
When type is “unsubscribed”, this property is ConversationListSubscriptionState.unsubscribed.
When type is “error”, this property is ConversationListSubscriptionState.error(_:).
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.
func conversationListSubscription.loadMore(count:) async
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.
Parameters
The number of additional conversations to load. Must be between 1 and 30. Default 20.
Returns
func conversationListSubscription.unsubscribe()
Unsubscribe from this resource and stop receiving updates.
If the subscription is already in the ConversationListSubscriptionState.unsubscribed or ConversationListSubscriptionState.error(_:) state, this is a no-op.
Returns
Values:
latestSnapshot: The most recently received snapshot for the conversationsloadedAll: True iflatestSnapshotcontains all conversations you are in. Use ConversationListSubscription.loadMore to load more.The error that caused the subscription to be terminated
A snapshot of the typing indicators in a conversation at a given moment in time.
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 nil.
A subscription to the typing status in a specific conversation
| unsubscribe | Unsubscribe from this resource and stop receiving updates. |
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 enum with the following fields:
type is one of “pending”, “active”, “unsubscribed”, or “error”.
When type is “pending”, this property is TypingSubscriptionState.pending.
When type is “active”, this property is TypingSubscriptionState.active(latestSnapshot:).
When type is “unsubscribed”, this property is TypingSubscriptionState.unsubscribed.
When type is “error”, this property is TypingSubscriptionState.error(_:).
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.
func typingSubscription.unsubscribe()
Unsubscribe from this resource and stop receiving updates.
If the subscription is already in the TypingSubscriptionState.unsubscribed or TypingSubscriptionState.error(_:) state, this is a no-op.
Returns
Values:
The most recently received typing indicator snapshot, or
nilif you are not a participant in the conversation (including when the conversation does not exist).The error that caused the subscription to be terminated
Values:
Values: