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.

Methods

createHtmlPanel	HTML Panels allow you to place a HTML document in an iframe in your chats, just above the entry box.
destroy	Destroys the Popup
hide	Closes the Popup, but doesn't remove it from the DOM
mount	Mounts the Popup to the parent container
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("close")	Triggers when the popup is closed by the user.
on("focus")	Triggers when the chat UI gets focused (i.e. the user clicks/taps anywhere inside it)
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("translationTriggered")	Triggers when the user toggles translation in a conversation
select	Switches the active conversation the conversation.
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. See MessagePredicate for all available options.
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.
show	Shows the Popup, previously hidden or mounted with a parameter `show: false`
toggleDesktopNotifications	Deprecated. Please use Session.setDesktopNotificationEnabled instead.

Properties

MessageField

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

Method Details

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

HtmlPanelOptions

interface 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>

popup.destroy()

Destroys the Popup

Call this before removing the Popup container from the DOM.

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>

Mounts the Popup to the parent container

Parameters

options

{ show?: boolean }

optional

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 (i.e. the user clicks/taps anywhere outside it)

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 (i.e. the user clicks/taps anywhere inside it)

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

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

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

MessagePredicate

interface MessagePredicate

custom { [key: string]: CustomFieldPredicate } optional	Only select messages that have particular custom fields set to particular values. Every key must correspond to a key in the custom message data that you have set. It is not necessary for all messages 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"`, and `"!oneOf"`. Examples, assuming you have set a `category` custom field on your messages: `// Only show messages that have no category set: { custom: { category: "!exists" } } // Only show messages of that have the category "shoes" { custom: { category: ["==", "shoes"] } } // Only show messages that have the 'topic' either "inquiry" or "reservation" { custom: { topic: ["oneOf", ["inquiry", "reservation"] ] } }` `// Only show messages about shoes that are marked visible. // this assumes you also have a custom field called visibility { custom: { category: ["==", "shoes"], visibility: ["==", "visible" ] } }`
origin FieldPredicate<"web" \| "rest" \| "email" \| "import"> optional	Only show messages that were sent by users (web), through the REST API (rest), via reply-to-email (email) or via the import REST API (import). For example: `// Don't show messages that were sent via the REST API { origin: ["!=", "rest"] }`
sender { id?: FieldPredicate<string> custom?: { [key: string]: CustomFieldPredicate } locale?: FieldPredicate<string> role?: FieldPredicate<string> } optional	Only show messages that are sent by a sender that has all of the given properties For example: `// Only show messages sent by users with the role of 'admin' and if the user ID is 1. {sender: {role: ["==", "admin"], id: ["==", "1"]}}`
type FieldPredicate<"UserMessage" \| "SystemMessage"> optional	Only show messages of a given type, for example: `{type: ["==", "SystemMessage"]}`

Returns

void

popup.setPresence({ visible, custom })

Sets metadata for the current session.

Parameters

{ visible, custom }

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

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 hsould be 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, previously hidden or mounted with a parameter show: false

Parameters

None.

Returns

void

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

interface Popup

Methods

Properties

messageField

Method Details

createHtmlPanel

Parameters

options

interface HtmlPanelOptions

conversation

height

show

url

Returns

destroy

Parameters

Returns

hide

Parameters

Returns

mount

Parameters

options

Returns

off

Parameters

eventType

handler

Returns

Parameters

eventType

handler

Returns

Parameters

eventType

handler

Returns

Parameters

eventType

handler

Returns

Parameters

eventType

handler

Returns

Parameters

eventType

handler

Returns

on("blur")

Parameters

eventType

handler

Returns

on("close")

Parameters

eventType

handler

Returns

on("focus")

Parameters

eventType

handler

Returns

on("open")

Parameters

eventType

handler

Returns

on("sendMessage")

Parameters

eventType

handler

Returns

on("translationTriggered")

Parameters

eventType

handler

Returns