---
url: https://talkjs.com/docs/Data_APIs/Swift/Users/
title: "Users | 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.

# Users

Create, update, and subscribe to user data.

A user is someone who can send and receive messages. Usually, they will map directly to the accounts in your website or app. However, you can also create users to act as bots or for AI agents.

## struct UserRef

References the user with a given user ID.

### 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/Users/#UserRef__createIfNotExists" class="no-underline font-mono text-blue-500 hover:text-blue-600 font-medium">createIfNotExists</a></td><td><p>Creates a user with this ID, or does nothing if a user with this ID already exists.</p></td></tr><tr class="flex flex-col flex-no-wrap sm:table-row"><td><a href="https://talkjs.com/docs/Data_APIs/Swift/Users/#UserRef__deleteFields" class="no-underline font-mono text-blue-500 hover:text-blue-600 font-medium">deleteFields</a></td><td><p>Deletes properties of this user.</p></td></tr><tr class="flex flex-col flex-no-wrap sm:table-row"><td><a href="https://talkjs.com/docs/Data_APIs/Swift/Users/#UserRef__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 user.</p></td></tr><tr class="flex flex-col flex-no-wrap sm:table-row"><td><a href="https://talkjs.com/docs/Data_APIs/Swift/Users/#UserRef__set" class="no-underline font-mono text-blue-500 hover:text-blue-600 font-medium">set</a></td><td><p>Sets properties of this user. The user is created if a user with this ID doesn’t already exist.</p></td></tr><tr class="flex flex-col flex-no-wrap sm:table-row"><td><a href="https://talkjs.com/docs/Data_APIs/Swift/Users/#UserRef__subscribe" class="no-underline font-mono text-blue-500 hover:text-blue-600 font-medium">subscribe</a></td><td><p>Subscribe to this user’s state.</p></td></tr><tr class="flex flex-col flex-no-wrap sm:table-row"><td><a href="https://talkjs.com/docs/Data_APIs/Swift/Users/#UserRef__subscribeOnline" class="no-underline font-mono text-blue-500 hover:text-blue-600 font-medium">subscribeOnline</a></td><td><p>Subscribe to this user and their online status.</p></td></tr></tbody></table>

### Properties

**id**: String

The ID of the referenced user.

Immutable: if you want to reference a different user, get a new UserRef instead.

### createIfNotExists

func _userRef_.createIfNotExists(name:role:photoUrl:email:custom:locale:phone:pushTokens:welcomeMessage:) async

Creates a user with this ID, or does nothing if a user with this ID already exists.

If the user already exists, this operation is still considered successful.

#### Parameters

**name**: String

The user’s name which is displayed on the TalkJS UI

**role _(optional)_**: String?

TalkJS supports multiple sets of settings, called “roles”. These allow you to change the behavior of TalkJS for different users. You have full control over which user gets which configuration. Default = the `default` role

**photoUrl _(optional)_**: String?

An optional URL to a photo that is displayed as the user’s avatar. Default = no photo

**email _(optional)_**: \[String\]?

An array of email addresses associated with the user. Default = no email addresses

**custom _(optional)_**: \[String : String\]?

Custom metadata you have set on the user. Default = no custom metadata

**locale _(optional)_**: String?

An IETF language tag See the localization documentation Default = the locale selected on the dashboard

**phone _(optional)_**: \[String\]?

An array of phone numbers associated with the user. Default = no phone numbers

**pushTokens _(optional)_**: \[String : Bool\]?

A Dictionary of push registration tokens to use when notifying this user.

Keys in the Dictionary have the format `'provider:token_id'`, where `provider` is either `"fcm"` for Firebase Cloud Messaging or `"apns"` for Apple Push Notification Service

Default = no push registration tokens

(Value of the Dictionary is always true)

**welcomeMessage _(optional)_**: String?

The default message a person sees when starting a chat with this user. Default = no welcome message

This field is only used by the Classic SDK (including the Flutter and React Native SDKs), and not by the modern UI Components SDK. If you use the UI Components, see the Welcome Messages guide.

#### Returns

Void

### deleteFields

func _userRef_.deleteFields(\_:) async

Deletes properties of this user.

Pass the name of each property to delete as a separate parameter to this function. To delete a field in the `custom` property, pass it as `custom.FIELD_TO_DELETE`. To delete a field in the `pushTokens` property, pass it as `pushTokens.FIELD_TO_DELETE`.

#### Parameters

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

#### Returns

