Participants
A participant is a resource that represents the relationship between a user and a conversation they are part of. The participant resource contains information about that user's activity in that conversation, such as whether they should receive notifications. By creating a participant representing a specific user and conversation, we are adding that user to the conversation.
References a given user's participation in a conversation.
Used in all Data API operations affecting that participant, such as joining/leaving a conversation, or setting their access. Created via ConversationRef.participant.
| 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. |
| edit | Edits properties of a pre-existing participant. If the user is not already a participant in the conversation, the promise will reject. |
| 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.
participantRef.createIfNotExists(params): Promise<void>
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 and the promise will still resolve.
Supports Automatic Batching
Parameters
interface CreateParticipantParams
Parameters you can pass to ParticipantRef.createIfNotExists.
Properties that are undefined will be set to the default.
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 promise that resolves when the operation completes. The promise will reject if client-side conversation syncing is disabled and the user is not already a participant.
participantRef.delete(): Promise<void>
Removes the user as a participant, or does nothing if they are already not a participant.
Deleting a nonexistent participant is treated as success, and the promise will resolve.
Returns
A promise that resolves when the operation completes. This promise will reject if client-side conversation syncing is disabled.
participantRef.edit(params): Promise<void>
Edits properties of a pre-existing participant. If the user is not already a participant in the conversation, the promise will reject.
Supports Automatic Batching
Parameters
interface SetParticipantParams
Parameters you can pass to ParticipantRef.set or ParticipantRef.edit.
Properties that are undefined will not be changed. To clear / reset a property to the default, pass null.
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 = ReadWrite access.
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 promise that resolves when the operation completes. 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 promise to reject.
participantRef.get(): Promise<ParticipantSnapshot | null>
Fetches a snapshot of the participant.
This contains all of the participant's public information.
Returns
A snapshot of the participant's attributes, or null if the user is not a participant. The promise will reject if you are not a participant and try to read information about someone else.
participantRef.set(params): Promise<void>
Sets properties of this participant. If the user is not already a participant in the conversation, they will be added.
Supports Automatic Batching
Parameters
interface SetParticipantParams
Parameters you can pass to ParticipantRef.set or ParticipantRef.edit.
Properties that are undefined will not be changed. To clear / reset a property to the default, pass null.
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 = ReadWrite access.
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 promise that resolves when the operation completes. 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 promise to reject.
A snapshot of a participant's attributes at a given moment in time.
Automatically expanded to include a snapshot of the user who is a participant.
Snapshots are immutable and we try to reuse them when possible. You should only re-render your UI when oldSnapshot !== newSnapshot.
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.
Get a ParticipantSubscription by calling ConversationRef.subscribeParticipants
The subscription is 'windowed'. It includes everyone who joined since a certain point in time. By default, you subscribe to the 10 most recent participants, and any participants who joined after you subscribe.
You can expand this window by calling loadMore, which extends the window further into the past.
| 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 object with the following fields:
type is one of "pending", "active", "unsubscribed", or "error".
When type is "active", includes latestSnapshot and loadedAll.
- latestSnapshot: ParticipantSnapshot[] | null the current state of the participants in the window, or null if you're not a participant in the conversation
- loadedAll: boolean true when latestSnapshot contains all the participants in the conversation
When type is "error", includes the error field. It is a JS Error object explaining what caused the subscription to be terminated.
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.
participantSubscription.loadMore(count): Promise<void>
Expand the window to include older participants
Calling loadMore multiple times in parallel will still only load one page of participants.
Parameters
The number of additional participants to load. Must be between 1 and 50. Default 10.
Returns
A promise that resolves once the additional participants have loaded
participantSubscription.unsubscribe()
Unsubscribe from this resource and stop receiving updates.
If the subscription is already in the "unsubscribed" or "error" state, this is a no-op.