Other interfaces

Any number of key/value pairs that will be sent with the action event.

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

Examples:

The following action button theme component will emit a color action event when you click it, with a parameter called choice that takes the value red:

<ActionButton action="color" data-choice="red">Red</ActionButton>

The following action button message markup will emit a color message action event when you click it, with a parameter called choice that takes the value blue:

<actionbutton:color?choice=blue|Blue>

Both the key and the value must be strings; arbitrarily deeply nested JSON is not supported.

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.

The value will be null if the conversation action is triggered from inside the ConversationListHeader component.

The current conversation object

The current TalkJS User

The participants in the conversation, including the current user

Deprecated.

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

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; arbitrarily deeply nested JSON is not supported. Example:

1{"country":"nl", "itemId": "720"}

Set to null to delete the existing value (if any). When omitted or undefined, the existing value remains unchanged.

Boolean indicating if desktop Notifications are enabled or not

Fullstory organization ID

Fullstory hostname

True if the event was triggered while an element was focused that can handle keyboard events.

The conversation that the user intends to leave

The conversation that the user intends to mark as unread

Determines whether the message field should automatically focus when the user navigates.

Defaults to "smart", which means that the message field gets focused whenever a conversation is selected, if possible without negative side effects. I.e. only 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" in the message field, which displays a dimmed text 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.

For example, to hide the message field when the current user has no write access to the current conversation, do the following:

1// this predicate holds iff the current user's `access` to the current conversation is
2// set to "ReadWrite"`:
3const showMessageField = { access: ["==", "ReadWrite"] };
4session.createInbox(conversation, { messageField: { visible: showMessageField } });

Defaults to true.

The current conversation object

The current TalkJS User

The participants in the conversation, including the current user

Deprecated.

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 id of the message to scroll to (This property only exists when a message search result has been selected)

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

Example, assume you have some users with the alternateRole field in their custom data:

1// Only show messages from senders that have the field alternateRole set:
2{custom: {alternateRole: "!exists" }}
3
4// Only show messages from senders that have the field alternateRole set to "support":
5{custom: {alternateRole: ["==", "support"]}}

Only show messages from a sender(s) with a given id.

For example:

1// Don't show messages sent by user with ID 1
2{sender: {id: ["!=", "1"]}}

Only show messages from senders with a given locale.

For example:

1// Only show messages from senders with locale: en-GB or en-US
2{sender: {locale: ["oneOf", ["en-GB", "en-US"]}}

Only show messages from senders who have a particular role.

For example:

1// Only show messages from senders with role: Admin and locale: en-GB
2{sender: {role: ["==", "Admin"], locale: ["==", "en-GB"]}}

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

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

Identifies the message as either a User message or System 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.

Example:

1[51.481083, -3.178306]

Contains the message's text

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

Example:

1// to remove conversations that the user has no access to anymore, do:
2{ access: ["!=", "None"] }

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

Example:

1// to show only the conversations that have been created after the UNIX timestamp 1679298371586
2{ createdAt: [">", 1679298371586] }

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

Examples, assuming you have set a category custom field on your conversations:

1// only show conversations that have no category set:
2{ custom: { category: "!exists" } }
3
4// only show conversations of category "shoes"
5{ custom: { category: ["==", "shoes"] } }
6
7// only show conversations either category "shoes" or "sandals"
8{ custom: { category: ["oneOf", ["shoes", "sandals"] ] } }
9
10// only show conversations about shoes that are marked visible.
11// this assumes you also have a custom field called `visibility`
12{ custom: { category: ["==", "shoes"], visibility: ["==", "visible" ] } }

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

Example:

1// to show only the conversations that have the last message sent after the UNIX timestamp 1679298371586
2{ lastMessageTs: [">", 1679298371586] }

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

Example:

1// to show only the conversations that have "Black leather boots" or "Hair Wax 5 Gallons" as the subject
2{ subject: ["oneOf", ["Black leather boots", "Hair Wax 5 Gallons"]] }

Only select messags 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).

Example:

1// to show only the messages that have been sent after the UNIX timestamp 1679298371586
2{ createdAt: [">", 1679298371586] }

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:

1// Only show messages that have no category set:
2{ custom: { category: "!exists" } }
3
4// Only show messages of that have the category "shoes"
5{ custom: { category: ["==", "shoes"] } }
6
7// Only show messages that have the 'topic' either "inquiry" or "reservation"
8{ custom: { topic: ["oneOf", ["inquiry", "reservation"] ] } }
9
10// Only show messages about shoes that are marked visible.
11// this assumes you also have a custom field called `visibility`
12{ custom: { category: ["==", "shoes"], visibility: ["==", "visible" ] } }

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:

1// Don't show messages that were sent via the REST API
2{ origin: ["!=", "rest"] }

Only show messages that are sent by a sender that has all of the given properties

For example:

1// Only show messages sent by users with the role of 'admin' and if the user ID is 1.
2{sender: {role: ["==", "admin"], id: ["==", "1"]}}

Only show messages of a given type, for example:

1{type: ["==", "SystemMessage"]}

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.

Conversation for which translation has been toggled

Boolean indicating if translation is enabled or not

Availability acts similarly to User​.welcomeMessage but appears as a system message.

Allows you to set custom metadata for the User

Set any property to null to delete the existing value (if any). When omitted or undefined, the existing value remains unchanged.

The unqiue ID which is used to identify the user in TalkJS

The locale field expects an IETF language tag. See the localization documentation.

The User's name which will be displayed on the TalkJS UI

An optional URL to a photo which will be displayed as the user's avatar

TalkJS supports multiple sets of settings, called "roles". These allow you to change the behavior of TalkJS for different users. You have full control over which user gets which configuration.

The default message a user sees when starting a chat with that person

Deprecated. Please use role instead.

Machine-readable error code

Human-readable error message