A session represents a user's active browser tab. It also authenticates your app with TalkJS.

Methods

Constructor

Creates a TalkJS Session.

createChatbox

Creates a Chatbox UI

createInbox

Creates an Inbox UI

createPopup

Creates a Popup UI

getOrCreateConversation

A method used to either fetch or create a conversation.

getOrStartConversation

Deprecated.

hasValidCredentials

Verifies whether the appId is valid.

off

Used to stop listening to specific TalkJS session events

on

Used to listen to TalkJS session events

registerDevice

Registers mobile device, one user can be connected to one mobile device.

setDesktopNotificationEnabled

Sets desktop notification on or off.

syncThemeForLocalDev

Used to configure TalkJS to use a theme hosted on the same location as your application for development.

unregisterDevice

Unregisters mobile device, one user can be connected to one mobile device.

Properties

appId
string
Your TalkJS AppId that can be found your TalkJS dashboard.
me
User
The TalkJS User associated with the current user in your application.
unreads
Unreads
Holds information about unread conversations. Lets your app be notified when the active user receives a new message.

Method Details

Constructor

new Session(options)

Creates a TalkJS Session.

Parameters

options
SessionOptions

SessionOptions

appId
string
Your app's unique TalkJS id. Get it from the dashboard.
me
User
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. Alternatively, only pass a user ID (as a string) if you are certain that the user object exists.
signature
string
optional
If you use Identitiy verification make sure you generate and use a signature.

createChatbox

session.createChatbox(selectedConversation, options)
Creates a Chatbox UI

The Chatbox is a slimmer version of the Inbox. It shows a single conversation, without a means to switch between conversations. You typically want to call the mount method after creating the Chabox to make it visible on your app.

Call createChatbox on any page you want to show a chatbox of a single conversation.

Parameters

selectedConversation
Conversation | ConversationBuilder

Select the conversation to show in the UI.

options
ChatboxOptions
optional

Optional. Use these to finetune the behavior of the Chatbox.

ChatboxOptions

chatSubtitleMode
"subject" | "participants" | null
optional
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 ChatboxOptions.chatTitleMode and InboxOptions.feedConversationTitleMode)
chatTitleMode
"subject" | "participants"
optional
Controls what text appears in the chat title, in the header above the messages. Defaults to "participants". (also see ChatboxOptions.chatSubtitleMode and InboxOptions.feedConversationTitleMode)
dir
"rtl" | "ltr"
optional
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".
messageFilter
MessageFilter
optional
Used to control which messages are shown in the message list, depending on a type, origin or custom message attributes. See Other_interfaces.MessageFilter for all available options. You can also modify the filter on the fly using [[UiBox.setMessageFilter]].
messageSuggestion
string
optional
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".
showChatHeader
boolean
optional
Used to control if the Chat Header is displayed in the UI. Defaults to true.
thirdparties
ThirdPartyOptions
optional
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.

Returns

Chatbox

createInbox

session.createInbox(options)
Creates an Inbox UI

The Inbox is the main UI component of TalkJS. It shows a user's conversation history and it allows them to write messages. You typically want to call the mount method after creating the Inbox to make it visible on your app.

Call createInbox on the messaging page of your app.

Parameters

options
InboxOptions
optional

Optional. Use these to finetune the behavior of the Inbox.

InboxOptions

feedConversationTitleMode
"participants" | "subject" | "auto"
optional
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 ChatboxOptions.chatSubtitleMode and ChatboxOptions.chatTitleMode)
feedFilter
ConversationFilter
optional
Used to control which conversations are shown in the conversation feed, depending on access level, custom conversation attributes or message read status. See ConversationFilter for all available options. You can also modify the filter on the fly using Inbox.setFeedFilter.
selected
Conversation | ConversationBuilder | string | null
optional
Makes the inbox start up with the given Conversation. Can be passed a value of the type ConversationBuilder (returned by getOrCreateConversation), the string value of the conversation id or null.
showFeedHeader
boolean
optional
Controls if the feed header containing the toggle to enable desktop notifications is shown. Defaults to true.
useBrowserHistory
boolean
optional
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).

Returns

Inbox

createPopup

session.createPopup(conversation, options)
Creates a Popup UI

The Popup is a beautiful, well positioned box containing a conversation. It shows a single conversation, without a means to switch between conversations. 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

conversation
Conversation | ConversationBuilder

The conversation to show on the UI.

options
PopupOptions
optional

PopupOptions

keepOpen
boolean
optional
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 true.
launcher
"close-only" | "always" | "never"
optional
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 "close-only".
showCloseInHeader
boolean | "auto"
optional
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.

