--- url: https://talkjs.com/docs/Data_APIs/JavaScript/Participants title: 'Participants' minidoc-source: js minidoc-lib: data-api --- A participant represents a user in a conversation. To add a user to a conversation you can [create a participant](/JavaScript_Data_API/Participants/#ParticipantRef__createIfNotExists), and you can [delete a participant](/JavaScript_Data_API/Participants/#ParticipantRef__delete) to kick them. You can track the participants of a conversation in real-time using [ConversationRef.subscribeParticipants](/JavaScript_Data_API/Conversations/#ConversationRef__subscribeParticipants). ## ParticipantRef /** 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. */ export interface ParticipantRef { /** 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. */ readonly conversationId: string; /** 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. @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. */ createIfNotExists(params?: CreateParticipantParams): Promise; /** 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. */ delete(): Promise; /** Edits properties of a pre-existing participant. If the user is not already a participant in the conversation, the promise will reject. @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. */ edit(params: SetParticipantParams): Promise; /** 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. */ get(): Promise; /** Sets properties of this participant. If the user is not already a participant in the conversation, they will be added. @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. */ set(params: SetParticipantParams): Promise; /** Subscribe to this participant's state. While the subscription is active, `onSnapshot` will be called when the participant joins or leaves the conversation, or their attributes change, including attributes on their user. Remember to call `.unsubscribe` on the subscription once you are done with it. @returns A subscription to the participant */ subscribe(onSnapshot?: (snapshot: ParticipantSnapshot|null)=>void): SingleParticipantSubscription; /** The ID of the user who is participating. Immutable: if you want to reference a different participant, get a new ParticipantRef instead. */ readonly userId: string; } ## CreateParticipantParams /** Parameters you can pass to ParticipantRef.createIfNotExists. Properties that are `undefined` will be set to the default. */ export interface CreateParticipantParams { /** The level of access the participant should have in the conversation. Default = "ReadWrite" access. */ access?: "ReadWrite"|"Read"; /** 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 `@`. */ notify?: boolean|"MentionsOnly"; } ## 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`. */ export interface SetParticipantParams { /** The level of access the participant should have in the conversation. Default = "ReadWrite" access. */ access?: "ReadWrite"|"Read"|null; /** 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 `@`. */ notify?: boolean|"MentionsOnly"|null; } ## ParticipantSnapshot /** 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`. */ export interface ParticipantSnapshot { /** The level of access this participant has in the conversation. */ readonly access: "ReadWrite"|"Read"; /** The date that this user joined the conversation, as a unix timestamp in milliseconds. */ readonly joinedAt: number; /** 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 `@`. */ readonly notify: boolean|"MentionsOnly"; /** The user who this participant snapshot is referring to */ readonly user: UserSnapshot; } ## ParticipantSubscription /** 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 ParticipantSubscription.loadMore, which extends the window further into the past. Do not call `.loadMore` in a loop until you have loaded all participants, unless you know that the maximum number of participants is small (under 100). Remember to `.unsubscribe` the subscription once you are done with it. */ export interface ParticipantSubscription { /** 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. */ readonly connected: Promise; /** Expand the window to include older participants The `count` parameter is relative to the current number of loaded participants. If you call `loadMore(5)` and then call `loadMore(10)` immediately afterwards (without awaiting the promise), then only 10 additional participants will be loaded, not 15. 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. @param count - 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 */ loadMore(count?: number): Promise; /** 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. */ state: PendingState|ParticipantActiveState|UnsubscribedState|ErrorState; /** 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. */ readonly terminated: Promise; /** Unsubscribe from this resource and stop receiving updates. If the subscription is already in the "unsubscribed" or "error" state, this is a no-op. */ unsubscribe(): void; }