Popup

A messaging UI for just a single conversation. There is no way for the user to switch between conversations (but you can change the active conversation through select). Create a Popup through Session​.createPopup and then call mount to show it.
createHtmlPanel

Puts custom HTML just above the message field.

destroy

Destroys the popup and removes it from the DOM

hide

Closes the popup, but doesn't remove it from the DOM

mount

Renders the Popup UI on your page

off

Used to stop listening to TalkJS events

on("blur")

Triggers when the chat UI gets unfocused

on("close")

Triggers when the popup is closed by the user

on("focus")

Triggers when the chat UI gets focused

on("open")

Triggers when the popup is opened by the user

on("sendMessage")

Triggers when the user sends a message using the TalkJS UI

on("translationToggled")

Triggers when the user toggles translation in a conversation

select

Switches the active conversation the conversation.

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.

show

Shows the Popup

toggleDesktopNotifications Deprecated

Please use Session​.setDesktopNotification­Enabled instead.

: MessageField

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

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

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>
popup.destroy()
Destroys the popup and removes it from the DOM

Destroys the popup, removes it from the DOM and removes all event listeners it has running.

Parameters

None.

Returns

void
popup.hide()
Closes the popup, but doesn't remove it from the DOM

Parameters

None.

Returns

void
popup.mount(options): Promise<void>
Renders the Popup UI on your page

Loads the popup in the background, but by default shows only the launcher button. Pass { show: true } to open the popup as soon as it's loaded.

Parameters

options (optional)
: { show?: boolean }

Returns

Promise<void>
This method has 6 overloads
popup.off(eventType, handler)
Used to stop listening to TalkJS events

Stops listening for the _open_ event

Parameters

eventType
: "open"
handler
: (event: OpenEvent) => void

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

Returns

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

Stops listening for the _close_ event

Parameters

eventType
: "close"
handler
: (event: CloseEvent) => void

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

Returns

void
popup.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
popup.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
popup.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
popup.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
popup.on(eventType, handler)
Triggers when the chat UI gets unfocused

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

Parameters

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

Returns

void
popup.on(eventType, handler)
Triggers when the popup is closed by the user

Only gets triggered when the user performs an action to close the popup, eg when they click the "X" on the launcher or, if enabled, in the popup header. This event is not triggered when you call hide or destroy.

Parameters

eventType
: "close"
handler
: (event: CloseEvent) => void

Returns

void
popup.on(eventType, handler)
Triggers when the chat UI gets focused

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

Parameters

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

Returns

void
popup.on(eventType, handler)
Triggers when the popup is opened by the user

Only gets triggered when the user performs an action to open the popup. This event is not triggered when you call show or when you mount it with the {show: true} option.

Parameters

eventType
: "open"
handler
: (event: OpenEvent) => void

Returns

void
popup.on(eventType, handler)
Triggers when the user sends a message using the TalkJS UI

Parameters

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

Returns

void
popup.on(eventType, handler)
Triggers when the user toggles translation in a conversation

Parameters

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

Returns

void
This method has 2 overloads
popup.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
popup.select(conversation, params)
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
params (optional)
: { asGuest?: boolean }

Selection parameters. asGuest can be used to select the conversation as a guest, with limited functions

Returns

void
popup.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
popup.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

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

Parameters

A predicate object that controls which messages are shown.

Returns

void
popup.setPresence(params)
Sets metadata for the current session.

Parameters

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

Object with presence parameters.

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

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

Returns

void
popup.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
popup.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
popup.show()
Shows the Popup

Use this to show a popup that was previously hidden or mounted with a parameter show: false. Note: does nothing on unmounted popups. Make sure you call mount once before you call show() or hide.

Parameters

None.

Returns

void
popup.toggleDesktopNotifications(isEnabled)
Please use Session​.setDesktopNotification­Enabled instead.

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.

Parameters

isEnabled
: boolean

Returns

void