Other interfaces
Provides additional parameters to custom message action or conversation action events.
Any number of key/value pairs that will be sent with the action event.
Both the key and the value must be strings. Deeply nested JSON is not supported.
Add to action buttons in your theme components with the syntax data-<key>=<value>, or to action buttons in messages with the syntax action?<key>=<value>.
1<ActionButton action="color" data-choice="red">Red</ActionButton>
This theme component creates an action button that emits a color action event when you click it, with a parameter called choice that takes the value red.
Encapsulates an active conversation between two parties.
Use this object to send system messages to the conversation or to programmatically select a conversation by passing it to Inbox.select.
Conversation objects are created with the deprecated Session.getOrStartConversation method.
The ID of the conversation
Optional custom conversation meta data
Set any property to null to delete the existing value (if any). When omitted or undefined, the existing value remains unchanged.
An optional URL to a photo which will be shown as the photo for the conversation.
Set to null to delete the existing value (if any). When omitted or undefined, the existing value remains unchanged.
An optional conversation subject which is displayed in the chat header
Set to null to delete the existing value (if any). When omitted or undefined, the existing value remains unchanged.
Emitted from Chatbox.onCustomConversationAction when a user clicks on a custom action in a conversation within the TalkJS UI
The value will be null if the conversation action is triggered from inside the ConversationListHeader component.
This represents the interface of the event triggered from Inbox.onConversationSelected.
The current conversation object
The current TalkJS User
The participants in the conversation, including the current user
When you are the only participant in the conversation, this property includes the current user. Use participants and filter out the current user instead.
The other participants in the conversation that are not the current user
Used to store additional metadata on users, conversations and messages
Any number of key/value pairs of your choosing to be stored along with the associated resource.
You can use custom data for all kinds of purposes, such as customizing a user's email notification text, transmitting contextual user data, or making email login tokens.
Both the key and the value must be strings. Deeply nested JSON is not supported.
Defines a custom emoji
Image file URL
Must be a fully-qualified URL of image file, eg an SVG, GIF or PNG. The image must be square (same width and height) and is always scaled down to the size of an emoji.
Hides this emoji from the emoji picker and autocompleter
Hidden emojis can't be sent in new messages, or used in new emoji reactions, but they still display properly in existing messages and reactions. This lets you safely remove previously used custom emoji from the chat UI.
This event is triggered when desktop notifications are toggled.
Boolean indicating if desktop Notifications are enabled or not
Fullstory organization ID
Fullstory hostname
Emitted through Chatbox.onKeyup when the user presses a key. All fields except isInputFocused precisely match the corresponding fields in the browser's KeyboardEvent.
True if the event was triggered while an element was focused that can handle keyboard events.
Triggered when the user clicks a "Leave conversation" action in the chat UI.
| preventDefault | Call this to prevent the conversation from being left, ie to cancel the user action. |
The conversation that the user intends to leave
leaveConversationEvent.preventDefault()
Call this to prevent the conversation from being left, ie to cancel the user action.
Doing this will turn the "Leave conversation" action into a no-op, so you might want to display some sort of error message to the user so they understand why their click didn't do anything.
You can only call preventDefault from inside the onLeaveConversation event handler or a function immediately invoked from it. Calling preventDefault later, or after some promise resolved, has no effect.
Returns
Triggered when the user clicks a "Mark as unread" action in the chat UI.
| preventDefault | Call this to prevent the conversation from being marked as unread, ie to cancel the user action. |
The conversation that the user intends to mark as unread
markConversationAsUnreadEvent.preventDefault()
Call this to prevent the conversation from being marked as unread, ie to cancel the user action.
Doing this will turn the "Mark as unread" action into a no-op, so you might want to display some sort of error message to the user so they understand why their click didn't do anything.
You can only call preventDefault from inside the onMarkConversationAsUnread event handler or a function immediately invoked from it. Calling preventDefault later, or after some promise resolved, has no effect.
Returns
Emitted from Chatbox.onCustomMessageAction when a user clicks on a custom action, as defined on the "Chat UI" page of the dashboard.
Encapsulates the message entry field tied to the currently selected conversation.
| focus | Focuses the message entry field. |
| getText | Gets the current content of the message field. |
| setText | Sets the message field to |
| setVisible | Sets the visibility of the Message Field to a given value or to a certain predicate. |
| typeText | Types the given |
messageField.focus()
Focuses the message entry field.
Note that on mobile devices, this will cause the on-screen keyboard to pop up, obscuring part of the screen.
This method will silently fail if the participant only has "Read" access in the current conversation.
Returns
messageField.getText(): Promise<string>
Gets the current content of the message field.
Returns
messageField.setText(text)
Sets the message field to text.
Useful if you want to guide your user with message suggestions. If you want to start a UI with a given text showing immediately, call this method before calling Inbox.mount
This method will silently fail if the participant only has "Read" access in the current conversation.
Parameters
The text to be displayed in the message entry field
Returns
messageField.setVisible(visible)
Sets the visibility of the Message Field to a given value or to a certain predicate.
See MessageFieldOptions.visible for examples.
Parameters
boolean or a more advanced predicate.
Returns
messageField.typeText(text)
Types the given text into the message field.
Inserts text wherever the cursor currently is.
This method may be useful for various bot/simulation scenarios. Additionally, it lets you make it so that any regular keypress lets the user start typing into the message field, even if it is not focused.
This method will silently fail if the participant only has "Read" access in the current conversation.
To do that, capture the keypress using a regular window event listener, ensure that the user isn't typing into a different input, and then call this method to type the key, followed by focus. Note that TalkJS already does this out-of-the box when the chat UI iframe has focus and ChatboxOptions.captureKeyboardEvents is off.
Parameters
The text to be inserted in the message entry field
Returns
Determines whether the message field should automatically focus when the user navigates.
The default option is "smart", which means that focus is switched to the message field whenever a conversation is selected, if it is possible to do this without negative side effects. This is possible when:
- The message field is inside the browser viewport (so focusing will not unexpectedly cause the page to scroll)
- The user is likely on a desktop/laptop computer (so focusing will not unexpectedly expand a mobile on-screen keyboard).
Note: If you need more control, consider setting autofocus to false and calling MessageField.focus at appropriate times.
If set to true, pressing the enter key sends the message (if there is text in the message field). When set to false, the only way to send a message is by clicking or touching the "Send" button. Defaults to true.
Overrides the placeholder text that is displayed in the message field when no text has yet been entered.
Defaults to "Say something..." (or a translation thereof).
Specifies whether the spellcheck attribute is set on the message field. Note that setting this to true may also enable autocorrect on some mobile devices. Defaults to false.
Determines whether the message field is visible. Pass either a boolean (false to hide it), or a ConversationPredicate. The latter approach lets you show/hide the message field based on properties of the current conversation.
Defaults to true.
1// true only if the user's `access` in this conversation is `"ReadWrite"`2const showMessageField = { access: ["==", "ReadWrite"] };3session.createInbox(conversation, { messageField: { visible: showMessageField } });
Event data triggered from Inbox.onSelectConversation.
| preventDefault | Prevents the clicked conversation from being selected. |
The current conversation object
The current TalkJS User
When you are the only participant in the conversation, this property includes the current user. Use participants and filter out the current user instead.
The other participants in the conversation that are not the current user
The participants in the conversation, including the current user
The id of the message to scroll to (This property only exists when a message search result has been selected)
selectConversationEvent.preventDefault()
Prevents the clicked conversation from being selected.
Returns
Only show messages from senders who have particular custom fields set to particular values.
Every key must correspond to a key in a user's custom data that you have set. It is not necessary for all senders to have these keys.
Each value must be either:
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".
alternateRole property set
1{ custom: {alternateRole: "exists" } }
Only show messages from a sender(s) with a given id.
Only show messages from senders with a given locale.
The event triggered when listening for the sendMessage event on the Inbox, Chatbox and Popup. This event is triggered before the message is sent to TalkJS, allowing you to modify the contents of the message or its metadata by using override().
The current conversation object
The current TalkJS user
The message that was sent
This function allows you to modify the contents of the message or its metadata before the message is sent.
Pass an object with text and/or custom fields, see SendMessageOverrideParams.
You can either pass the overridden data directly, or a (possibly async) function that computes it.
Note that if you pass an async function, it must resolve as quickly as possible, because the chat UI cannot update before it does. This may make chat UX feel sluggish. If it does not resolve within 5 seconds, the message is sent unmodified.
A message that was sent to TalkJS
Identifies the message as either a User message or System message
The ID of the conversation that the message belongs to
The message ID of the message that was sent
Contains an Array of User.id's that have read the message
Contains the user ID for the person that sent the message
Only given if the message contains a file. An object with the URL and filesize (in bytes) of the given file. Attachment dimensions (in px) are sometimes available for image and video attachments, used to set the size of the thumbnail before loading, to prevent content shift when loading media on slower connections.
Only given if the message contains a location. An array of two numbers which represent the longitude and latitude of this location, respectively. Only given if this message is a shared location. For example: [51.481083, -3.178306].
Contains the message's text
Allows you to filter conversations down to a specific subset.
Use with Inbox.setFeedFilter or pass InboxOptions.feedFilter to Session.createInbox.
1inbox.setFeedFilter({ hasUnreadMessages: true });
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", and "!oneOf".
The operand must be either a string (one of "ReadWrite", "Read" or "None") or an array of strings (for the oneOf operators).
Only select conversations that have been created in a particular time interval.
Must be an 2-element array of [operator, operand] structure. Valid operators are: ">", "<", ">=", "<=", "between", and "!between".
The operand must be either a number or a 2-element array of numbers (for the between operators).
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", and "!oneOf".
1{ custom: { category: ["==", "shoes"] } }
1{ custom: { topic: ["oneOf", ["inquiry", "reservation"] ] } }
Set this field to only select conversations that have, or don't have any, unread messages.
Only select conversations that have the last message sent in a particular time interval.
Must be an 2-element array of [operator, operand] structure. Valid operators are: ">", "<", ">=", "<=", "between", and "!between".
The operand must be either a number or a 2-element array of numbers (for the between operators).
Only select conversations that have the subject set to particular values.
Must be an 2-element array of [operator, operand] structure. Valid operators are: "==", "!=", "oneOf", and "!oneOf".
The operand must be either a string or an array of strings (for the oneOf operators).
Lets you show only specific messages in the chat panel of a Chatbox, Inbox or Popup.
Used in methods like Chatbox.setMessageFilter
1chatbox.setMessageFilter({ type: ["==", "UserMessage"] });
Only show messages of a given type (system message or user message)
Only select messages that have been sent in a particular time interval.
Must be an 2-element array of [operator, operand] structure. Valid operators are: ">", "<", ">=", "<=", "between", and "!between".
The operand must be either a number or a 2-element array of numbers (for the between operators).
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".
1{ custom: { category: ["==", "shoes"] } }
1{ custom: { topic: ["oneOf", ["inquiry", "reservation"] ] } }
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).
A subscription to an event
| unsubscribe | Stop receiving events for this subscription |
subscription.unsubscribe()
Stop receiving events for this subscription
Returns
A map of values that will be available to your theme under the theme.custom namespace. The values can be anything that can be JSON-serialized. String and numeric values will also be made available as CSS custom properties in themes, available as var(--theme-<key>). where <key> is the value's key in the object.
The name of the theme to use in this widget If no theme name is given, TalkJS will use the theme set in the user's role, falling back to the default theme if the user has no role.
Used to configure supported third-party integrations with TalkJS. See third party integrations
This event is triggered when the user toggles real-time message translation using the built-in toggle.
Conversation for which translation has been toggled
Boolean indicating if translation is enabled or not
TalkJS Error class, inherits from the global Error class.
TalkJS methods may throw (or reject promises with) instances of this class if specific catchable information can be provided through the code property.
Machine-readable error code
Human-readable error message
A machine-readable error code enum.
Supports the following values:
- NOTIFICATIONS_PERMISSION_DENIED
- NOTIFICATIONS_NOT_SUPPORTED
- ARGUMENT_INVALID
Allows you to filter conversations down to a specific subset.
Use with Inbox.setFeedFilter or pass InboxOptions.feedFilter to Session.createInbox.
The first element must be the string "any", and the second element a list of SimpleConversationPredicate objects.
See SimpleConversationPredicate for all available options.
Lets you show only specific messages in the chat panel of a Chatbox, Inbox or Popup.
Used in methods like Chatbox.setMessageFilter.
The first element must be the string "any", and the second element a list of SimpleMessagePredicate objects.
See SimpleMessagePredicate for all available options.
A string that must be "ReadWrite", "Read" or "None".
Allows you to filter conversations down to a specific subset.
Use with Inbox.setFeedFilter or pass InboxOptions.feedFilter to Session.createInbox.
The ConversationPredicate can be either of the following:
- a single SimpleConversationPredicate object that filters based on all the fields of the predicate
- an array that gives you all the conversations that satisfy at least one of the SimpleConversationPredicates
See SimpleConversationPredicate and CompoundConversationPredicate for all available options.
A string or a two-element array that forms a predicate about a string field in a custom field.
Used in MessagePredicate and ConversationPredicate. Allows all forms in FieldPredicate plus the following:
- "exists"
- "!exists"
A two-element array that forms a predicate about a field.
Used in MessagePredicate and ConversationPredicate. Possible forms:
- ["==", "someValue"]
- ["!=", "someValue"]
- ["oneOf", ["someValue", "someOtherValue"]]
- ["!oneOf", ["someValue", "someOtherValue"]]
Lets you show only specific messages in the chat panel of a Chatbox, Inbox or Popup.
Used in methods like Chatbox.setMessageFilter.
The MessagePredicate can be either of the following:
- a single SimpleMessagePredicate object that filters based on all the fields of the predicate
- an array that gives you all the messages that satisfy at least one of the SimpleMessagePredicates
See SimpleMessagePredicate and CompoundMessagePredicate for all available options.
A two-element array that forms a predicate about a numeric field.
Used in ConversationPredicate. Possible forms:
- [">", someNumber]
- ["<", someNumber]
- [">=", someNumber]
- ["<=", someNumber]
- ["between", [lowerBound, upperBound]]
- ["!between", [lowerBound, upperBound]]