Session

class Session

A session represents a TalkJS session. It also authenticates your app with TalkJS.

It is also responsible for creating User and Conversation objects.

Note: After creating the Session object, you must set its me property before doing anything else related to TalkJS.

Available methods

ConstructorCreates a TalkJS Session.
destroyInvalidates this session.
getUserA method used to either fetch or create a user.
getUserByIdA method used to fetch an existing user.
getConversationA method used to either fetch or create a conversation.
hasValidCredentialsVerifies whether the `appId` is valid.
setPushRegistrationA method used to register push notification device tokens on the TalkJS backend.
unsetPushRegistrationA method used to unregister push notification device tokens on the TalkJS backend.
clearPushRegistrationsA method used to unregister all push notification device tokens for the current user.

Available properties

appId
String

Your TalkJS AppId that can be found on the Settings page of your TalkJS dashboard.

enablePushNotifications
bool

This determines whether the device the user is currently using will be registered by the SDK to receive push notifications.

me
User

A User object that identifies the currently active user.

Note: A User object is created by calling either the getUser or getUserById methods of the Session object.

NoteE: After creating the Session object, you must set its me property before doing anything else related to TalkJS.

signature
String?

If you use Identity verification make sure you generate and use a signature.

onMessage
MessageHandler?

Triggered when a message is sent in a conversation the current user is in.

unreads
Unreads?

This object can notify you when the amount of unread conversations changes.

Constructor

Session({
required String appId,
bool? enablePushNotifications = false,
String? signature,
MessageHandler? onMessage,
Unreads? unreads,
});

Creates a TalkJS Session.

Parameters

appId
String

Your app's unique TalkJS ID. Get it from the Settings page of your dashboard.

enablePushNotifications
(optional)bool?

This determines whether the device the user is currently using will be registered to receive push notifications.

If explicitly passing null, the SDK will not automatically register/unregister the current device. You'll have to call setPushRegistration and unsetPushRegistration accordingly.

signature
(optional)String?

If you use Identity verification make sure you generate and use a signature.

onMessage
(optional)MessageHandler?

Triggered when a message is sent in a conversation the current user is in.

unreads
(optional)Unreads?

This object can notify you when the amount of unread conversations changes.

destroy

Future<void> destroy();

Invalidates this session.

You cannot use any objects that were created in this session after you destroy it.

If you want to use TalkJS after having called destroy() you must instantiate a new Session instance.

Returns

The return value is a Future that can be awaited to be sure that the session has actually been invalidated.

getUser

User getUser({
required String id,
required String name,
List<String>? email,
List<String>? phone,
String? availabilityText,
String? locale,
String? photoUrl,
String? role,
Map<String, String?>? custom,
String? welcomeMessage,
});

Fetches or creates a User.

Use this method to synchronize user data with the TalkJS backend.

The fields id and name are required. A warning will be emitted if role is not specified.

Set email to null if you want to use TalkJS without email fallback.

Parameters

availabilityText
(optional)String?

Availability acts similarly to User​.welcomeMessage but appears as a system message.

custom
(optional)Map<String, String?>?

Allows you to set custom metadata for the User

email
(optional)List<String>?

One or more email address belonging to the User. The email addresses will be used for Email Notifications if they are enabled.

id
String

The unique ID which is used to identify the user in TalkJS

locale
(optional)String?

The locale field expects an IETF language tag. See the localization documentation.

name
String

The User's name which will be displayed on the TalkJS UI

phone
(optional)List<String>?

One or more phone numbers belonging to the User. The phone number will be used for SMS Notifications (this feature requires standard plan and up).

photoUrl
(optional)String?

An optional URL to a photo which will be displayed as the user's avatar

role
(optional)String?

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.

welcomeMessage
(optional)String?

The default message a user sees when starting a chat with that person

Returns

User

getUserById

User getUserById(String id);

Fetches an existing User.

Only use this method if you're sure that a user by the given id already exists in TalkJS (for instance, because you synchronized it via the REST API). Otherwise use the getUser method instead.

Parameters

id
String

The unique ID which is used to identify the user in TalkJS

Returns

User

getConversation

Conversation getConversation({
required String id,
Map<String, String?>? custom,
List<String>? welcomeMessages,
String? photoUrl,
String? subject,
Set<Participant> participants = const <Participant>{},
});

Returns a Conversation object that encapsulates a conversation between me (set as a property of the Session) and zero or more other participants.

The returned Conversation is a reference to a conversation with the given id, that is automatically created or updated with the given fields the first time it is used in a ChatBox.

If conversation synchronization is disabled, pass only the id parameter, and make sure that a conversation with that id already exists.

Parameters

id
String

A unique identifier for this conversation, such as a channel name or topic ID. Any user with access to this ID can join this conversation. Read about how to choose a good conversation ID for your use case If you want to make a simple one-on-one conversation, consider using oneOnOneId to generate one.

custom
(optional)Map<String, String?>?

Custom metadata that is stored with the conversation

photoUrl
(optional)String?

The URL of a photo to be used for this conversation in the TalkJS UI in case there are more than 2 participants (TalkJS shows the photo of the other participant in a 1-on-1 conversation)

subject
(optional)String?

A human-readable subject of the conversation. Supports formatted links in a Markdown-style syntax, e.g. Beautiful <https://example.com/booking/18644|home by the sea>;!. URLs and email addresses are made clickable, and emojis made to work cross-platform.

welcomeMessages
(optional)List<String>?

Messages which are sent at the beginning of a chat. In this case the messages will appear as system messages.

participants
(optional)Set<Participant>

A set containing the participants for this conversation.

Returns

Conversation

hasValidCredentials

Future<bool> hasValidCredentials();

Verifies whether the appId is valid.

Returns

The return value is a Future of a boolean.

setPushRegistration

Future<void> setPushRegistration({
Provider? provider,
String? pushRegistrationId,
});

Registers push notifications to the TalkJS backend.

If the provider and pushRegistrationId parameters are not passed, it registers the device's current token on Firebase if it's running on Android and on APNs if it's on iOS.

If passing parameters to this function, both provider and pushRegistrationId must not be null

Parameters

provider
(optional)Provider?

Either Provider.fcm or Provider.apns.

pushRegistrationId
(optional)String?

The FCM or APNS token ID.

Returns

The return value is a Future that can be awaited to be sure that the communication with the backend actually happened.

unsetPushRegistration

Future<void> unsetPushRegistration({
Provider? provider,
String? pushRegistrationId,
});

Unregisters push notifications to the TalkJS backend.

If the provider and pushRegistrationId parameters are not passed, it unregisters the device's current token on Firebase if it's running on Android and on APNs if it's on iOS.

If passing parameters to this function, both provider and pushRegistrationId must not be null

Parameters

provider
(optional)Provider?

Either Provider.fcm or Provider.apns.

pushRegistrationId
(optional)String?

The FCM or APNS token ID.

Returns

The return value is a Future that can be awaited to be sure that the communication with the backend actually happened.

clearPushRegistrations

Future<void> clearPushRegistrations();

Unregisters all push notification device tokens for the current user

Returns

The return value is a Future that can be awaited to be sure that the communication with the backend actually happened.


Event handlers

MessageHandler

typedef MessageHandler = void Function(Message message);

See Message for the callback parameter.