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.

Methods

createHtmlPanel

HTML Panels allow you to place a HTML document in an iframe in your chats, just above the entry box.

destroy

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

mount

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

off

Used to stop listening to TalkJS events.

on("blur")

Triggers when the chat UI gets unfocused (i.e. the user clicks/taps anywhere outside it).

on("conversationSelected")

Triggers when a conversation is selected.

on("desktopNotificationToggled")

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

on("focus")

Triggers when the chat UI gets focused (i.e. the user clicks/taps anywhere inside it).

on("selectConversation")

Triggers when a user clicks a conversation in the feed. It's triggered *before* a conversation is selected. You can prevent the conversation from being actually selected by calling event.preventDefault().

on("sendMessage")

Triggers when the user sends a message using the TalkJS UI

on("translationTriggered")

Triggers when the user toggles translation in a conversation

select

Switches the active conversation the conversation.

setFeedFilter

Used to control which conversations are shown in the conversation feed, depending on access level, custom conversation attributes or message read status.

setHighlightedWords

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 in TalkJS Premium and up. Also see ChatboxOptions.highlightedWords

setMessageFilter

Used to control which messages are shown in the message list, depending on a type, origin or custom message attributes.

setPresence

Sets metadata for the current session.

setTranslationEnabledDefault

Enable/disable translation by default. This setting is applied to any conversation for which you haven't set a specific value.

setTranslationEnabledForConversation

Enable or disable translation for a conversation.

toggleDesktopNotifications

Deprecated. Please use Session.setDesktopNotificationEnabled instead.

Properties

messageField

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

Method Details

createHtmlPanel

inbox.createHtmlPanel(options): Promise<HtmlPanel>

HTML Panels allow you to place a HTML document in an iframe in your chats, just above the entry box.

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

options

interface HtmlPanelOptions

conversation

optional

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
number

optional

Optional, defaults to 300 (px).

show
boolean

optional

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.

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.

Returns

Promise<HtmlPanel>

destroy

inbox.destroy()

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

Parameters

None.

Returns

void

mount

inbox.mount(container): Promise<void>

Renders the UI inside a DOM element specified by container. 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 | JQuery | null

Returns

Promise<void>

off

This method has 7 overloads:
inbox.off(eventType, handler)

Used to stop listening to TalkJS events.

Stops listening for the _selectConversation_ event

Parameters

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

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

Returns

void
inbox.off(eventType, handler)

Used to stop listening to TalkJS events.

Stops listening for the _conversationSelected_ event

Parameters

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

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

Returns

void
inbox.off(eventType, handler)

Used to stop listening to TalkJS events.

Stops listening for the _desktopNotificationToggled_ event

Parameters

eventType
"desktopNotificationToggled"
handler

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

Returns

void
inbox.off(eventType, handler)

Used to stop listening to TalkJS events.

Stops listening for the _focus_ event

Parameters

eventType
"focus"
handler
() => void

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

Returns

void
inbox.off(eventType, handler)

Used to stop listening to TalkJS events.

Stops listening for the _blur_ event

Parameters

eventType
"blur"
handler
() => void

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

Returns

void
inbox.off(eventType, handler)

Used to stop listening to TalkJS events.

Stops listening for the _sendMessage_ event

Parameters

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

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

Returns

void
inbox.off(eventType, handler)

Used to stop listening to TalkJS events.

Stops listening for the _translationToggled_ event

Parameters

eventType
"translationToggled"
handler
() => void

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

Returns

void

on("blur")

inbox.on(eventType, handler)

Triggers when the chat UI gets unfocused (i.e. the user clicks/taps anywhere outside it).

Parameters

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

Returns

void

on("conversationSelected")

inbox.on(eventType, handler)

Triggers when 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

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

Returns

void

on("desktopNotificationToggled")

inbox.on(eventType, handler)

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

Parameters

eventType
"desktopNotificationToggled"
handler

Returns

void

on("focus")

inbox.on(eventType, handler)

Triggers when the chat UI gets focused (i.e. the user clicks/taps anywhere inside it).

Parameters

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

Returns

void

on("selectConversation")

inbox.on(eventType, handler)

Triggers when a user clicks a conversation in the feed. It's triggered *before* a conversation is selected. You can prevent the conversation from being actually selected by calling event.preventDefault().

Parameters

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

Returns

void

on("sendMessage")

inbox.on(eventType, handler)

Triggers when the user sends a message using the TalkJS UI

Parameters

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

Returns

void

on("translationTriggered")

inbox.on(eventType, handler)

Triggers when the user toggles translation in a conversation

Parameters

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

Returns

void

select

inbox.select(conversation)

Switches the active conversation the 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

Returns

void

setFeedFilter

inbox.setFeedFilter(filter)

Used to control which conversations are shown in the conversation feed, 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

filter

A predicate object that controls which conversations are shown.

Returns

void

setHighlightedWords

inbox.setHighlightedWords(words)

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 in TalkJS Premium 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, depending on a type, origin or custom message attributes.

See MessagePredicate for all available options.

Parameters

filter

A predicate object that controls which messages are shown.

Returns

void

setPresence

inbox.setPresence({ visible, custom })

Sets metadata for the current session.

Parameters

{ visible, custom }
{     visible?: boolean     custom?: {         [key: string]: string     } }

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

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

toggleDesktopNotifications

inbox.toggleDesktopNotifications(isEnabled)

Please use Session.setDesktopNotificationEnabled instead.

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

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.

Parameters

isEnabled
boolean

Returns

void