Session

onBrowserPermissionNeeded

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

handler

: ( event: BrowserPermissionNeededEvent ) => Promise<any> | void

Returns

onDesktopNotificationClicked

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.

Parameters

handler

: (event: DesktopNotificationClickedEvent) => void

Returns

onMessage

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

handler

: (message: Message) => void

Returns

setDesktopNotificationEnabled

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

isEnabled

: boolean

Whether notifications should be enabled.

{ alertOnFailure } (optional)

: { alertOnFailure?: boolean }

Returns

Promise<void>

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.

setPushRegistration

session.setPushRegistration({
        provider: "fcm" | "apns";
        pushRegistrationId: string;
    }): Promise<void>

Registers a single mobile device, as one user can be connected to multiple mobile devices.

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

{ provider, pushRegistrationId, }

: { provider: "fcm" | "apns" pushRegistrationId: string }

Returns

Promise<void>

unsetPushRegistration

session.unsetPushRegistration({
        provider: "fcm" | "apns";
        pushRegistrationId: string;
    }): Promise<void>

Unregisters a single mobile device, as one user can be connected to multiple mobile devices.

Related methods: setPushRegistration clearPushRegistrations

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

{ provider, pushRegistrationId, }

: { provider: "fcm" | "apns" pushRegistrationId: string }

Returns

Promise<void>

Deprecated Methods

The following methods remain supported for backward compatibility reasons. In new projects, we recommend that you use the suggested alternatives instead.

getOrStartConversation Deprecated
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

Deprecated getOrStartConversation

This method has 2 overloads

session.getOrStartConversation(other, options): Conversation

Deprecated. This method will keep being supported, but for new projects, we recommend that you use getOrCreateConversation.

Parameters

other

: User

A User object that identifies the person to converse with. The user is uniquely identified by their id; all other fields (name, photo etc) are overwritten in the TalkJS database each time they change.

options (optional)

: GetOrStartOptionsA

Options used for getOrStartConversation

interface GetOrStartOptionsA

custom (optional)

: { [name: string]: string }

Additional parameter to store the custom fields, that you want to use in the email template. E.g. custom.specialToken

photoUrl (optional)

: string

Photo to be used for this conversation in the TalkJS UI.

subject (optional)

: string

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

welcomeMessages (optional)

: string[]

Returns

Conversation

a Conversation object that encapsulates a conversation between me (given in the constructor) and other.

session.getOrStartConversation(conversationId, options): Conversation

Deprecated. This method will keep being supported, but for new projects, we recommend that you use getOrCreateConversation.

Parameters

conversationId

: string

A unique identifier for this conversation. Any user with access to this ID can join this conversation.

options (optional)

: GetOrStartOptionsB

Options used for getOrStartConversation

interface GetOrStartOptionsB

custom (optional)

: { [name: string]: string }

Additional parameter to store the custom fields, that you want to use in the email template. E.g. custom.specialToken

participants

: Array<User>

photoUrl (optional)

: string

Photo to be used for this conversation in the TalkJS UI.

subject (optional)

: string

Returns

Conversation

a Conversation object that encapsulates a conversation between me (given in the constructor) and zero or more other participants.

Deprecated off

This method has 2 overloads

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.

Deprecated. Please use the Subscription.unsubscribe method on the object returned by onMessage instead.

Parameters

eventType

: "message"

handler

: (message: Message) => void

Returns

void

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.

Deprecated. Please use the Subscription.unsubscribe method on the object returned by onDesktopNotificationClicked instead.

Parameters

eventType

: "desktopNotificationClicked"

handler

: (event: DesktopNotificationClickedEvent) => void

Returns

void

Deprecated on

This method has 2 overloads

session.on("message", handler)

Listens for an event

For an example, see

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

Deprecated. Please use onMessage instead.

Parameters

eventType

: "message"

handler

: (message: Message) => void

Returns

void

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

Deprecated. Please use onDesktopNotificationClicked instead.

Parameters

eventType

: "desktopNotificationClicked"

handler

: (event: DesktopNotificationClickedEvent) => void

Returns

void

Deprecated registerDevice

session.registerDevice({
        platform: "ios" | "android";
        pushRegistrationId: string;
    }): 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.

Deprecated. 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

{ platform, pushRegistrationId, }

: { platform: "ios" | "android" pushRegistrationId: string }

Returns

Promise<void>

Deprecated syncThemeForLocalDev

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.

Deprecated. We recommend switching to Custom Themes, which are substantially more powerful and do not have a practical need for a method like this.

