Inbox

interface Inbox

The main messaging UI. Chats on the left, messages on the right. Create an Inbox through Session​.createInbox and then call mount to show it.

Method Overview

createHtmlPanel

Puts custom HTML just above the message field.

destroy

Destroys the inbox and removes it from the DOM

mount

Renders the Inbox UI inside a DOM element on your page

onBlur

Triggers when focus moves out of the chat UI.

onConversationSelected

Triggers after a conversation is selected

onCustomConversationAction

Triggers when a user launches a custom action on a conversation within the TalkJS UI.

onCustomMessageAction

Triggers when a user launches a custom action on a message within the TalkJS UI.

onDesktopNotificationToggled

Triggers when the user toggles the "Desktop Notifications" toggle in the inbox conversation list header.

onFocus

Triggers when the chat UI is focussed.

onKeydown

Triggers a KeyEvent when the user presses a key.

onKeyup

Triggers a KeyEvent when the user releases a key.

onLeaveConversation

Triggers when the user clicks on the "Leave conversation" action

onMarkConversationAsUnread

Triggers when the user clicks on the "Mark as unread" action

onSelectConversation

Triggers when a user clicks a conversation in the conversation list.

onSendMessage

Triggers when the user sends a message using the TalkJS UI

onTranslationToggled

Triggers when the user toggles message translation in the TalkJS UI.

select

Switches the active conversation.

sendFile

Upload a file attachment to the currently active conversation.

sendLocation

Send the user's current location to the currently active conversation.

setFeedFilter

Controls which conversations are shown in the conversation feed

setHighlightedWords

Highlights certain words in messages

setMessageFilter

Used to control which messages are shown in the message list

setPresence

Sets metadata for the current session.

setTranslationEnabledDefault

Enable/disable translation by default.

setTranslationEnabledFor­Conversation

Enable or disable translation for a conversation.

off Deprecated

Stops emitting events registered with on.

on Deprecated

Listens for an event.

toggleDesktopNotifications Deprecated

Toggles desktop notifications

Properties

currentConversation
: ConversationData | null

The conversation currently shown in the UI.

