---
url: https://talkjs.com/docs/Data_APIs/Flutter/Users
title: 'Users'
minidoc-source: dart
---

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 [TalkSession.user]. */
class UserRef {
/** The ID of the referenced user.
Immutable: if you want to reference a different user, get a new UserRef instead. */
final String id;

/** 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.
@return A snapshot of the user's public attributes, or null if the user doesn't exist. */
Future<UserSnapshot?>get()

/** Sets properties of this user. The user is created if a user with this ID doesn't already exist.
Properties that are `null` will not be changed. To clear / reset a property to the default, call [UserRef.deleteFields] instead.
`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.
@param name The user's name which will be displayed on the TalkJS UI
@param custom 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
@param locale An [IETF language tag](https://www.w3.org/International/articles/language-tags/) See the [localization documentation](/docs/Features/Language_Support/Localization.html) Default = the locale selected on the dashboard
@param photoUrl An optional URL to a photo which will be displayed as the user's avatar. Default = no photo
@param role 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
@param welcomeMessage The default message a person sees when starting a chat with this user. Default = no welcome message
@param email An array of email addresses associated with the user. Default = no email addresses
@param phone An array of phone numbers associated with the user. Default = no phone numbers
@param pushTokens 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 */
Future<void>set({String? name, Map<String, String?>? custom, String? locale, String? photoUrl, String? role, String? welcomeMessage, List<String>? email, List<String>? phone, Map<String, bool?>? pushTokens})

/** 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.
@param name The user's name which is displayed on the TalkJS UI
@param custom Custom metadata you have set on the user. Default = no custom metadata
@param locale An [IETF language tag](https://www.w3.org/International/articles/language-tags/) See the [localization documentation](/docs/Features/Language_Support/Localization.html) Default = the locale selected on the dashboard
@param photoUrl An optional URL to a photo that is displayed as the user's avatar. Default = no photo
@param role 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
@param welcomeMessage The default message a person sees when starting a chat with this user. Default = no welcome message
@param email An array of email addresses associated with the user. Default = no email addresses
@param phone An array of phone numbers associated with the user. Default = no phone numbers
@param pushTokens 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) */
Future<void>createIfNotExists({required String name, Map<String, String>? custom, String? locale, String? photoUrl, String? role, String? welcomeMessage, List<String>? email, List<String>? phone, Map<String, bool>? pushTokens})

/** Deletes properties of this user.
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`.
@param fields The names of the properties to delete */
Future<void>deleteFields(List<String>fields)

/** 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.
@return A subscription to the user */
UserSubscription subscribe(void Function(UserSnapshot? snapshot) onSnapshot)

/** 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.
@return A subscription to the user's online status */
UserOnlineSubscription subscribeOnline(void Function(UserOnlineSnapshot? snapshot) onSnapshot)
}

## 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](/docs/Reference/REST_API/Getting_Started/Introduction/) */
class UserSnapshot {
/** The unique ID that is used to identify the user in TalkJS */
final String id;

/** The user's name, which is displayed on the TalkJS UI */
final String name;

/** Custom metadata you have set on the user */
final Map<String, String>custom;

/** 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. */
final String role;

/** An [IETF language tag](https://www.w3.org/International/articles/language-tags/) For more information, see: [localization](/docs/Features/Language_Support/Localization.html)
When `locale` is null, the app's default locale will be used */
String? locale;

/** An optional URL to a photo that is displayed as the user's avatar */
String? photoUrl;

/** The default message a person sees when starting a chat with this user */
String? welcomeMessage;

UserSnapshot(Map<String, dynamic>json)

Map<String, dynamic>toJson()
}

## UserSubscription
class UserSubscription {
/** Resolves when the subscription starts receiving updates from the server. */
final Future<void>connected;

/** 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. */
final Future<void>terminated;

/** Unsubscribe from this resource and stop receiving updates.
If the subscription is already in the [UnsubscribedState] or [ErrorState], this is a no-op. */
Future<void>unsubscribe()
}

## 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`. */
class UserOnlineSnapshot {
/** The user this snapshot relates to */
final UserSnapshot user;

/** 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](/docs/Reference/JavaScript_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](/docs/Reference/Components/), are considered connected if they have a UI open.
People using the [JavaScript SDK](/docs/Reference/JavaScript_Chat_SDK/), [React SDK](/docs/Reference/React_SDK/Installation/), [React Native SDK](/docs/Reference/React_Native_SDK/Installation/), or [Flutter SDK](/docs/Reference/Flutter_SDK/Installation/) are considered connected whenever they have an active `Session` object. */
final bool isConnected;

UserOnlineSnapshot(Map<String, dynamic>json)

Map<String, dynamic>toJson()
}

## 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. */
class 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. */
final Future<void>connected;

/** 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. */
final Future<void>terminated;

/** Unsubscribe from this resource and stop receiving updates.
If the subscription is already in the [UnsubscribedState] or [ErrorState], this is a no-op. */
Future<void>unsubscribe()
}