Participants
Get and manage a conversation's participants.
View as MarkdownA participant represents a user in a conversation. To add a user to a conversation you can create a participant, and you can delete a participant to kick them. You can track the participants of a conversation in real-time using ConversationRef.subscribeParticipants.
References a given user’s participation in a conversation.
| createIfNotExists | Adds the user as a participant, or does nothing if they are already a participant. |
| delete | Removes the user as a participant, or does nothing if they are already not a participant. |
| deleteFields | Deletes properties of this participant. |
| edit | Edits properties of a pre-existing participant. If the user is not already a participant in the conversation, the function will throw. |
| get | Fetches a snapshot of the participant. |
| set | Sets properties of this participant. If the user is not already a participant in the conversation, they will be added. |
The ID of the conversation the user is participating in.
Immutable: if you want to reference the user in a different conversation, get a new ParticipantRef instead.
The ID of the user who is participating.
Immutable: if you want to reference a different participant, get a new ParticipantRef instead.
func participantRef.createIfNotExists(access:notify:) async
Adds the user as a participant, or does nothing if they are already a participant.
If the participant already exists, this operation is still considered successful.
The function will throw if client-side conversation syncing is disabled and the user is not already a participant.
Parameters
The level of access the participant should have in the conversation. Default = .ReadWrite access.
When the participant should be notified about new messages in this conversation. Default = .True.
.False means no notifications, .True means notifications for all messages, and .MentionsOnly means that the user will only be notified when they are mentioned with an @.
Returns
func participantRef.delete() async
Removes the user as a participant, or does nothing if they are already not a participant.
Deleting a nonexistent participant is treated as success.
This function will throw if client-side conversation syncing is disabled.
Returns
func participantRef.edit(access:notify:) async
Edits properties of a pre-existing participant. If the user is not already a participant in the conversation, the function will throw.
When client-side conversation syncing is disabled, you must already be a participant and you cannot set anything except the notify property. 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 ParticipantRef.deleteFields instead.
Parameters
The level of access the participant should have in the conversation. Default = .ReadWrite access.
When the participant should be notified about new messages in this conversation. Default = .True.
.False means no notifications, .True means notifications for all messages, and .MentionsOnly means that the user will only be notified when they are mentioned with an @.
Returns
func participantRef.get() async -> ParticipantSnapshot?
Fetches a snapshot of the participant.
This contains all of the participant’s public information.
Returns
A snapshot of the participant’s attributes, or nil if the user is not a participant. The function will throw if you are not a participant and try to read information about someone else.
func participantRef.set(access:notify:) async
Sets properties of this participant. If the user is not already a participant in the conversation, they will be added.
When client-side conversation syncing is disabled, you must already be a participant and you cannot set anything except the notify property. 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 ParticipantRef.deleteFields instead.
Parameters
The level of access the participant should have in the conversation. Default = .ReadWrite access.
When the participant should be notified about new messages in this conversation. Default = .True.
.False means no notifications, .True means notifications for all messages, and .MentionsOnly means that the user will only be notified when they are mentioned with an @.
Returns
A snapshot of a participant’s attributes at a given moment in time.
The level of access this participant has in the conversation.
The date that this user joined the conversation, as a unix timestamp in milliseconds.
When the participant will be notified about new messages in this conversation.
.False means no notifications, .True means notifications for all messages, and .MentionsOnly means that the user will only be notified when they are mentioned with an @.
The user who this Participant Snapshot is referring to
A subscription to the participants in a specific conversation.
| loadMore | Expand the window to include older participants |
| 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 ParticipantSubscriptionState.pending.
When type is “active”, this property is ParticipantSubscriptionState.active(latestSnapshot:loadedAll:).
When type is “unsubscribed”, this property is ParticipantSubscriptionState.unsubscribed.
When type is “error”, this property is ParticipantSubscriptionState.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 participantSubscription.loadMore(count:) async
Expand the window to include older participants
Calling loadMore multiple times in parallel will still only load one page of participants.
Avoid calling .loadMore in a loop until you have loaded all participants. 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 participants, where the loop will exit.
Parameters
The number of additional participants to load. Must be between 1 and 50. Default 10.
Returns
func participantSubscription.unsubscribe()
Unsubscribe from this resource and stop receiving updates.
If the subscription is already in the ParticipantSubscriptionState.unsubscribed or ParticipantSubscriptionState.error(_:) state, this is a no-op.
Returns
Values:
latestSnapshot: The most recently received snapshot for the participants, ornilif you are not a participant in that conversation.loadedAll: True iflatestSnapshotcontains all participants in the conversation. Use ParticipantSubscription.loadMore to load more.: [ParticipantSnapshot]?The error that caused the subscription to be terminated