Session
A session represents a user's active browser tab. It also authenticates your app with TalkJS.
| Constructor | Creates a TalkJS Session. |
| clearPushRegistrations | Unregisters all the mobile devices for the user. |
| conversation | Get a reference to a conversation. |
| createChatbox | Creates a Chatbox UI. |
| createInbox | Creates an Inbox UI |
| createPopup | Creates a Popup UI. |
| destroy | Disconnects all websockets, removes all UIs, and invalidates this session. |
| getChatboxes | Returns a list of all active Chatbox objects linked to this session. |
| getInboxes | Returns a list of all active Inbox objects linked to this session. |
| getOrCreateConversation Classic | A method used to either fetch or create a conversation. |
| getPopups | Returns a list of all active Popup objects linked to this session. |
| hasValidCredentials | Verifies whether the |
| onBrowserPermissionDenied | Triggered when the user tried to do an action that requires explicit browser permission, but this permission was denied. |
| onBrowserPermissionNeeded | Triggered when a browser permission prompt is about to be shown. |
| onDesktopNotificationClicked | Listen for when a user clicks a desktop notification. |
| onMessage | Triggered when a message is sent in a conversation the current user is in. |
| setDesktopNotificationEnabled | Sets desktop notification on or off. |
| setPushRegistration | Registers a single mobile device, as one user can be connected to multiple mobile devices. |
| subscribeConversations | Subscribes to your most recently active conversations. |
| unsetPushRegistration | Unregisters a single mobile device, as one user can be connected to multiple mobile devices. |
| uploadAudio | Upload an audio file with audio-specific metadata. |
| uploadFile | Upload a generic file without any additional metadata. |
| uploadImage | Upload an image with image-specific metadata. |
| uploadVideo | Upload a video with video-specific metadata. |
| uploadVoice | Upload a voice recording with voice-specific metadata. |
| user | Get a reference to a user. |
| off Deprecated | Used to stop listening to specific TalkJS session events. |
| on Deprecated | Listens for an event |
| registerDevice Deprecated | |
| syncThemeForLocalDev Deprecated | Used to configure TalkJS to use a legacy theme hosted on the same location as your application for development. |
| unregisterDevice Deprecated |
Your TalkJS AppId that can be found on the "Settings" page of your TalkJS dashboard.
A reference to the current user.
The current user is the one you passed to the session constructor as userId or me. This is a short-hand for session.user(session.me.id).
The returned UserRef is part of the Data API, which is included in the Chat SDK. You can use references to get, edit, and subscribe to your data.
Whether the session is active and in a valid state.
When false, calling methods on this Session instance will throw errors.
This field is false when destroy has been called in the past. Once a session has been destroyed, you cannot revive it. Instead, create a new session.
The TalkJS User associated with the current user in your application.
Holds information about unread conversations. Lets your app be notified when the active user receives a new message.
new Session(options)
Creates a TalkJS Session.
Parameters
interface SessionOptions
Your app's unique TalkJS ID. Get it from the "Settings" page of your dashboard.
A token to authenticate the session with.
See the how-to guide on generating authentication tokens, and many examples in different programming languages.
See the reference documentation for full details on the technical requirements for the JWT.
A function that fetches and returns a new authentication token from your server. TalkJS calls this function whenever the current token is about to expire. This callback is designed to work with any backend setup.
TalkJS will not retry your tokenFetcher if the callback throws an error. Your callback should implement its own retry functionality.
See the how-to guide on refreshable authentication tokens, and many examples in different programming languages.
The ID of the currently active user.
It is permitted to pass the ID of a user that does not exist yet. However, you cannot mount a Chat UI before creating your user.
Session.currentUser will be a reference to the user with this ID.
This is the recommended alternative to me.
User is part of the Classic Data API. New TalkJS integrations should use userId instead and manually create the user with Session.currentUser.set({ ... }). UserRef.set() is part of the simpler and more powerful Data API.
A User object that identifies the currently active user. The user is uniquely identified by their id; all other fields (name, photo, etc) are overwritten in the TalkJS database each time they change, unless the user has been created with the alternate constructor.
Legacy alternative to JWT authentication. A HMAC-SHA256 hash of the current user ID, signed with your TalkJS secret key.
See the documentation for examples of how to generate a signature in different programming languages.
session.clearPushRegistrations(): Promise<void>
Unregisters all the mobile devices for the user.
Related methods: setPushRegistrationunsetPushRegistration
Note that you must ensure that the user exists in the TalkJS database before you call this method. The simplest way to do that is to call it after you mount a chatbox, inbox or popup.
Returns
session.conversation(id): ConversationRef
Get a reference to a conversation.
The returned ConversationRef is part of the Data API, which is included in the Chat SDK. You can use references to get, edit, and subscribe to your data.
Parameters
The ID of the conversation that you want to reference
Returns
A ConversationRef for the conversation with that ID
Usage
1session.conversation("test").createIfNotExists();
1session.conversation("test").set({ subject: "Power tools" });
1session.conversation("test").set({ notify: false });
session.createChatbox(options): Chatbox
Creates a Chatbox UI.
The Chatbox is a slimmer version of the Inbox. It shows a single conversation, without giving the user a way to switch between conversations.
Call createChatbox on any page you want to show a chatbox of a single conversation. You typically want to call Chatbox.mount after creating the chatbox to make it visible on your app.
Note: A deprecated two-parameter form of this method, createChatbox(selectedConversation, options), also exists. This form will keep being supported but we recommend not using it new codebases. Instead, call Chatbox.select immediately after mount.
Parameters
Optional, Use these to finetune the behavior of the Chatbox.
interface ChatboxOptions
Enables capturing Chatbox.onKeyup events.
Note: Setting this to true also disables any non-standard keyboard shortcuts in TalkJS.
At the time of writing, the only such shortcut is that when captureKeyboardEvents is disabled, TalkJS will auto-focus the message field if the user starts typing but no input field is focused.
Allows users to send and receive custom emojis.
This adds a set of custom emoji images to the emoji picker, the emoji autocompleter, and emoji reactions.
Every emoji name *must* start and end with a colon, for example :lol:.
Make sure you always specify a consistent, backward-compatible set of custom emojis. If an existing message contains a custom emoji that is not specified in customEmojis here, then the emoji cannot be displayed and the textual name will be displayed instead (including colons).
If you want to allow an emoji to be displayed if it's used in existing data, but not let users select it in new messages/reactions, set the hidden option to true for that emoji.
Controls the text direction (for supporting right-to-left languages such as Arabic and Hebrew). TalkJS tries to determine the appropriate text direction from the parent page, but if that does not work or you want to explicitly control it, you can override it here. Defaults to "rtl".
Settings that affect the behavior of the message field
Used to control which messages are shown in the message list, depending on a type, origin or custom message attributes.
*Note*: Messages are only filtered in the message list. The inbox UI's conversation feed will always show the last message sent to the conversation, regardless of the message filter set.
See MessagePredicate for all available options.
You can also modify the filter on the fly using Chatbox.setMessageFilter.
Sets metadata for the current session.
- visible manually sets the information about the visibility of TalkJS. This is useful when TalkJS is hidden with CSS. TalkJS will assume that UIs marked visible: false cannot be seen, and thus messages arriving on this UI will not be marked as read until you set visible to true again.
- custom is an additional parameter to store the custom fields, that you may want to use in the REST API call.
Used to control if the Chat Header is displayed in the UI. Defaults to true.
Set this to true to show a translation toggle in all conversations. Set this to "auto" to show a translation toggle in conversations where there are participants with different locales. This setting defaults to false, meaning that no toggles will be shown. In order to use this, you must be on the Growth plan, and set a Google Translate API key on the "Settings" page of the dashboard.
Overrides the theme used for this chat UI.
This only works with themes created in the Theme Editor. If you don't pass a theme name, we'll first check for a theme set in the user's role, and then fall back to using the default theme.
You can either pass the name of the theme you'd like to use, or a ThemeOptions object, which you can use to pass variables to your theme.
TalkJS leverages iframes behind the scenes and therefore not all services that you use in your app will work out of the box. This option adds support for a number of services to help you use them. Let us know if you're missing any.
TalkJS can translate conversations to the current user's locale using Google Translate. This option specifies which conversations should be translated in this UI. You can pass a boolean to enable or turn off translation for all conversations, "auto" to enable translation on conversations where users have different locales, or you can pass an array of ConversationBuilders or conversation Ids to be translated. This feature is only available on the Growth plan and above. Make sure you add your Google Translate API key on the "Settings" page of the dashboard.
Controls what text appears in the chat subtitle, right below the chat title. No subtitle is displayed when the conversation has no subject set or when set to null. Defaults to "subject".
(also see chatTitleMode and InboxOptions.feedConversationTitleMode)
Controls what text appears in the chat title, in the header above the messages. Defaults to "participants".
(also see chatSubtitleMode and InboxOptions.feedConversationTitleMode)
Sets the message input box to the given text. You can use this to suggest a certain initial message to be sent. The user can still edit it before hitting "send".
Returns
Usage
session.createInbox(options): Inbox
Creates an Inbox UI
The Inbox is TalkJS's most versatile component. It combines a Chatbox with a panel showing a a list of conversations where the user is a participant.
Call createInbox on the messaging page of your app. You typically want to call Inbox.mount after creating the inbox to make it visible on your app.
Parameters
Optional. Use these to finetune the behavior of the Inbox.
interface InboxOptions
Enables capturing Chatbox.onKeyup events.
Note: Setting this to true also disables any non-standard keyboard shortcuts in TalkJS.
At the time of writing, the only such shortcut is that when captureKeyboardEvents is disabled, TalkJS will auto-focus the message field if the user starts typing but no input field is focused.
Allows users to send and receive custom emojis.
This adds a set of custom emoji images to the emoji picker, the emoji autocompleter, and emoji reactions.
Every emoji name *must* start and end with a colon, for example :lol:.
Make sure you always specify a consistent, backward-compatible set of custom emojis. If an existing message contains a custom emoji that is not specified in customEmojis here, then the emoji cannot be displayed and the textual name will be displayed instead (including colons).
If you want to allow an emoji to be displayed if it's used in existing data, but not let users select it in new messages/reactions, set the hidden option to true for that emoji.
Controls the text direction (for supporting right-to-left languages such as Arabic and Hebrew). TalkJS tries to determine the appropriate text direction from the parent page, but if that does not work or you want to explicitly control it, you can override it here. Defaults to "rtl".
Used to control which conversations are shown in the conversation feed, depending on access level, custom conversation attributes or message read status.
The feedFilter can be either of the following: - a single ConversationPredicate object that filters based on all the fields of the predicate - an array that gives you all the conversations that satisfy at least one of the ConversationPredicates
When filtering conversations with an array, the first element must be the string "any", and the second element a list of ConversationPredicate objects.
See ConversationPredicate for all available options.
You can also modify the filter on the fly using Inbox.setFeedFilter.
Settings that affect the behavior of the message field
Used to control which messages are shown in the message list, depending on a type, origin or custom message attributes.
*Note*: Messages are only filtered in the message list. The inbox UI's conversation feed will always show the last message sent to the conversation, regardless of the message filter set.
See MessagePredicate for all available options.
You can also modify the filter on the fly using Inbox.setMessageFilter.
Sets metadata for the current session.
- visible manually sets the information about the visibility of TalkJS. This is useful when TalkJS is hidden with CSS. TalkJS will assume that UIs marked visible: false cannot be seen, and thus messages arriving on this UI will not be marked as read until you set visible to true again.
- custom is an additional parameter to store the custom fields, that you may want to use in the REST API call.
Used to control if the Chat Header is displayed in the UI. Defaults to true.
Controls if the feed header containing the toggle to enable desktop notifications is shown. Defaults to true.
Whether to show a "Back" button at the top of the chat screen on mobile devices.
Set this to true to show a translation toggle in all conversations. Set this to "auto" to show a translation toggle in conversations where there are participants with different locales. This setting defaults to false, meaning that no toggles will be shown. In order to use this, you must be on the Growth plan, and set a Google Translate API key on the "Settings" page of the dashboard.
Overrides the theme used for this chat UI.
This only works with themes created in the Theme Editor. If you don't pass a theme name, we'll first check for a theme set in the user's role, and then fall back to using the default theme.
You can either pass the name of the theme you'd like to use, or a ThemeOptions object, which you can use to pass variables to your theme.
TalkJS leverages iframes behind the scenes and therefore not all services that you use in your app will work out of the box. This option adds support for a number of services to help you use them. Let us know if you're missing any.
TalkJS can translate conversations to the current user's locale using Google Translate. This option specifies which conversations should be translated in this UI. You can pass a boolean to enable or turn off translation for all conversations, "auto" to enable translation on conversations where users have different locales, or you can pass an array of ConversationBuilders or conversation Ids to be translated. This feature is only available on the Growth plan and above. Make sure you add your Google Translate API key on the "Settings" page of the dashboard.
Controls whether the user navigating between conversation should count as steps in the browser history. Defaults to true, which means that if the user clicks the browser's back button, they go back to the previous conversation (if any).
Controls what text appears in the chat subtitle, right below the chat title. No subtitle is displayed when the conversation has no subject set or when set to null. Defaults to "subject".
(also see chatTitleMode and feedConversationTitleMode)
Controls what text appears in the chat title, in the header above the messages. Defaults to "participants".
(also see chatSubtitleMode and feedConversationTitleMode)
Controls how a chat is displayed in the feed of chats.
Note: when set to "subject" but a conversation has no subject set, then TalkJS falls back to "participants".
When not set, defaults to "auto", which means that in group conversations that have a subject set, the subject is displayed and otherwise the participants.
(also see chatSubtitleMode and chatTitleMode)
Sets the message input box to the given text. You can use this to suggest a certain initial message to be sent. The user can still edit it before hitting "send".
Makes the inbox start up with the given Conversation. Can be passed a value of the type ConversationBuilder (returned by getOrCreateConversation) or the string value of the conversation id. Conversation can be deselected on startup by passing a null value. Passing undefined means that the last conversation (or "no chats yet page") will be displayed.
Returns
Usage
session.createPopup(options): Popup
Creates a Popup UI.
The Popup is a positioned box containing a conversation. It shows a single conversation, without means to switch between conversations.
Call createPopup on any page you want to show a popup of a single conversation. You typically want to call Popup.mount after creating the popup to make it visible on your app.
Note: A deprecated two-parameter form of this method, createPopup(selectedConversation, options), also exists. This form will keep being supported but we recommend not using it new codebases. Instead, call Popup.select immediately after mount. In order to have a popup on each site you need to call createPopup on any page you want to show a popup with the conversation.
Parameters
Optional, Use these to finetune the behavior of the Popup.
interface PopupOptions
Enables capturing Chatbox.onKeyup events.
Note: Setting this to true also disables any non-standard keyboard shortcuts in TalkJS.
At the time of writing, the only such shortcut is that when captureKeyboardEvents is disabled, TalkJS will auto-focus the message field if the user starts typing but no input field is focused.
Allows users to send and receive custom emojis.
This adds a set of custom emoji images to the emoji picker, the emoji autocompleter, and emoji reactions.
Every emoji name *must* start and end with a colon, for example :lol:.
Make sure you always specify a consistent, backward-compatible set of custom emojis. If an existing message contains a custom emoji that is not specified in customEmojis here, then the emoji cannot be displayed and the textual name will be displayed instead (including colons).
If you want to allow an emoji to be displayed if it's used in existing data, but not let users select it in new messages/reactions, set the hidden option to true for that emoji.
Controls the text direction (for supporting right-to-left languages such as Arabic and Hebrew). TalkJS tries to determine the appropriate text direction from the parent page, but if that does not work or you want to explicitly control it, you can override it here. Defaults to "rtl".
If enabled, the Popup will reopen every time the user navigates to another page. This way, a conversation can continue while the user browses around. Set to false to disable this behavior.
Defaults to false.
Specifies whether to show a round launcher and/or close button beneath the popup in the right bottom corner of the page.
"close-only": show a close button beneath the popup, but don't show a launch button
"always": show a launch button when the popup is closed, show a close button when it is visible
"never": never show a launcher
Note: if you choose "never" you may want to override the positioning of the popup as well. Just tune the __talkjs_popup class in your CSS.
Ignored on mobile, where the popup fills the entire screen so the value is effectively "never".
Defaults to "always".
Settings that affect the behavior of the message field
Used to control which messages are shown in the message list, depending on a type, origin or custom message attributes.
*Note*: Messages are only filtered in the message list. The inbox UI's conversation feed will always show the last message sent to the conversation, regardless of the message filter set.
See MessagePredicate for all available options.
You can also modify the filter on the fly using Popup.setMessageFilter.
Sets metadata for the current session.
- visible manually sets the information about the visibility of TalkJS. This is useful when TalkJS is hidden with CSS. TalkJS will assume that UIs marked visible: false cannot be seen, and thus messages arriving on this UI will not be marked as read until you set visible to true again.
- custom is an additional parameter to store the custom fields, that you may want to use in the REST API call.
Used to control if the Chat Header is displayed in the UI. Defaults to true.
Whether to show the "x" icon in the popup header to close the popup. "auto", which is the default value means true on mobile and to false on desktop.
Set this to true to show a translation toggle in all conversations. Set this to "auto" to show a translation toggle in conversations where there are participants with different locales. This setting defaults to false, meaning that no toggles will be shown. In order to use this, you must be on the Growth plan, and set a Google Translate API key on the "Settings" page of the dashboard.
Overrides the theme used for this chat UI.
This only works with themes created in the Theme Editor. If you don't pass a theme name, we'll first check for a theme set in the user's role, and then fall back to using the default theme.
You can either pass the name of the theme you'd like to use, or a ThemeOptions object, which you can use to pass variables to your theme.
TalkJS leverages iframes behind the scenes and therefore not all services that you use in your app will work out of the box. This option adds support for a number of services to help you use them. Let us know if you're missing any.
TalkJS can translate conversations to the current user's locale using Google Translate. This option specifies which conversations should be translated in this UI. You can pass a boolean to enable or turn off translation for all conversations, "auto" to enable translation on conversations where users have different locales, or you can pass an array of ConversationBuilders or conversation Ids to be translated. This feature is only available on the Growth plan and above. Make sure you add your Google Translate API key on the "Settings" page of the dashboard.
Controls what text appears in the chat subtitle, right below the chat title. No subtitle is displayed when the conversation has no subject set or when set to null. Defaults to "subject".
(also see chatTitleMode and InboxOptions.feedConversationTitleMode)
Controls what text appears in the chat title, in the header above the messages. Defaults to "participants".
(also see chatSubtitleMode and InboxOptions.feedConversationTitleMode)
Sets the message input box to the given text. You can use this to suggest a certain initial message to be sent. The user can still edit it before hitting "send".
Returns
Usage
session.destroy()
Disconnects all websockets, removes all UIs, and 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 Talk.Session instance.
Returns
session.getChatboxes(): Chatbox[]
Returns a list of all active Chatbox objects linked to this session.
Only includes chatboxes that are still mounted in the DOM. So if you call createChatbox() but later remove its container element (or an ancestor of the container), then the Chatbox object will have been made invalid and is therefore not included in the results.
Returns
session.getInboxes(): Inbox[]
Returns a list of all active Inbox objects linked to this session.
Only includes inboxes that are still mounted in the DOM. So if you call createInbox() but later remove its container element (or an ancestor of the container), then the Inbox object will have been made invalid and is therefore not included in the results.
Returns
session.getOrCreateConversation(conversationId): ConversationBuilder
A method used to either fetch or create a conversation.
Returns a ConversationBuilder object that encapsulates a conversation between me (given in the constructor) and zero or more other participants. Use ConversationBuilder.setParticipant and ConversationBuilder.setAttributes on the returned object to further set up your conversation.
Parameters
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.
Returns
session.getPopups(): Popup[]
Returns a list of all active Popup objects linked to this session.
Includes popups actively created using createPopup, and also popups created on page load, if PopupOptions.keepOpen was set to true on an earlier page.
Only includes popups that are still mounted in the DOM. So if you call createPopup() but later remove its container element (or an ancestor of the container), then the Popup object will have been made invalid and is therefore not included in the results.
Returns
session.hasValidCredentials(): Promise<boolean>
Verifies whether the appId is valid.
Returns a Promise of a boolean, never rejects.
Returns
session.onBrowserPermissionDenied(handler): Subscription
Triggered when the user tried to do an action that requires explicit browser permission, but this permission was denied.
This can be caused by user actions such as the sharing a location, enabling desktop notifications, or trying to record a voice message. These features require the user to explicitly grant the browser permission.
This event can be triggered in two situations:
1. The browser showed the user a permission prompt, and the user picked "Deny". In this case, this event will have been preceded by onBrowserPermissionNeeded.
2. The user has denied the same permission in the past and the browser remembered this decision. In this case, the action will fail immediately and an onBrowserPermissionNeeded event will not have been emitted.
In either case, the user may be able to allow the permission in their browser settings. The intended use of this event is to show the user an alert or dialog telling them how.
Note: by default, TalkJS may display an error message in an alert if a permission is denied. If you listen to this event, then these messages are suppressed under the assumption that you will provide your own UI for this.
Parameters
Returns
session.onBrowserPermissionNeeded(handler): Subscription
Triggered when a browser permission prompt is about to be shown.
Certain features, such as sharing location, sending voice messages, or receiving notificatons, only work if the user has granted your app the relevant permissions. By default, TalkJS will trigger the browser's built-in permissions dialog the first time such a feature is used.
This event is triggered *just before* this browser permissions dialog is shown. This lets you show custom UI elements that let you show the user where to look, or explain that it's all safe.
If you return a promise from your event handler, then TalkJS will wait until this promise resolves before showing the permission dialog.
Note that it is not guaranteed that this event will trigger: It will only trigger if we are certain that a permission prompt is about to show, and unfortunately we can't be certain of that in all browsers. More explicitly, it will only trigger when the browser supports the [Permissions API](https://developer.mozilla.org/en-US/docs/Web/API/Permissions_API) with the given notification type.
Notably:
* Safari below 15.6 (2022) does not support the Permissions API at all
* Firefox does not support querying the "microphone" permission, which TalkJS needs for voice messages.
In these situations, this event will never trigger.
Parameters
Returns
session.onDesktopNotificationClicked(handler): Subscription
Listen for when a user clicks a desktop notification.
A "desktopNotificationClicked" event is fired every time a user clicks on a desktop notification generated by TalkJS.
When a user clicks on a notification, these things will happen:
1. The browser tab will be selected (note, this works in most browsers but cannot be guaranteed);
2. If you provided one or more "desktopNotificationClicked" handlers, they will be invoked in order;
3. If you did not, then the currently active inbox (if any) will jump to the conversation corresponding to the notification.
See also setDesktopNotificationEnabled
Parameters
Returns
session.onMessage(handler): Subscription
Triggered when a message is sent in a conversation the current user is in.
A "message" event is fired every time a message is sent or received by the current user (even if no TalkJS UI is visible). Your handler function is passed a Message object with some information about each message and its conversation.
Note that this event does not get triggered for conversations where the current user is a guest. It only applies to users who were added as participants.
Parameters
Returns
session.setDesktopNotificationEnabled(isEnabled, { alertOnFailure }): Promise<void>
Sets desktop notification on or off.
Has the same effect as toggling the "Desktop notification" toggle in the TalkJS Inbox UI. Use this function to replicate that toggle elsewhere in your UI if you're using TalkJS in a mode that doesn't show this toggle.
When desktop notifications are enabled for the first time, the browser will show a prompt to ask the user for permission. The call will only succeed if the user accepts it.
We recommend only calling this function in response to user action, so users know that they can expect a permission prompt. This significantly increases the percentage of users that click "Allow".
Notably, we strongly recommend that you do not call this function immediately when the page loads, because many browsers auto block notifications when permission is requested on page load. This is likely a measure to prevent overly aggressive news sites from being able to spam past visitors.
Parameters
Whether notifications should be enabled.
Returns
a promise that'll resolve if the change succeeds. If anything goes wrong, the promise will reject with a TalkError, which has a code property to indicate what went wrong. Possible values in this case are:
- Talk.ErrorCode.NOTIFICATIONS_PERMISSION_DENIED: The browser or the user didn't grant you permission to send notifications.
- Talk.ErrorCode.NOTIFICATIONS_NOT_SUPPORTED: The browser doesn't support desktop notifications.
session.setPushRegistration(options): Promise<void>
Registers a single mobile device, as one user can be connected to multiple mobile devices.
Related methods: unsetPushRegistrationclearPushRegistrations
Note that you must ensure that the user exists in the TalkJS database before you call this method. The simplest way to do that is to call it after you mount a chatbox, inbox or popup.
Parameters
interface PushRegistrationOptions
The push message provider to use: Google's Firebase Cloud Messaging (fcm) or Apple's APNs (apns).
The APNs device token or the FCM registration token.
Returns
session.subscribeConversations(onSnapshot): ConversationListSubscription
Subscribes to your most recently active conversations.
The subscription is 'windowed'. Initially, this window contains the 20 most recent conversations. Conversations are ordered by last activity. The last activity of a conversation is either joinedAt or lastMessage.createdAt, whichever is higher.
If an older conversation receives a new message, or you are added to a conversation, it will appear at the start of the list. Call loadMore to load additional older conversations.
Whenever Subscription.state.type is "active" and something changes in your conversations, onSnapshot will fire and Subscription.state.latestSnapshot will be updated. loadedAll is true when the snapshot contains all your conversations.
If the current user does not exist yet, the snapshot will be an empty list.
Parameters
Returns
session.unsetPushRegistration(options): Promise<void>
Unregisters a single mobile device, as one user can be connected to multiple mobile devices.
Related methods: setPushRegistrationclearPushRegistrations
Note that you must ensure that the user exists in the TalkJS database before you call this method. The simplest way to do that is to call it after you mount a chatbox, inbox or popup.
Parameters
interface PushRegistrationOptions
The push message provider to use: Google's Firebase Cloud Messaging (fcm) or Apple's APNs (apns).
The APNs device token or the FCM registration token.
Returns
session.uploadAudio(data, metadata): Promise<FileToken>
Upload an audio file with audio-specific metadata.
This is a variant of uploadFile used for audio files.
Parameters
The binary audio data. Usually a File.
Information about the audio file.
interface AudioFileMetadata
Returns
A file token that can be used to send the audio file in a message.
session.uploadFile(data, metadata): Promise<FileToken>
Upload a generic file without any additional metadata.
This function does not send any message, it only uploads the file and returns a file token. To send the file in a message, pass the file token in a SendFileBlock when calling ConversationRef.send.
See the documentation for more information about sending files in messages.
If the file is a video, image, audio file, or voice recording, use one of the other functions like uploadImage instead.
Parameters
The binary file data. Usually a File.
Information about the file
Returns
A file token that can be used to send the file in a message.
session.uploadImage(data, metadata): Promise<FileToken>
Upload an image with image-specific metadata.
This is a variant of uploadFile used for images.
Parameters
The binary image data. Usually a File.
Information about the image.
interface ImageFileMetadata
Returns
A file token that can be used to send the image in a message.
session.uploadVideo(data, metadata): Promise<FileToken>
Upload a video with video-specific metadata.
This is a variant of uploadFile used for videos.
Parameters
The binary video data. Usually a File.
Information about the video.
interface VideoFileMetadata
Returns
A file token that can be used to send the video in a message.
session.uploadVoice(data, metadata): Promise<FileToken>
Upload a voice recording with voice-specific metadata.
This is a variant of uploadFile used for voice recordings.
Parameters
The binary audio data. Usually a File.
Information about the voice recording.
interface VoiceRecordingFileMetadata
Returns
A file token that can be used to send the audio file in a message.
session.user(id): UserRef
Get a reference to a user.
The returned UserRef is part of the Data API, which is included in the Chat SDK. This is the entry-point for all Data API operations that affect a user globally, such as editing their name. You can use references to get, edit, and subscribe to your data.
Parameters
The ID of the user that you want to reference
Returns
A UserRef for the user with that ID
Usage
1const userRef = session.user("test");2userRef.createIfNotExists({ name: "Alice" });
The following methods remain supported for backward compatibility reasons. In new projects, we recommend that you use the suggested alternatives instead.
| off Deprecated | Used to stop listening to specific TalkJS session events. |
| on Deprecated | Listens for an event |
| registerDevice Deprecated | |
| syncThemeForLocalDev Deprecated | Used to configure TalkJS to use a legacy theme hosted on the same location as your application for development. |
| unregisterDevice Deprecated |
session.off("message", handler)
Used to stop listening to specific TalkJS session events.
Call this with the same eventType and handler to stop receiving events.
Parameters
Returns
session.off("desktopNotificationClicked", handler)
Used to stop listening to specific TalkJS session events.
Call this with the same eventType and handler to stop receiving events.
Parameters
Returns
session.on("message", handler)
Listens for an event
A "message" event is fired every time a message is sent or received by the current user (even if no TalkJS UI is visible). Your handler function is passed a Message object with some information about each message and its conversation.
For an example, see https://gist.github.com/eteeselink/607e585eb40be76f2ed150d4090e5261
Note that this event does not get triggered for conversations where the current user is a guest. It only applies to users who were added as participants.
Related method: off
Parameters
Returns
session.on("desktopNotificationClicked", handler)
Listens for an event
A "desktopNotificationClicked" event is fired every time a user clicks on a desktop notification generated by TalkJS.
When a user clicks on a notification, these things will happen:
1. The browser tab will be selected (note, this works in most browsers but cannot be guaranteed);
2. If you provided one or more "desktopNotificationClicked" handlers, they will be invoked in order;
3. If you did not, then the currently active inbox (if any) will jump to the conversation corresponding to the notification.
See also setDesktopNotificationEnabled and off
Parameters
Returns
session.registerDevice({ platform, pushRegistrationId, }): Promise<void>
Related method: Session.unregisterDevice
Note that you must ensure that the user exists in the TalkJS database before you call this method. The simplest way to do that is to call it after you mount a chatbox, inbox or popup.
This method will keep being supported, but for new projects, we recommend that you use setPushRegistration.
Registers mobile device, one user can be connected to one mobile device.
Parameters
Returns
session.syncThemeForLocalDev(path)
Used to configure TalkJS to use a legacy theme hosted on the same location as your application for development.
Tells TalkJS to use a theme hosted on the same location as your application (e.g. localhost:8000/). e.g. Call talkSession.syncThemeForLocalDev("/assets/css/talkjs-theme.css") just before you call createInbox or createChatbox. TalkJS will then use the specified file instead of using a theme created in the dashboard.
Parameters
The path to the legacy theme's CSS file
Returns
session.unregisterDevice(): Promise<void>
Related method: Session.registerDevice
This method will keep being supported, but for new projects, we recommend that you use unsetPushRegistration or clearPushRegistrations.
Unregisters mobile device, one user can be connected to one mobile device.
Returns
This object can notify you when the amount of unread conversations changes. You can't instantiate it - instead, get an instance via Session.unreads.
| onChange | Triggered when the list of unread conversations changes. |
| off Deprecated | Call this with the same |
| on Deprecated | A "change" event is fired on startup right after TalkJS loads, as well as every time the amount of unread conversations changed. The |
unreads.onChange(handler): Subscription
Triggered when the list of unread conversations changes.
A "change" event is fired on startup right after TalkJS loads, as well as every time the amount of unread conversations changed. The handler is invoked with an array of objects with limited information about each conversation, see UnreadConversation.
Note that conversations where the user is a guest do not keep track of unread messages. This is only done for users who are added as participants.
Parameters
Returns
The following methods remain supported for backward compatibility reasons. In new projects, we recommend that you use the suggested alternatives instead.
| off Deprecated | Call this with the same |
| on Deprecated | A "change" event is fired on startup right after TalkJS loads, as well as every time the amount of unread conversations changed. The |
unreads.off("change", handler)
Call this with the same eventType and handler that you used for on to stop receiving events.
Related methods: on
Parameters
Returns
unreads.on("change", handler)
A "change" event is fired on startup right after TalkJS loads, as well as every time the amount of unread conversations changed. The handler is invoked with an array of objects with limited information about each conversation, see UnreadConversation.
Note that conversations where the user is a guest do not keep track of unread messages. This is only done for users who are added as participants.
Related methods: off
Parameters
Returns
Used as part of Unreads.on.
The ConversationData of the unread conversation.
Always identical to lastMessage.conversation, which is maintained for compatibility reasons.
interface ConversationData
Contains custom metadata for the conversation if it was set using ConversationBuilder.custom.
Set any property to null to delete the existing value (if any). When omitted or undefined, the existing value remains unchanged. When sending custom: null all properties and values will be removed.
The ID of the conversation
A map of the access rights for the participants in this conversation.
This property is not guaranteed to be complete. It always includes the current user, but does not always list other participants.
Specifically, ConversationData returned from the following functions will only include the current user: Session.onMessage, Session.onDesktopNotificationClicked, Session.unreads.onChange. In all other cases, this field contains every participant in the conversation.
Note on guest access: This field indicates a user's access as a participant. Guests always have "ReadWrite" access and are not included in this map
Contains the URL of a photo that was set using ConversationBuilder.subject.
Contains the conversation subject if it was set using ConversationBuilder.subject.
One or more welcome messages that will display to the user as a SystemMessage
Contains the last Message for this conversation.
The number of unread messages in this conversation.
Note: Conversations with last activity before 15 June 2023 will have unreadMessageCount value set to 0 on initial load. It will be properly set after the next refresh
Sent by Session.onDesktopNotificationClicked when a user clicks on a browser notification.
A TalkJS message, used as part of Session.onMessage
Specifies if if the message is media (file), text or a shared location
Only given if the message's type equals "media". An object with the URL and filesize (in bytes) of the given file. Attachment dimensions (in px) are sometimes available for media file attachments, used to set the size of the thumbnail before loading, to prevent content shift when loading media on slower connections.
Contains the message's content
Contains the ConversationData that the message belongs to.
Custom metadata that is stored with the conversation
Set any property to null to delete the existing value (if any). When omitted or undefined, the existing value remains unchanged.
The message's ID.
'true' if the message was sent by the current user.
Only given if the message's type equals "location". An array of two numbers which represent the longitude and latitude of this location, respectively. Only given if this message is a shared location. For example, [51.481083, -3.178306].
Determines how this message was sent: respectively, Via a web browser (or mobile Webview), via the REST API, via reply-to-email, or using the import API.
'true' if the message has been read, 'false' has not been seen yet
The User that sent the message
The senderID (userID) for the person that sent the message
UNIX timestamp specifying when the message was sent (UTC, in milliseconds)
Sent by Session.onBrowserPermissionNeeded when a browser permission dialog is about to be shown to the user.
| preventDefault | Cancel whatever user action caused the permission to be requested. |
The type of permission requested.
Note that more possible values may be added in the future, so make sure your handler can deal with unknown permission types gracefully.
browserPermissionNeededEvent.preventDefault()
Cancel whatever user action caused the permission to be requested.
For example, if a user wants to share their location for the first time so that this event is triggered, then if you call preventDefault(), no permission will be requested from the browser, the location sharing will be cancelled, and TalkJS will continue as if the location sharing button had not been clicked at all.
This may be useful if you're using this event to show custom UI elements that nudge users towards granting permission, and this UI has a "cancel" button.
Returns
Sent by Session.onBrowserPermissionDenied when the user tried to do an action that require explicit browser permission, but it was denied.
The type of permission that was denied.
Note that more possible values may be added in the future, so make sure your handler can deal with unknown permission types gracefully.
A string that is one of "notifications" | "microphone" | "geolocation".
Used in BrowserPermissionNeededEvent and BrowserPermissionDeniedEvent
Note that more possible values may be added in the future, so make sure your handler can deal with unknown permission types gracefully.