--- url: https://talkjs.com/docs/Data_APIs/JavaScript/Users title: 'Users' minidoc-source: js minidoc-lib: data-api --- 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. ## UserRef /** 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. */ export interface UserRef { /** 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. @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. */ createIfNotExists(params: CreateUserParams): Promise; /** 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. */ get(): Promise; /** The ID of the referenced user. Immutable: if you want to reference a different user, get a new UserRef instead. */ readonly id: string; /** 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. @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. */ set(params: SetUserParams): Promise; /** 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. @returns A subscription to the user */ subscribe(onSnapshot?: (event: UserSnapshot|null)=>void): UserSubscription; /** 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. @returns A subscription to the user's online status */ subscribeOnline(onSnapshot?: (event: UserOnlineSnapshot|null)=>void): UserOnlineSubscription; } ## CreateUserParams /** Parameters you can pass to UserRef.createIfNotExists. Properties that are `undefined` will be set to the default. */ export interface CreateUserParams { /** Custom metadata you have set on the user. Default = no custom metadata */ custom?: Record; /** A single email address or an array of email addresses associated with the user. Default = no email addresses */ email?: string|string[]; /** An IETF language tag. See the localization documentation Default = null, will use the locale set on the dashboard */ locale?: string; /** The user's name which is displayed on the TalkJS UI */ name: string; /** A single phone number or an array of phone numbers associated with the user. Default = no phone numbers */ phone?: string|string[]; /** An optional URL to a photo that is displayed as the user's avatar. Default = no photo */ photoUrl?: string; /** 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 */ pushTokens?: Record; /** 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 */ role?: string; /** The default message a person sees when starting a chat with this user. Default = no welcome message Welcome messages are rendered in the UI as messages, but they are not real messages. This means they do not appear when you list messages using the REST API or JS Data API, and you cannot reply or react to them. 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. */ welcomeMessage?: string; } ## 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`. */ export interface SetUserParams { /** 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 */ custom?: Record|null; /** A single email address or an array of email addresses associated with the user. Default = no email addresses */ email?: string|string[]|null; /** An IETF language tag. See the localization documentation Default = null, will use the locale set on the dashboard */ locale?: string|null; /** The user's name which will be displayed on the TalkJS UI */ name?: string; /** A single phone number or an array of phone numbers associated with the user. Default = no phone numbers */ phone?: string|string[]|null; /** An optional URL to a photo which will be displayed as the user's avatar. Default = no photo */ photoUrl?: string|null; /** 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 */ pushTokens?: Record|null; /** 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 */ role?: string|null; /** The default message a person sees when starting a chat with this user. Default = no welcome message Welcome messages are rendered in the UI as messages, but they are not real messages. This means they do not appear when you list messages using the REST API or JS Data API, and you cannot reply or react to them. 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. */ welcomeMessage?: string|null; } ## UserSnapshot /** 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`. */ export interface UserSnapshot { /** Custom metadata you have set on the user */ readonly custom: Record; /** The unique ID that is used to identify the user in TalkJS */ readonly id: string; /** An IETF language tag. For more information, see: Localization. When `locale` is null, the app's default locale will be used */ readonly locale: string|null; /** The user's name, which is displayed on the TalkJS UI */ readonly name: string; /** An optional URL to a photo that is displayed as the user's avatar */ readonly photoUrl: string|null; /** 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. */ readonly role: string; /** The default message a person sees when starting a chat with this user Welcome messages are rendered in the UI as messages, but they are not real messages. This means they do not appear when you list messages using the REST API or JS Data API, and you cannot reply or react to them. 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. */ readonly welcomeMessage: string|null; } ## UserSubscription /** A subscription to a specific user Get a UserSubscription by calling UserRef.subscribe Remember to `.unsubscribe` the subscription once you are done with it. */ export interface UserSubscription { /** Resolves when the subscription starts receiving updates from the server. */ readonly connected: Promise; /** 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. */ state: PendingState|UserActiveState|UnsubscribedState|ErrorState; /** 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. */ readonly terminated: Promise; /** Unsubscribe from this resource and stop receiving updates. If the subscription is already in the "unsubscribed" or "error" state, this is a no-op. */ unsubscribe(): void; } ## UserOnlineSnapshot /** 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`. */ export interface UserOnlineSnapshot { /** 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. */ readonly isConnected: boolean; /** The user this snapshot relates to */ readonly user: UserSnapshot; } ## UserOnlineSubscription /** 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. */ export interface UserOnlineSubscription { /** 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. */ readonly connected: Promise; /** 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: UserOnlineSnapshot|null` `null` means the user does not exist. When `type` is "error", includes the `error` field. It is a JS `Error` object explaining what caused the subscription to be terminated. */ state: PendingState|UserOnlineActiveState|UnsubscribedState|ErrorState; /** 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. */ readonly terminated: Promise; /** Unsubscribe from this resource and stop receiving updates. If the subscription is already in the "unsubscribed" or "error" state, this is a no-op. */ unsubscribe(): void; }