Void

### get

func _userRef_.get() async -> [UserSnapshot](https://talkjs.com/docs/Data_APIs/Swift/Users/#UserSnapshot)?

Fetches a snapshot of the user.

This contains all of a user’s public information. Fetching a user snapshot doesn’t require any permissions. You can read the public information of any user. Private information, such as email addresses and phone numbers, aren’t included in the response.

#### Returns

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

A snapshot of the user’s public attributes, or nil if the user doesn’t exist.

### set

func _userRef_.set(name:role:photoUrl:email:custom:locale:phone:pushTokens:welcomeMessage:) async

Sets properties of this user. The user is created if a user with this ID doesn’t already exist.

`name` is required when creating a user. The function will throw if you don’t provide a `name` and the user does not exist yet.

Properties that are `nil` will not be changed. To clear / reset a property to the default, call [UserRef.deleteFields](https://talkjs.com/docs/Data_APIs/Swift/Users/#UserRef__deleteFields) instead.

#### Parameters

**name**: String

The user’s name which will be displayed on the TalkJS UI

**role _(optional)_**: String?

TalkJS supports multiple sets of settings, called “roles”. These allow you to change the behaviour of TalkJS for different users. You have full control over which user gets which configuration. Default = the `default` role

**photoUrl _(optional)_**: String?

An optional URL to a photo which will be displayed as the user’s avatar. Default = no photo

**email _(optional)_**: \[String\]?

An array of email addresses associated with the user. Default = no email addresses

**custom _(optional)_**: \[String : String?\]?

Custom metadata you have set on the user. This value acts as a patch. Remove specific properties by calling [UserRef.deleteFields](https://talkjs.com/docs/Data_APIs/Swift/Users/#UserRef__deleteFields) Default = no custom metadata

**locale _(optional)_**: String?

An IETF language tag See the localization documentation Default = the locale selected on the dashboard

**phone _(optional)_**: \[String\]?

An array of phone numbers associated with the user. Default = no phone numbers

**pushTokens _(optional)_**: \[String : Bool?\]?

A Dictionary of push registration tokens to use when notifying this user.

Keys in the Dictionary have the format `'provider:token_id'`, where `provider` is either `"fcm"` for Firebase Cloud Messaging or `"apns"` for Apple Push Notification Service

The value for each key must be `true` to register the device for push notifications. To unregister that device call [UserRef.deleteFields](https://talkjs.com/docs/Data_APIs/Swift/Users/#UserRef__deleteFields)

Calling [UserRef.deleteFields](https://talkjs.com/docs/Data_APIs/Swift/Users/#UserRef__deleteFields) with the string `pushTokens` unregisters all the previously registered devices.

Default = no push tokens

**welcomeMessage _(optional)_**: String?

The default message a person sees when starting a chat with this user. Default = no welcome message

Note: User welcome messages are only supported by the Classic SDKs, and in the Components-based SDKs, this field is ignored. To show welcome messages in the Components-based SDK, see Welcome Messages.

#### Returns

Void

### subscribe

func _userRef_.subscribe(onSnapshot:) -> [UserSubscription](https://talkjs.com/docs/Data_APIs/Swift/Users/#UserSubscription)

Subscribe to this user’s state.

While the subscription is active, `onSnapshot` will be called when the user is created or the snapshot changes.

Remember to call `.unsubscribe` on the subscription once you are done with it.

#### Parameters

**onSnapshot _(optional)_**: (@Sendable (\_ snapshot: [UserSnapshot](https://talkjs.com/docs/Data_APIs/Swift/Users/#UserSnapshot)?) -> Void)?

#### Returns

[UserSubscription](https://talkjs.com/docs/Data_APIs/Swift/Users/#UserSubscription)

A subscription to the user

### subscribeOnline

func _userRef_.subscribeOnline(onSnapshot:) -> [UserOnlineSubscription](https://talkjs.com/docs/Data_APIs/Swift/Users/#UserOnlineSubscription)

Subscribe to this user and their online status.

While the subscription is active, `onSnapshot` will be called when the user is created or the snapshot changes (including changes to the nested UserSnapshot).

Remember to call `.unsubscribe` on the subscription once you are done with it.

#### Parameters

**onSnapshot _(optional)_**: (@Sendable (\_ snapshot: [UserOnlineSnapshot](https://talkjs.com/docs/Data_APIs/Swift/Users/#UserOnlineSnapshot)?) -> Void)?

#### Returns

[UserOnlineSubscription](https://talkjs.com/docs/Data_APIs/Swift/Users/#UserOnlineSubscription)

A subscription to the user’s online status

## struct UserSnapshot

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

### Properties

**custom**: \[String : String\]

Custom metadata you have set on the user

**id**: String

The unique ID that is used to identify the user in TalkJS

**locale _(optional)_**: String?

An IETF language tag For more information, see: localization

When `locale` is nil, the app’s default locale will be used

**name**: String

The user’s name, which is displayed on the TalkJS UI

**photoUrl _(optional)_**: String?

An optional URL to a photo that is displayed as the user’s avatar

**role**: String

TalkJS supports multiple sets of settings for users, called “roles”. Roles allow you to change the behavior of TalkJS for different users. You have full control over which user gets which configuration.

## struct UserSubscription

### 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/Users/#UserSubscription__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<[UserSubscriptionState](https://talkjs.com/docs/Data_APIs/Swift/Users/#UserSubscriptionState)\>

Resolves when the subscription starts receiving updates from the server.

**state**: [UserSubscriptionState](https://talkjs.com/docs/Data_APIs/Swift/Users/#UserSubscriptionState) { 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 UserSubscriptionState.pending.

When `type` is “active”, this property is UserSubscriptionState.active(latestSnapshot:).

When `type` is “unsubscribed”, this property is UserSubscriptionState.unsubscribed.

When `type` is “error”, this property is UserSubscriptionState.error(\_:).

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

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.

### unsubscribe

func _userSubscription_.unsubscribe()

Unsubscribe from this resource and stop receiving updates.

If the subscription is already in the UserSubscriptionState.unsubscribed or UserSubscriptionState.error(\_:) state, this is a no-op.

#### Returns

Void

## enum UserSubscriptionState

Values:

-   **pending**
-   **unsubscribed**
-   **active(latestSnapshot:)**
    
    The most recently received snapshot for the user, or `nil` if the user does not exist yet.
    
    **latestSnapshot _(optional)_**: [UserSnapshot](https://talkjs.com/docs/Data_APIs/Swift/Users/#UserSnapshot)?
    
-   **error(\_:)**
    
    The error that caused the subscription to be terminated
    
    **\_ _(unnamed)_**: TalkJSError
    

## struct UserOnlineSnapshot

A snapshot of a user’s online status at a given moment in time.

### Properties

**isConnected**: Bool

Whether the user is connected right now

Users are considered connected whenever they have an active websocket connection to the TalkJS servers. In practice, this means:

People using the JS Data API are considered connected if they are subscribed to something, or if they sent a request in the last few seconds. Creating a `TalkSession` is not enough to appear connected.

People using Components, are considered connected if they have a UI open.

People using the JavaScript SDK, React SDK, React Native SDK, or Flutter SDK are considered connected whenever they have an active `Session` object.

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

The user this snapshot relates to

## struct UserOnlineSubscription

A subscription to the online status of a user

### 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/Users/#UserOnlineSubscription__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<[UserOnlineSubscriptionState](https://talkjs.com/docs/Data_APIs/Swift/Users/#UserOnlineSubscriptionState)\>

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**: [UserOnlineSubscriptionState](https://talkjs.com/docs/Data_APIs/Swift/Users/#UserOnlineSubscriptionState) { 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 UserOnlineSubscriptionState.pending.

When `type` is “active”, this property is UserOnlineSubscriptionState.active(latestSnapshot:).

When `type` is “unsubscribed”, this property is UserOnlineSubscriptionState.unsubscribed.

When `type` is “error”, this property is UserOnlineSubscriptionState.error(\_:).

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

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.

### unsubscribe

func _userOnlineSubscription_.unsubscribe()

Unsubscribe from this resource and stop receiving updates.

If the subscription is already in the UserOnlineSubscriptionState.unsubscribed or UserOnlineSubscriptionState.error(\_:) state, this is a no-op.

#### Returns

Void

## enum UserOnlineSubscriptionState

Values:

-   **pending**
-   **unsubscribed**
-   **active(latestSnapshot:)**
    
    The most recently received snapshot
    
    **latestSnapshot _(optional)_**: [UserOnlineSnapshot](https://talkjs.com/docs/Data_APIs/Swift/Users/#UserOnlineSnapshot)?
    
-   **error(\_:)**
    
    The error that caused the subscription to be terminated
    
    **\_ _(unnamed)_**: TalkJSError