Inbox

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.

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.

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.

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

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.

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.

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.

See onKeyup for more details.

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.

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});

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.

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.

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

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.

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.

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.

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.

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

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.

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

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.

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

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.