Users
Create, update, and subscribe to user data.
View as MarkdownA 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.
References the user with a given user ID.
| createIfNotExists | Creates a user with this ID, or does nothing if a user with this ID already exists. |
| deleteFields | Deletes properties of this user. |
| get | Fetches a snapshot of the user. |
| set | Sets properties of this user. The user is created if a user with this ID doesn’t already exist. |
| subscribe | Subscribe to this user’s state. |
| subscribeOnline | Subscribe to this user and their online status. |
The ID of the referenced user.
Immutable: if you want to reference a different user, get a new UserRef instead.
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
The user’s name which is displayed on the TalkJS UI
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
An optional URL to a photo that is displayed as the user’s avatar. Default = no photo
An array of email addresses associated with the user. Default = no email addresses
Custom metadata you have set on the user. Default = no custom metadata
An IETF language tag See the localization documentation Default = the locale selected on the dashboard
An array of phone numbers associated with the user. Default = no phone numbers
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)
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
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.
Returns
func userRef.get() async -> 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
A snapshot of the user’s public attributes, or nil if the user doesn’t exist.
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 instead.
Parameters
The user’s name which will be displayed on the TalkJS UI
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
An optional URL to a photo which will be displayed as the user’s avatar. Default = no photo
An array of email addresses associated with the user. Default = no email addresses
Custom metadata you have set on the user. This value acts as a patch. Remove specific properties by calling UserRef.deleteFields Default = no custom metadata
An IETF language tag See the localization documentation Default = the locale selected on the dashboard
An array of phone numbers associated with the user. Default = no phone numbers
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
Calling UserRef.deleteFields with the string pushTokens unregisters all the previously registered devices.
Default = no push tokens
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
func userRef.subscribe(onSnapshot:) -> 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
Returns
A subscription to the user
func userRef.subscribeOnline(onSnapshot:) -> 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
Returns
A subscription to the user’s online status
A snapshot of a user’s attributes at a given moment in time.
Custom metadata you have set on the user
The unique ID that is used to identify the user in TalkJS
An IETF language tag For more information, see: localization
When locale is nil, the app’s default locale will be used
The user’s name, which is displayed on the TalkJS UI
An optional URL to a photo that is displayed as the user’s avatar
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.
| unsubscribe | Unsubscribe from this resource and stop receiving updates. |
Resolves when the subscription starts receiving updates from the server.
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(_:).
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 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
Values:
The most recently received snapshot for the user, or
nilif the user does not exist yet.: UserSnapshot?The error that caused the subscription to be terminated
A snapshot of a user’s online status at a given moment in time.
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.
The user this snapshot relates to
A subscription to the online status of a user
| 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 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(_:).
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 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
Values:
The most recently received snapshot
The error that caused the subscription to be terminated