Parameters

path

: string

The path to the legacy theme's CSS file

Returns

void

Deprecated unregisterDevice

session.unregisterDevice(): Promise<void>

Related method: Session.registerDevice

Deprecated. 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.

Parameters

None.

Returns

Promise<void>

interface Unreads

This object can notify you when the amount of unread conversations changes. You can't instantiate it - instead, get an instance via Session.unreads.

Method Overview

onChange	Triggered when the list of unread conversations changes.
off Deprecated	Call this with the same `eventType` and `handler` that you used for `on` to stop receiving events.
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 `handler` is invoked with an array of objects with limited information about each conversation, see UnreadConversation.

onChange

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

handler

: (unreadConversations: UnreadConversation[]) => void

Returns

Deprecated Methods

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 `eventType` and `handler` that you used for `on` to stop receiving events.
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 `handler` is invoked with an array of objects with limited information about each conversation, see UnreadConversation.

Deprecated off

unreads.off("change", handler)

Call this with the same eventType and handler that you used for on to stop receiving events.

Related methods: on

Deprecated. Please use the Subscription.unsubscribe method on the object returned by onChange instead.

Parameters

eventType

: "change"

handler

: (unreadConversations: UnreadConversation[]) => void

Returns

void

Deprecated on

unreads.on("change", handler)

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

Deprecated. Please use onChange instead.

Parameters

eventType

: "change"

handler

: (unreadConversations: UnreadConversation[]) => void

Returns

void

interface UnreadConversation

Used as part of Unreads.on.

Properties

conversation

The ConversationData of the unread conversation.

Always identical to lastMessage.conversation, which is maintained for compatibility reasons.

interface ConversationData

custom

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.

id

: string

The ID of the conversation

participants

: Record< string, {access: "Read" | "ReadWrite" }>

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

photoUrl

: string | null

Contains the URL of a photo was set using ConversationBuilder.subject.

subject

: string | null

Contains the conversation subject if it was set using ConversationBuilder.subject.

welcomeMessages

: Array<string> | null

One or more welcome messages that will display to the user as a SystemMessage

lastMessage

: Message

Contains the last Message for this conversation.

interface Message

A TalkJS message, used as part of Session.onMessage

attachment

: { url: string size: number dimensions?: {width: number height: number }} | null

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 image and video attachments, used to set the size of the thumbnail before loading, to prevent content shift when loading media on slower connections.

body

: string

Contains the message's content

conversation

Contains the ConversationData that the message belongs to.

custom

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.

id

: string

The message's ID.

isByMe

: boolean

'true' if the message was sent by the current user.

location

: [number, number] | null

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.

Example:


[51.481083, -3.178306]

origin

: string

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.

read

: boolean

'true' if the message has been read, 'false' has not been seen yet

sender

: UserData | null

The User that sent the message

senderId

: string | null

The senderID (userID) for the person that sent the message

timestamp

: number

UNIX timestamp specifying when the message was sent (UTC, in milliseconds)

type

: "media" | "text" | "location"

Specifies if if the message is media (file), text or a shared location

unreadMessageCount

: number

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

interface DesktopNotificationClickedEvent

Sent by Session.onDesktopNotificationClicked when a user clicks on a browser notification.

Properties

conversation

interface ConversationData

custom

Contains custom metadata for the conversation if it was set using ConversationBuilder.custom.

id

: string

The ID of the conversation

participants

: Record< string, {access: "Read" | "ReadWrite" }>

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.

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

photoUrl

: string | null

Contains the URL of a photo was set using ConversationBuilder.subject.

subject

: string | null

Contains the conversation subject if it was set using ConversationBuilder.subject.

welcomeMessages

: Array<string> | null

One or more welcome messages that will display to the user as a SystemMessage

interface Message

A TalkJS message, used as part of Session.onMessage

Properties

attachment

: { url: string size: number dimensions?: {width: number height: number }} | null

body

: string

Contains the message's content

conversation

Contains the ConversationData that the message belongs to.

interface ConversationData

custom

Contains custom metadata for the conversation if it was set using ConversationBuilder.custom.

id

: string

The ID of the conversation

participants

: Record< string, {access: "Read" | "ReadWrite" }>

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.

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

photoUrl

: string | null

Contains the URL of a photo was set using ConversationBuilder.subject.

subject

: string | null

Contains the conversation subject if it was set using ConversationBuilder.subject.

welcomeMessages

: Array<string> | null

One or more welcome messages that will display to the user as a SystemMessage

custom