This field is null when the UI does not currently show a conversation (eg because null was passed to select, it's an Inbox with only conversation list visible, or the selected conversation could not be found).

This field will always be equal to conversation in the onConversationSelected event.

Also note that because the onSelectConversation event is emitted before the new conversation is actually shown, this field will still reflect the previous conversation at that point.

isAlive
: boolean

Whether the object is active and in a valid state.

When false, calling methods on this instance will throw errors.

This field is false when destroy has been called in the past. It is also false if Session​.destroy has been called, because destroying a session destroys all its UI widgets.

Finally, an instance may also be considered if its previously mounted iframe has been removed from the DOM by some external library.

Once this instance has been destroyed, you cannot revive it. Instead, create a new instance.

messageField
: MessageField

Encapsulates the message entry field tied to the currently selected conversation.

createHtmlPanel

inbox.createHtmlPanel(options): Promise<HtmlPanel>

Puts custom HTML just above the message field.

Using HTML Panels, you can extend TalkJS UIs to have anything from credit card payments to lead collection forms, or, for instance, to show the product details of a marketplace transaction between your users. See our HTMLPanels documentation for more info.

Parameters

interface HtmlPanelOptions

url
: string

Required. URL you want to load inside the HTML panel. Url can be absolute ("https://www.example.com/register-form.html") or relative ("register-form.html"). We recommend using same origin pages to have better control of the page. Learn more about HTML Panels and same origin pages here.

conversation (optional)
: Conversation | ConversationBuilder | string

Either a Conversation object (as returned from getOrCreateConversation) or the id field of a conversation (which you may have stored in your database). If given the HTML panel called will only show up for that conversation.

height (optional)
: number

Optional, defaults to 100 (px).

show (optional)
: boolean

Optional, defaults to true. Set false if you don't want the HTML panel to be shown after createHtmlPanel is called. You can change the visibility of the HTML panels by calling .hide() or .show() on the HtmlPanel instance returned by createHtmlPanel's promise.

Returns

Promise<HtmlPanel>

destroy

inbox.destroy()

Destroys the inbox and removes it from the DOM

Destroys the inbox, removes it from the DOM and removes all event listeners it has running. Call this before removing the inbox container from the DOM.

Returns

void

mount

inbox.mount(container): Promise<void>

Renders the Inbox UI inside a DOM element on your page

The container element specified by container must either be a DOM Element (as returned by e.g. document.getElementById) or a JQuery object with a single element.

Parameters

container
: HTMLElement | null

Returns

Promise<void>

onBlur

inbox.onBlur(handler): Subscription

Triggers when focus moves out of the chat UI.

Emits an event when the user clicks/taps anywhere outside the chat UI.

Parameters

handler
: () => void

Returns

Subscription

onConversationSelected

inbox.onConversationSelected(handler): Subscription

Triggers after a conversation is selected

This event is emitted in 4 situations:

1. When the Inbox loads;

2. When the user clicks on a conversation in the feed;

3. When something in your code calls select

4. When the Inbox is shown in mobile view, and the user clicks the < Inbox button.

Note that the event's conversation field will be null when the inbox loads (and the user has no conversations), when calling select with null to deselect any conversation, and in case 4 above.

Parameters

handler
: (event: ConversationSelectedEvent) => void

Returns

Subscription

onCustomConversationAction

inbox.onCustomConversationAction(action, handler): Subscription

Triggers when a user launches a custom action on a conversation within the TalkJS UI.

To set up a custom action, you can either create it on the "Chat UI" page in your dashboard or add an action button to the ChatHeader, MessageField, ConversationListHeader or ConversationListItem components of your theme in the Theme Editor, which you can access from the "Themes" page in your dashboard. If an action is allowed on a particular conversation, it'll show up in that conversation's action menu. The name you specify when setting up the action, is also the name you should pass in here (case sensitive). The event you get contains information about the conversation on which the action was called, including its ID, so you can look it up later via our REST API.

Parameters

action
: string

Optional. The action you want to listen for. Omit to listen for any action.

handler
: (event: ConversationActionEvent) => void

The handler to be called

Returns

Subscription

A subscription you can use to unsubscribe.

onCustomMessageAction

inbox.onCustomMessageAction(action, handler): Subscription

Triggers when a user launches a custom action on a message within the TalkJS UI.

To set up a custom action, you can either create it on the "Chat UI" page in your dashboard, add an action button to your messages, or add an action button to the UserMessage, SystemMessage, or MessageBody components of your theme in the Theme Editor, which you can access from the "Themes" page in your dashboard. If an action is allowed on a particular message, it'll show up in that message's action menu. The name you specify when setting up the action, is also the name you should pass in here (case sensitive). The event you get contains information about the message on which the action was called, including its ID, so you can look it up later via our REST API.

Parameters

action
: string

Optional. The action you want to listen for. Omit to listen for any action.

handler
: (event: MessageActionEvent) => void

The handler to be called

Returns

Subscription

A subscription you can use to unsubscribe.

onDesktopNotificationToggled

inbox.onDesktopNotificationToggled(handler): Subscription

Triggers when the user toggles the "Desktop Notifications" toggle in the inbox conversation list header.

Parameters

handler
: (event: DesktopNotificationToggledEvent) => void

Returns

Subscription

onFocus

inbox.onFocus(handler): Subscription

Triggers when the chat UI is focussed.

Parameters

handler
: () => void

Returns

Subscription

onKeydown

inbox.onKeydown(handler): Subscription

Triggers a KeyEvent when the user presses a key.

See onKeyup for more details.

Parameters

handler
: (event: KeyEvent) => void

Returns

Subscription

onKeyup

inbox.onKeyup(handler): Subscription

Triggers a KeyEvent when the user releases a key.

This event is only emitted when ChatboxOptions​.captureKeyboardEvents is enabled. In that case, it is emitted for every keypress, including regular letters typed into text fields.

Note that there's a notorious system limitation on macOS: metaKey is not set in keyup events when hitting keystrokes (eg Cmd+p). Consider using onKeydown if you need to support Cmd.

event.isInputFocused is true when a TalkJS input area is focused (eg the message field, the search box, or adjacent buttons). When this is the case, keypresses are likely to cause changes inside the chat UI. We recommend that you discard these events except when implementing global shortcuts that should take effect regardless of whether the user is typing a message or otherwise interacting with the chat UI using the keyboard.

Note: by design, the TalkJS UI does not handle special multi-key shortcuts other than those provided by the user's device (eg ctrl+v for paste). This means that it is usually safe to assign special behavior to unused keyboard shortcuts with one or more modifier keys (like alt, shift or ctrl), even when isInputFocused is true.

All other event fields are the same as the corresponding fields in the browser's KeyboardEvent.

Example

1myChatbox.onKeyup(event => {
2 if(event.shiftKey || event.altKey || event.metaKey) {
3 return;
4 }
5
6 // let the 1 key switch to our app's main panel, except if the user is typing
7 if(!event.isInputFocused && event.key === "1") {
8 myApp.selectMainPanel();
9 }
10
11 // quit if the user hits ctrl+q, irrespective of whether they're typing.
12 if(event.ctrlKey && event.key === "q") {
13 myApp.quit();
14 }
15});

Parameters

handler
: (event: KeyEvent) => void

Returns

Subscription

onLeaveConversation

inbox.onLeaveConversation(handler): Subscription

Triggers when the user clicks on the "Leave conversation" action

This event triggers *before* the user actually leaves the conversation. You can call event.preventDefault() to disallow the user from actually leaving.

This event only triggers when the user performs a Leave action from inside the chat UI. Notably, when a user leaves the conversation through other means (for example, they're removed from the conversation using the REST API), this event does not trigger.

Parameters

handler
: (event: LeaveConversationEvent) => void

Returns

Subscription

onMarkConversationAsUnread

inbox.onMarkConversationAsUnread(handler): Subscription

Triggers when the user clicks on the "Mark as unread" action

This event triggers *before* the user actually marks the conversation as unread. You can call event.preventDefault() to disallow the user from actually marking it as unread.

This event only triggers when the user performs a "Mark as unread" action from inside the chat UI. Notably, when a user marks the conversation as unread through other means (for example, via the REST API), this event does not trigger.

Parameters

handler
: (event: MarkConversationAsUnreadEvent) => void

Returns

Subscription

onSelectConversation

inbox.onSelectConversation(handler): Subscription

Triggers when a user clicks a conversation in the conversation list.

This event is triggered *before* a conversation is selected. You can prevent the conversation from being actually selected by calling event.preventDefault().

Parameters

handler
: (event: SelectConversationEvent) => void

Returns

Subscription

onSendMessage

inbox.onSendMessage(handler): Subscription

Triggers when the user sends a message using the TalkJS UI

Parameters

handler
: (event: SendMessageEvent) => void

Returns

Subscription

onTranslationToggled

inbox.onTranslationToggled(handler): Subscription

Triggers when the user toggles message translation in the TalkJS UI.

Parameters

handler
: (event: TranslationToggledEvent) => void

Returns

Subscription

select

inbox.select(conversation, params): Promise<void>

Switches the active conversation.

conversation can be either a ConversationBuilder object or a TalkJS conversation id. Passing null means that the conversation will be de-selected in the UI and the message list will disappear. Passing undefined means that the last conversation (or "no chats yet" page if there are no other conversations) will be rendered in the message list component.

Parameters

conversation
: string | Conversation | ConversationBuilder | null | undefined
params (optional)
: SelectConversationOptions
interface SelectConversationOptions

Selection parameters.

asGuest (optional)
: boolean

can be used to select the conversation as a guest, with limited functions

messageId (optional)
: string

can be used to scroll to a specific message

Returns

Promise<void>

A promise that resolves once the new conversation has been selected.

sendFile

inbox.sendFile(file): Promise<void>

Upload a file attachment to the currently active conversation.

The behaviour of this method is similar to if the user clicked the attachment button, in that the confirmation dialog is shown to the user.

Ensure that the File object's name property has an appropriate file extension.

Parameters

file
: File

The File object to be uploaded.

Returns

Promise<void>

sendLocation

inbox.sendLocation(): Promise<void>

Send the user's current location to the currently active conversation.

The behaviour of this method is identical to the user clicking the location button in message field i.e the confirmation dialog is shown.

Note: If the user had not previously granted location access to your website, calling this method will trigger the browser's popup asking them for permission to access their location. The user's location will only be shared if they allow.

Returns

Promise<void>

setFeedFilter

inbox.setFeedFilter(filter)

Controls which conversations are shown in the conversation feed

Lets you filter conversations in the conversation list, depending on access level, custom conversation attributes or message read status.

See ConversationPredicate for all available options.

You can also set the filter in Session​.createInbox using InboxOptions​.feedFilter.

Parameters

A predicate object that controls which conversations are shown.

Returns

void

setHighlightedWords

inbox.setHighlightedWords(words)

Highlights certain words in messages

The TalkJS search feature includes the ability to highlight certain words in messages. Call this method to highlight certain words without having the user invoke the search feature. Call again with an empty array to disable highlighting.

Note: like the search feature, this option only works on the Growth plan and up.

Also see ChatboxOptions​.highlightedWords

Parameters

words
: string[]

Returns

void

setMessageFilter

inbox.setMessageFilter(filter)

Used to control which messages are shown in the message list

Lets you filter messages 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.

Example

1// only show messages sent by users with role "admin"
2chatbox.setMessageFilter({
3 sender: {
4 role: ["==", "admin"],
5 }
6});

Parameters

A predicate object that controls which messages are shown.

Returns

void

setPresence

inbox.setPresence(presence)

Sets metadata for the current session.

Note: If you want to mount UI that is already hidden, set presence when creating the UI or call setPresence({ visible: false }) before calling mount.

Also, important to note, is that the Popup internally calls this method when a user opens or closes it. visible is set to true or false respectively.

Parameters

presence
: UserPresence
interface UserPresence

custom (optional)
: CustomData

This is an additional parameter to store the custom fields that you may want to use in the REST API call.

Set any property to null to delete the existing value (if any). When omitted or undefined, the existing value remains unchanged.

visible (optional)
: boolean

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.

When omitted or undefined, the existing value remains unchanged.

Returns

void

setTranslationEnabledDefault

inbox.setTranslationEnabledDefault(enabled)

Enable/disable translation by default.

This setting is applied to any conversation for which you haven't set a specific value.

Parameters

enabled
: boolean | "auto"

Whether conversations should be translated by default or not. Pass "auto" to enable translation for conversations with users with different locales.

Returns

void

setTranslationEnabledForConversation

inbox.setTranslationEnabledForConversation(conversation, enabled)

Enable or disable translation for a conversation.

Parameters

conversation
: string | ConversationBuilder

The conversation for which this should be set. If not specified, the setting will be applied to the currently selected conversation.

enabled
: boolean

Whether translation should be enabled

Returns

void

Deprecated Methods

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

Method Overview

off Deprecated

Stops emitting events registered with on.

on Deprecated

Listens for an event.

toggleDesktopNotifications Deprecated

Toggles desktop notifications

Deprecated off (1)

inbox.off("selectConversation", handler)

Stops emitting events registered with on.

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

Parameters

eventType
: "selectConversation"
handler
: (event: SelectConversationEvent) => void

The handler function must be the same handler function that was passed to on("focus")

Returns

void

Deprecated off (2)

inbox.off("conversationSelected", handler)

Stops emitting events registered with on.

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

Parameters

eventType
: "conversationSelected"
handler
: (event: ConversationSelectedEvent) => void

The handler function must be the same handler function that was passed to on("focus")

Returns

void

Deprecated off (3)

inbox.off("desktopNotificationToggled", handler)

Stops emitting events registered with on.

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

Parameters

eventType
: "desktopNotificationToggled"
handler
: (event: DesktopNotificationToggledEvent) => void

The handler function must be the same handler function that was passed to on("focus")

Returns

void

Deprecated off (4)

inbox.off("focus", handler)

Stops emitting events registered with on.

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

Parameters

eventType
: "focus"
handler
: () => void

The handler function must be the same handler function that was passed to on("focus")

Returns

void

Deprecated off (5)

inbox.off("blur", handler)

Stops emitting events registered with on.

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

Parameters

eventType
: "blur"
handler
: () => void

The handler function must be the same handler function that was passed to on("focus")

Returns

void

Deprecated off (6)

inbox.off("sendMessage", handler)

Stops emitting events registered with on.

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

Parameters

eventType
: "sendMessage"
handler
: (event: SendMessageEvent) => void

The handler function must be the same handler function that was passed to on("focus")

Returns

void

Deprecated off (7)

inbox.off("translationToggled", handler)

Stops emitting events registered with on.

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

Parameters

eventType
: "translationToggled"
handler
: () => void

The handler function must be the same handler function that was passed to on("focus")

Returns

void

Deprecated off (8)

inbox.off("keyup", handler)

Stops emitting events registered with on.

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

Parameters

eventType
: "keyup"
handler
: (event: KeyEvent) => void

The handler function must be the same handler function that was passed to on("focus")

Returns

void

Deprecated on (1)

inbox.on("selectConversation", handler)

Listens for an event.

Deprecated. Please use onSelectConversation instead.

Parameters

eventType
: "selectConversation"
handler
: (event: SelectConversationEvent) => void

Returns

void

Deprecated on (2)

inbox.on("conversationSelected", handler)

Listens for an event.

Deprecated. Please use onConversationSelected instead.

Parameters

eventType
: "conversationSelected"
handler
: (event: ConversationSelectedEvent) => void

Returns

void

Deprecated on (3)

inbox.on("desktopNotificationToggled", handler)

Listens for an event.

Deprecated. Please use onDesktopNotificationToggled instead.

Parameters

eventType
: "desktopNotificationToggled"
handler
: (event: DesktopNotificationToggledEvent) => void

Returns

void

Deprecated on (4)

inbox.on("sendMessage", handler)

Listens for an event.

Deprecated. Please use onSendMessage instead.

Parameters

eventType
: "sendMessage"
handler
: (event: SendMessageEvent) => void

Returns

void

Deprecated on (5)

inbox.on("focus", handler)

Listens for an event.

Deprecated. Please use onFocus instead.

Parameters

eventType
: "focus"
handler
: () => void

Returns

void

Deprecated on (6)

inbox.on("blur", handler)

Listens for an event.

Deprecated. Please use onBlur instead.

Parameters

eventType
: "blur"
handler
: () => void

Returns

void

Deprecated on (7)

inbox.on("translationToggled", handler)

Listens for an event.

Deprecated. Please use translationToggled instead.

Parameters

eventType
: "translationToggled"
handler
: (event: TranslationToggledEvent) => void

Returns

void

Deprecated on (8)

inbox.on("keyup", handler)

Listens for an event.

Deprecated. Please use onKeyup instead.

Parameters

eventType
: "keyup"
handler
: (event: KeyEvent) => void

Returns

void

Deprecated toggleDesktopNotifications

inbox.toggleDesktopNotifications(isEnabled)

Toggles desktop notifications

This method will keep being supported, but for new projects, we recommend that you use Session​.setDesktopNotification­Enabled.

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.

Deprecated. Please use Session​.setDesktopNotification­Enabled instead.

Parameters

isEnabled
: boolean

Returns

void