Returns

Popup

getOrCreateConversation

session.getOrCreateConversation(conversationId)
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

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

Returns

ConversationBuilder

getOrStartConversation

This method has 2 overloads:
session.getOrStartConversation(other, options)

Deprecated. This method will keep being supported, but for new projects, we recommend that you use Session.getOrCreateConversation. Returns a Conversation object that encapsulates a conversation between me (given in the constructor) and other.

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
GetOrStartOptionsA

Options used for getOrStartConversation

Returns

Conversation
session.getOrStartConversation(conversationId, options)

Deprecated. This method will keep being supported, but for new projects, we recommend that you use Session.getOrCreateConversation. Returns a Conversation object that encapsulates a conversation between me (given in the constructor) and zero or more other participants.

Parameters

conversationId
string

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

options
GetOrStartOptionsB

Options used for getOrStartConversation

Returns

Conversation

hasValidCredentials

session.hasValidCredentials()
Verifies whether the appId is valid.

Returns a Promise of a boolean, never rejects.

Parameters

None.

Returns

Promise<boolean>

off

session.off(eventType, handler)
Used to stop listening to specific TalkJS session events

Call this with the same eventType and handler to stop receiving events.

Related methods: Session.on

Parameters

eventType
"message"
handler
(message: Message) => void

Returns

void

on

session.on(eventType, handler)
Used to listen to TalkJS session events

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

Related method: Session.off

Parameters

eventType
"message"
handler
(message: Message) => void

Returns

void

registerDevice

session.registerDevice({ platform, pushRegistrationId })
Registers mobile device, one user can be connected to one mobile device.

Related method: Session.unregisterDevice

Parameters

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

Returns

Promise<void>

setDesktopNotificationEnabled

session.setDesktopNotificationEnabled(isEnabled, { alertOnFailure })
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.

Parameters

isEnabled
boolean
{ alertOnFailure }
{ alertOnFailure?: boolean; }
optional

Returns

Promise<void>

a promise that'll resolve if the change succeeds, but rejects if anything goes wrong. If anything goes wrong, the promise will be rejected with a Talk.Error, which has a codeproperty Possible values for it are:

- Talk.Error.Code.NOTIFICATIONS_PERMISSION_DENIED: The browser or the user didn't grant you permission to send notifications. - Talk.Error.Code.NOTIFICATIONS_NOT_SUPPORTED: The browser doesn't support desktop notifications.


syncThemeForLocalDev

session.syncThemeForLocalDev(path)
Used to configure TalkJS to use a 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

path
string

Returns

void

unregisterDevice

session.unregisterDevice()
Unregisters mobile device, one user can be connected to one mobile device.

Related method: Session.registerDevice

Parameters

None.

Returns

Promise<void>

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.

Methods

off

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

on

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.

Method Details

off

unreads.off(eventType, handler)
Call this with the same eventType and handler that you used for on to stop receiving events.

Related methods: Unreads.on

Parameters

eventType
"change"
handler
(messages: UnreadConversation[]) => void

Returns

void

on

unreads.on(eventType, 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.

Related methods: Unreads.off

Parameters

eventType
"change"
handler
(messages: UnreadConversation[]) => void

Returns

void

UnreadMessage

Not found

DesktopNotificationToggledEvent

This event is triggered when desktop notifications are toggled.

Properties

isEnabled
boolean
Boolean indicating if desktop Notifications are enabled or not

Message

A TalkJS message, used as part of Session.on

Properties

body
string
Contains the message's content
conversation
ConversationData
Contains the ConversationData that the message belongs to.

ConversationData

custom
CustomData
optional
Contains custom metadata for the conversation if it was set using ConversationBuilder.custom.
id
string
The ID of the conversation
photoUrl
string
optional
Contains the URL of a photo was set using ConversationBuilder.subject.
subject
string
optional
Contains the conversation subject if it was set using ConversationBuilder.subject.
topicId
string
optional

Deprecated. Please use ConversationBuilder.subject instead.

welcomeMessages
Array<string>
optional
One or more welcome messages that will display to the user as a SystemMessage
custom
CustomData
optional
isByMe
boolean
'true' if the message was sent by the current user.
origin
string
read
boolean
'true' if the message has been read, 'false' has not been seen yet
sender
User | null
The User that sent the message
senderId
string | null
The senderID (userID) for the person that sent the message
timestamp
number
The timestamp for the when the message was sent
type
"media" | "text" | "location"
Specifies if if the message is media (file), text or a shared location