Popup
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 |
onBlur | Triggers when focus moves out of the chat UI. |
onClose | Triggers when the popup is closed by the user |
onCustomConversationAction | Triggers when a user launches a custom action on a conversation within the TalkJS UI. |
onCustomMessageAction | Triggers when a user launches a custom action on a message within the TalkJS UI. |
onFocus | Triggers when the chat UI is focussed. |
onKeydown | Triggers a KeyEvent when the user presses a key. |
onKeyup | Triggers a KeyEvent when the user releases a key. |
onLeaveConversation | Triggers when the user clicks on the "Leave conversation" action |
onOpen | Triggers when the popup is opened by the user |
onSendMessage | Triggers when the user sends a message using the TalkJS UI |
onTranslationToggled | Triggers when the user toggles message translation in the TalkJS UI. |
select | Switches the active conversation the conversation. |
sendFile | Upload a file attachment to the currently active conversation. |
sendLocation | Send the user's current location to the currently active 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 |
off Deprecated | Stops emitting events registered with on. |
on Deprecated | Listens for an event. |
toggleDesktopNotifications Deprecated | Toggles desktop notifications |
currentConversation
: ConversationData | nullThe conversation currently shown in the UI.
This field is null
when the UI does not currently show a conversation (eg because null
was passed to select or the selected conversation could not be found).
messageField
: MessageFieldEncapsulates the message entry field tied to the currently selected conversation.
popup.createHtmlPanel(options): Promise<HtmlPanel>
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
: HtmlPanelOptionsinterface HtmlPanelOptions
conversation (optional)
: Conversation | ConversationBuilder | stringEither 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.
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.
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
popup.destroy()
Destroys the popup, removes it from the DOM and removes all event listeners it has running.
Parameters
Returns
popup.hide()
Parameters
Returns
popup.mount(options): Promise<void>
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
popup.onBlur(handler): Subscription
Emits an event when the user clicks/taps anywhere outside the chat UI.
Parameters
handler
: () => voidReturns
popup.onClose(handler): Subscription
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
handler
: () => voidReturns
popup.onCustomConversationAction(action, handler): Subscription
To set up a custom action, you need to create it in the role editor. 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.
Parameters
action
: stringthe action you want to listen for
handler
: (event: ConversationActionEvent) => voidthe handler to be called
Returns
a subscription you can use to unsubscribe.
popup.onCustomMessageAction(action, handler): Subscription
To set up a custom action, you need to create it in the role editor. 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.
Parameters
action
: stringthe action you want to listen for
handler
: (event: MessageActionEvent) => voidthe handler to be called
Returns
a subscription you can use to unsubscribe.
popup.onFocus(handler): Subscription
Parameters
handler
: () => voidReturns
popup.onKeydown(handler): Subscription
Parameters
handler
: (event: KeyEvent) => voidReturns
popup.onKeyup(handler): Subscription
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.
Example
myChatbox.onKeyup(event => {if(event.shiftKey || event.altKey || event.metaKey) {return;}// let the 1 key switch to our app's main panel, except if the user is typingif(!event.isInputFocused && event.key === "1") {myApp.selectMainPanel();}// quit if the user hits ctrl+q, irrespective of whether they're typing.if(event.ctrlKey && event.key === "q") {myApp.quit();}});
Parameters
handler
: (event: KeyEvent) => voidReturns
popup.onLeaveConversation(handler): Subscription
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.
Parameters
handler
: (event: LeaveConversationEvent) => voidReturns
popup.onOpen(handler): Subscription
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
handler
: () => voidReturns
popup.onSendMessage(handler): Subscription
Parameters
handler
: (event: SendMessageEvent) => voidReturns
popup.onTranslationToggled(handler): Subscription
Parameters
handler
: (event: TranslationToggledEvent) => voidReturns
popup.select(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 | undefinedReturns
popup.select(conversation, params)
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 | undefinedparams (optional)
: { asGuest?: boolean }Selection parameters. asGuest
can be used to select the conversation as a guest, with limited functions
Returns
popup.sendFile(file): Promise<void>
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.
Parameters
file
: FileThe File object to be uploaded.
Returns
popup.sendLocation(): Promise<void>
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.
Parameters
Returns
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 on the Growth plan and up.
Also see ChatboxOptions​.highlightedWords
Parameters
words
: string[]Returns
popup.setMessageFilter(filter)
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
filter
: MessagePredicateA predicate object that controls which messages are shown.
Returns
popup.setPresence(presence)
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 internally calls this method when a user opens or closes it. visible
is set to true
or false
respectively.
Parameters
presence
: UserPresenceinterface UserPresence
custom (optional)
: CustomDataThis is an additional parameter to store the custom fields that you may want to use in the REST API call.
Set any property to null
to delete the existing value (if any). When omitted or undefined
, the existing value remains unchanged.
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.
When omitted or undefined
, the existing value remains unchanged.
Returns
popup.setTranslationEnabledDefault(boolean | "auto")
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
popup.setTranslationEnabledForConversation(conversation, enabled)
Parameters
conversation
: string | ConversationBuilderThe conversation for which this should be set. If not specified, the setting will be applied to the currently selected conversation.
enabled
: booleanWhether translation should be enabled
Returns
popup.show()
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
Returns
The following methods remain supported for backward compatibility reasons. In new projects, we recommend that you use the suggested alternatives instead.
off Deprecated | Stops emitting events registered with on. |
on Deprecated | Listens for an event. |
toggleDesktopNotifications Deprecated | Toggles desktop notifications |
popup.off("open", handler)
Deprecated. Please use the Subscription​.unsubscribe method on the object returned by onOpen instead.
Parameters
eventType
: "open"handler
: () => voidThe handler function must be the same handler function that was passed to on("open")
Returns
popup.off("close", handler)
Deprecated. Please use the Subscription​.unsubscribe method on the object returned by onClose instead.
Parameters
eventType
: "close"handler
: () => voidThe handler function must be the same handler function that was passed to on("close")
Returns
popup.off("sendMessage", handler)
Deprecated. Please use the Subscription​.unsubscribe method on the object returned by onSendMessage instead.
Parameters
eventType
: "sendMessage"handler
: (event: SendMessageEvent) => voidThe handler function must be the same handler function that was passed to on("sendMessage")
Returns
popup.off("focus", handler)
Deprecated. Please use the Subscription​.unsubscribe method on the object returned by onFocus instead.
Parameters
eventType
: "focus"handler
: () => voidThe handler function must be the same handler function that was passed to on("focus")
Returns
popup.off("blur", handler)
Deprecated. Please use the Subscription​.unsubscribe method on the object returned by onBlur instead.
Parameters
eventType
: "blur"handler
: () => voidThe handler function must be the same handler function that was passed to on("blur")
Returns
popup.off("translationToggled", handler)
Deprecated. Please use the Subscription​.unsubscribe method on the object returned by onTranslationToggled instead.
Parameters
eventType
: "translationToggled"handler
: () => voidThe handler function must be the same handler function that was passed to on("translationToggled")
Returns
popup.off("keyup", handler)
Deprecated. Please use the Subscription​.unsubscribe method on the object returned by onKeyup instead.
Parameters
eventType
: "keyup"handler
: (event: KeyEvent) => voidThe handler function must be the same handler function that was passed to on("keyup")
Returns
popup.on("open", handler)
Deprecated. Please use onOpen instead.
Parameters
eventType
: "open"handler
: () => voidReturns
popup.on("close", handler)
Deprecated. Please use onClose instead.
Parameters
eventType
: "close"handler
: () => voidReturns
popup.on("sendMessage", handler)
Deprecated. Please use onSendMessage instead.
Parameters
eventType
: "sendMessage"handler
: (event: SendMessageEvent) => voidReturns
popup.on("focus", handler)
Deprecated. Please use onFocus instead.
Parameters
eventType
: "focus"handler
: () => voidReturns
popup.on("blur", handler)
Deprecated. Please use onBlur instead.
Parameters
eventType
: "blur"handler
: () => voidReturns
popup.on("translationToggled", handler)
Deprecated. Please use onTranslationToggled instead.
Parameters
eventType
: "translationToggled"handler
: (event: TranslationToggledEvent) => voidReturns
popup.on("keyup", handler)
Deprecated. Please use onKeyup instead.
Parameters
eventType
: "keyup"handler
: (event: KeyEvent) => voidReturns
popup.toggleDesktopNotifications(isEnabled)
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. Please use Session​.setDesktopNotificationÂEnabled instead.