---
url: https://talkjs.com/docs/Data_APIs/Swift/Participants/
title: "Participants | Swift | TalkJS Documentation"
---

For AI agents: Find a documentation index at https://talkjs.com/llms.txt (full content at https://talkjs.com/llms-full.txt). Get a markdown version of any page by appending .md to its URL path.

# Participants

Get and manage a conversation's participants.

A participant represents a user in a conversation. To add a user to a conversation you can [create a participant](https://talkjs.com/docs/Swift_Data_API/Participants/#ParticipantRef__createIfNotExists), and you can [delete a participant](https://talkjs.com/docs/Swift_Data_API/Participants/#ParticipantRef__delete) to kick them. You can track the participants of a conversation in real-time using [ConversationRef.subscribeParticipants](https://talkjs.com/docs/Swift_Data_API/Conversations/#ConversationRef__subscribeParticipants).

## struct ParticipantRef

References a given user’s participation in a conversation.

### Method Overview

<table class="my-0"><tbody><tr class="flex flex-col flex-no-wrap sm:table-row"><td><a href="https://talkjs.com/docs/Data_APIs/Swift/Participants/#ParticipantRef__createIfNotExists" class="no-underline font-mono text-blue-500 hover:text-blue-600 font-medium">createIfNotExists</a></td><td><p>Adds the user as a participant, or does nothing if they are already a participant.</p></td></tr><tr class="flex flex-col flex-no-wrap sm:table-row"><td><a href="https://talkjs.com/docs/Data_APIs/Swift/Participants/#ParticipantRef__delete" class="no-underline font-mono text-blue-500 hover:text-blue-600 font-medium">delete</a></td><td><p>Removes the user as a participant, or does nothing if they are already not a participant.</p></td></tr><tr class="flex flex-col flex-no-wrap sm:table-row"><td><a href="https://talkjs.com/docs/Data_APIs/Swift/Participants/#ParticipantRef__deleteFields" class="no-underline font-mono text-blue-500 hover:text-blue-600 font-medium">deleteFields</a></td><td><p>Deletes properties of this participant.</p></td></tr><tr class="flex flex-col flex-no-wrap sm:table-row"><td><a href="https://talkjs.com/docs/Data_APIs/Swift/Participants/#ParticipantRef__edit" class="no-underline font-mono text-blue-500 hover:text-blue-600 font-medium">edit</a></td><td><p>Edits properties of a pre-existing participant. If the user is not already a participant in the conversation, the function will throw.</p></td></tr><tr class="flex flex-col flex-no-wrap sm:table-row"><td><a href="https://talkjs.com/docs/Data_APIs/Swift/Participants/#ParticipantRef__get" class="no-underline font-mono text-blue-500 hover:text-blue-600 font-medium">get</a></td><td><p>Fetches a snapshot of the participant.</p></td></tr><tr class="flex flex-col flex-no-wrap sm:table-row"><td><a href="https://talkjs.com/docs/Data_APIs/Swift/Participants/#ParticipantRef__set" class="no-underline font-mono text-blue-500 hover:text-blue-600 font-medium">set</a></td><td><p>Sets properties of this participant. If the user is not already a participant in the conversation, they will be added.</p></td></tr></tbody></table>

### Properties

**conversationId**: String

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.

**userId**: String

The ID of the user who is participating.

Immutable: if you want to reference a different participant, get a new ParticipantRef instead.

### createIfNotExists

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

**access _(optional)_**: [ConversationAccess](https://talkjs.com/docs/Data_APIs/Swift/Conversations/#ConversationAccess)?

The level of access the participant should have in the conversation. Default = `.ReadWrite` access.

**notify _(optional)_**: [NotificationSettings](https://talkjs.com/docs/Data_APIs/Swift/Conversations/#NotificationSettings)?

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

Void

### delete

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

Void

### deleteFields

func _participantRef_.deleteFields(\_:) async

Deletes properties of this participant.

Pass the name of each property to delete as a separate parameter to this function.

#### Parameters

**fields _(unnamed)_**: String...

#### Returns

Void

### edit

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](https://talkjs.com/docs/Data_APIs/Swift/Participants/#ParticipantRef__deleteFields) instead.

#### Parameters

**access _(optional)_**: [ConversationAccess](https://talkjs.com/docs/Data_APIs/Swift/Conversations/#ConversationAccess)?

The level of access the participant should have in the conversation. Default = `.ReadWrite` access.

**notify _(optional)_**: [NotificationSettings](https://talkjs.com/docs/Data_APIs/Swift/Conversations/#NotificationSettings)?

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

Void

### get

func _participantRef_.get() async -> [ParticipantSnapshot](https://talkjs.com/docs/Data_APIs/Swift/Participants/#ParticipantSnapshot)?

Fetches a snapshot of the participant.

This contains all of the participant’s public information.

#### Returns

[ParticipantSnapshot](https://talkjs.com/docs/Data_APIs/Swift/Participants/#ParticipantSnapshot)?

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.

### set

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](https://talkjs.com/docs/Data_APIs/Swift/Participants/#ParticipantRef__deleteFields) instead.

#### Parameters

**access _(optional)_**: [ConversationAccess](https://talkjs.com/docs/Data_APIs/Swift/Conversations/#ConversationAccess)?

The level of access the participant should have in the conversation. Default = `.ReadWrite` access.

**notify _(optional)_**: [NotificationSettings](https://talkjs.com/docs/Data_APIs/Swift/Conversations/#NotificationSettings)?

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

Void

## struct ParticipantSnapshot

A snapshot of a participant’s attributes at a given moment in time.

### Properties

**access**: [ConversationAccess](https://talkjs.com/docs/Data_APIs/Swift/Conversations/#ConversationAccess)

The level of access this participant has in the conversation.

**joinedAt**: Int64

The date that this user joined the conversation, as a unix timestamp in milliseconds.

**notify**: [NotificationSettings](https://talkjs.com/docs/Data_APIs/Swift/Conversations/#NotificationSettings)

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 `@`.

**user**: [UserSnapshot](https://talkjs.com/docs/Data_APIs/Swift/Users/#UserSnapshot)

The user who this Participant Snapshot is referring to

## struct ParticipantSubscription

A subscription to the participants in a specific conversation.

### Method Overview

<table class="my-0"><tbody><tr class="flex flex-col flex-no-wrap sm:table-row"><td><a href="https://talkjs.com/docs/Data_APIs/Swift/Participants/#ParticipantSubscription__loadMore" class="no-underline font-mono text-blue-500 hover:text-blue-600 font-medium">loadMore</a></td><td><p>Expand the window to include older participants</p></td></tr><tr class="flex flex-col flex-no-wrap sm:table-row"><td><a href="https://talkjs.com/docs/Data_APIs/Swift/Participants/#ParticipantSubscription__unsubscribe" class="no-underline font-mono text-blue-500 hover:text-blue-600 font-medium">unsubscribe</a></td><td><p>Unsubscribe from this resource and stop receiving updates.</p></td></tr></tbody></table>

### Properties

**connected**: Deferred<[ParticipantSubscriptionState](https://talkjs.com/docs/Data_APIs/Swift/Participants/#ParticipantSubscriptionState)\>

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.

**state**: [ParticipantSubscriptionState](https://talkjs.com/docs/Data_APIs/Swift/Participants/#ParticipantSubscriptionState) { get }

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(\_:).

**terminated**: Deferred<[ParticipantSubscriptionState](https://talkjs.com/docs/Data_APIs/Swift/Participants/#ParticipantSubscriptionState)\>

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.

### loadMore

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

**count _(optional)_**: Int?

The number of additional participants to load. Must be between 1 and 50. Default 10.

#### Returns

Void

### unsubscribe

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

Void

## enum ParticipantSubscriptionState

Values:

-   **pending**
-   **unsubscribed**
-   **active(latestSnapshot:loadedAll:)**
    
    `latestSnapshot`: The most recently received snapshot for the participants, or `nil` if you are not a participant in that conversation.
    
    `loadedAll`: True if `latestSnapshot` contains all participants in the conversation. Use [ParticipantSubscription.loadMore](https://talkjs.com/docs/Data_APIs/Swift/Participants/#ParticipantSubscription__loadMore) to load more.
    
    **latestSnapshot _(optional)_**: \[[ParticipantSnapshot](https://talkjs.com/docs/Data_APIs/Swift/Participants/#ParticipantSnapshot)\]?
    
    **loadedAll**: Bool
    
-   **error(\_:)**
    
    The error that caused the subscription to be terminated
    
    **\_ _(unnamed)_**: TalkJSError