Users
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.
References the user with a given user ID.
Used in all Data API operations affecting that user, such as creating the user, fetching or updating user data, or adding a user to a conversation. Created via .
| 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.
userRef.createIfNotExists(data): Unit
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
data class CreateUserParams
Parameters you can pass when creating a user.
Custom metadata you have set on the user. Default = no custom metadata
An array of email addresses associated with the user. Default = no email addresses
An IETF language tag See the localization documentation Default = the locale selected on the dashboard
The user's name which is displayed on the TalkJS UI
An array of phone numbers associated with the user. Default = no phone numbers
An optional URL to a photo that is displayed as the user's avatar. Default = no photo
A Map of push registration tokens to use when notifying this user.
Keys in the Map 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 Map is always true)
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
The default message a person sees when starting a chat with this user. Default = no welcome message
Returns
userRef.deleteFields(vararg fields): Unit
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
Returns
userRef.get(): 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 null if the user doesn't exist.
userRef.set(data): Unit
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.
Parameters
data class SetUserParams
Parameters you can pass when updating a user.
Properties that are null will not be changed. To clear / reset a property to the default, call UserRef.deleteFields instead.
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 array of email addresses associated with the user. Default = no email addresses
An IETF language tag See the localization documentation Default = the locale selected on the dashboard
The user's name which will be displayed on the TalkJS UI
An array of phone numbers associated with the user. Default = no phone numbers
An optional URL to a photo which will be displayed as the user's avatar. Default = no photo
A Map of push registration tokens to use when notifying this user.
Keys in the Map 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
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
The default message a person sees when starting a chat with this user. Default = no welcome message
Returns
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
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.
Users also have private information, such as email addresses and phone numbers, but these are only exposed on the REST API
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 null, 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.
The default message a person sees when starting a chat with this user
Resolves when the subscription starts receiving updates from the server.
The current state of the subscription
An object with the following fields:
type is one of "pending", "active", "unsubscribed", or "error".
When type is "pending", the subclass type of this property is .
When type is "active", the subclass type of this property is UserActiveState.
When type is "unsubscribed", the subclass type of this property is .
When type is "error", the subclass type of this property is .
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 from this resource and stop receiving updates.
If the subscription is already in the or , this is a no-op.
The most recently received snapshot for the user, or null if the user does not exist yet.
A snapshot of a user's online status at a given moment in time.
Snapshots are immutable and we try to reuse them when possible. You should only re-render your UI when oldSnapshot != newSnapshot.
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
Get a UserOnlineSubscription by calling UserRef.subscribeOnline.
Remember to .unsubscribe the subscription once you are done with it.
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 "pending", the subclass type of this property is .
When type is "active", the subclass type of this property is UserOnlineActiveState.
When type is "unsubscribed", the subclass type of this property is .
When type is "error", the subclass type of this property is .
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 from this resource and stop receiving updates.
If the subscription is already in the or , this is a no-op.
The state of a user online subscription when it is actively listening for changes
The most recently received snapshot