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 Session.user.
| createIfNotExists | Creates a user with this ID, or does nothing if a user with this ID already exists. |
| 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. |
The ID of the referenced user.
Immutable: if you want to reference a different user, get a new UserRef instead.
userRef.createIfNotExists(params): Promise<void>
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 and the promise will still resolve.
Parameters
interface CreateUserParams
Parameters you can pass to UserRef.createIfNotExists.
Properties that are undefined will be set to the default.
The user's name which is displayed on the TalkJS UI
Custom metadata you have set on the user. Default = no custom metadata
A single email address or 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
A single phone number or 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
An object of push registration tokens to use when notifying this user.
Keys in the object have the format 'provider:token_id', where provider is either "fcm" for Android (Firebase Cloud Messaging), or "apns" for iOS (Apple Push Notification Service).
Default = no push registration tokens
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
A promise that resolves when the operation completes. The promise will reject if client-side user syncing is disabled and the user does not already exist.
userRef.get(): Promise<UserSnapshot | null>
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.
Supports Automatic Batching and Cached Fetch
Returns
A snapshot of the user's public attributes, or null if the user doesn't exist.
userRef.set(params): Promise<void>
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 promise will reject if you don't provide a name and the user does not exist yet.
Parameters
interface SetUserParams
Parameters you can pass to UserRef.set.
Properties that are undefined will not be changed. To clear / reset a property to the default, pass null.
Custom metadata you have set on the user. This value acts as a patch. Remove specific properties by setting them to null. Default = no custom metadata
A single email address or 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
A single phone number or 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
An object of push registration tokens to use when notifying this user.
Keys in the object have the format 'provider:token_id', where provider is either "fcm" for Android (Firebase Cloud Messaging), or "apns" for iOS (Apple Push Notification Service).
The value for each key can either be true to register the device for push notifications, or null to unregister that device.
Setting pushTokens to null unregisters all the previously registered devices.
Default = no push tokens
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
A promise that resolves when the operation completes. The promise will reject if the request is invalid or if client-side user syncing is disabled.
userRef.subscribe(onSnapshot): UserSubscription
Subscribe to this user's state.
Whenever Subscription.state.type is "active" and the user is created or their attributes change, onSnapshot will fire and Subscription.state.latestSnapshot will be updated.
Parameters
Returns
A subscription to the user
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.
Snapshots are immutable and we try to reuse them when possible. You should only re-render your UI when oldSnapshot !== newSnapshot.
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
A subscription to a specific user
Get a UserSubscription by calling UserRef.subscribe
| 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 object with the following fields:
type is one of "pending", "active", "unsubscribed", or "error".
When type is "active", includes latestSnapshot: UserSnapshot | null. It is the current state of the user, or null if they don't exist.
When type is "error", includes the error: Error field. It is a JS Error object explaining what caused the subscription to be terminated.
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.
userSubscription.unsubscribe()
Unsubscribe from this resource and stop receiving updates.
If the subscription is already in the "unsubscribed" or "error" state, this is a no-op.