TalkJS Documentation

The Chat API + Javascript SDK for websites and apps

Log in or Sign up to view personalized docs.

Inbox

Friday, May 10, 2019 1:12 AM

The main messaging UI. Chats on the left, messages on the right. Create an Inbox through Session.createInbox and then call Inbox.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("sendMessage")

Triggers when the user sends a message using the TalkJS UI

select

Switches the active conversation the conversation identified by conversation, which can be either a Conversation object or a TalkJS conversation id.

setFeedFilter

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 set the filter in Session.createInbox using InboxOptions.feedFilter.

setPresence

Sets metadata for the current session.

toggleDesktopNotifications

Deprecated. Please use Session.setDesktopNotificationEnabled instead.

Properties

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

Method Details

createHtmlPanel

inbox.createHtmlPanel(options)
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
HtmlPanelOptions

HtmlPanelOptions

conversation
Conversation | ConversationBuilder | string
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)
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 5 overloads:
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
(event: DesktopNotificationToggledEvent) => void

Returns

void
inbox.off(eventType, handler)
Used to stop listening to TalkJS events.

Stops listening for the focus event

Parameters

eventType
"focus"
handler
() => void

Returns

void
inbox.off(eventType, handler)
Used to stop listening to TalkJS events.

Stops listening for the blur event

Parameters

eventType
"blur"
handler
() => void

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

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

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
(event: DesktopNotificationToggledEvent) => void

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("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

select

inbox.select(conversation)
Switches the active conversation the conversation identified by conversation, which can be either a Conversation object or a TalkJS conversation id.

Parameters

conversation
string | Conversation | ConversationBuilder

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 ConversationFilter for all available options. You can also set the filter in Session.createInbox using InboxOptions.feedFilter.

Parameters

filter
ConversationFilter

ConversationFilter

access
FieldPredicate<ConversationAccessLevel>
optional		Only select conversations that the current user as specific access to. Must be an 2-element array of [operator, operand] structure. Valid operators are: * "==" * "!=" * "oneOf" * "!oneOf". The operand must be either a string (one of "ReadWrite", "Read" or "None") or an array of strings (for the oneOf operators). Example: 
// to remove conversations that the user has no access to anymore, do:
{ access: ["!=", "None"] }
custom
{ [key: string]: CustomFieldPredicate; }
optional		Only select conversations that have particular custom fields set to particular values. Every key must correspond to a key in the custom conversation data that you set (by passing custom to ConversationBuilder.setAttributes). It is not necessary for all conversations to have these keys. Each value must be one of the following: * A string, equal to "exists" or "!exists" * A 2-element array of [operator, operand] structure. The operand must be either a string or an array of strings (for the oneOf operators). Valid operators are: * "==" * "!=" * "oneOf" * "!oneOf". Examples, assuming you have set a category custom field on your conversations: 
// only show conversations that have no category set:
{ custom: { category: "!exists" } }


// only show conversations of category "shoes"
{ custom: { category: ["==", "shoes"] } }


// only show conversations either category "shoes" or "sandals"
{ custom: { category: ["oneOf", ["shoes", "sandals"] ] } }


// only show conversations about shoes that are marked visible.
// this assumes you also have a custom field called visibility
{ custom: { category: ["==", "shoes"], visibility: ["==", "visible" ] } }
hasUnreadMessages
boolean
optional		Set this field to only select conversations that have, or don't have any, unread messages.

Returns

void

setPresence

inbox.setPresence({ visible, custom })
Sets metadata for the current session.

Parameters

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

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