Other interfaces
custom
: CustomDatainterface CustomData
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:
{"country":"nl", "itemId": "720"}
Set to null
to delete the existing value (if any). When omitted or undefined
, the existing value remains unchanged.
The type of permission that was denied.
Note that more possible values may be added in the future, so make sure your handler can deal with unknown permission types gracefully.
preventDefault | Cancel whatever user action caused the permission to be requested. |
The type of permission requested.
Note that more possible values may be added in the future, so make sure your handler can deal with unknown permission types gracefully.
browserPermissionNeededEvent.preventDefault()
For example, if a user wants to share their location for the first time so that this event is triggered, then if you call preventDefault()
, no permission will be requested from the browser, the location sharing will be cancelled, and TalkJS will continue as if the location sharing button had not been clicked at all.
This may be useful if you're using this event to show custom UI elements that nudge users towards granting permission, and this UI has a "cancel" button.
Parameters
Returns
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.
Deprecated. Use Session.getOrCreateConversation instead
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.
Legacy - please use subject instead.
conversation
: ConversationDatainterface ConversationData
custom
: CustomDataContains custom metadata for the conversation if it was set using ConversationBuilder.custom.
Set any property to null
to delete the existing value (if any). When omitted or undefined
, the existing value remains unchanged. When sending custom: null
all properties and values will be removed.
Contains the URL of a photo was set using ConversationBuilder.subject.
Contains the conversation subject if it was set using ConversationBuilder.subject.
One or more welcome messages that will display to the user as a SystemMessage
params
: ActionEventParamsUse with Inbox.setFeedFilter or pass InboxOptions.feedFilter to Session.createInbox. For example, to hide read conversations, use:
inbox.setFeedFilter({ hasUnreadMessages: true })
.
To show everything (ie to disable the filter), use an empty object:
inbox.setFeedFilter({})
.
access (optional)
: FieldPredicate<ConversationAccessLevel>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:
// to remove conversations that the user has no access to anymore, do:{ access: ["!=", "None"] }
custom (optional)
: { [key: string]: CustomFieldPredicate }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:
// only show conversations that have no category set:{ custom: { category: "!exists" } }// only show conversations of category "shoes"{ custom: { category: ["==", "shoes"] } }// only show conversations either category "shoes" or "sandals"{ custom: { category: ["oneOf", ["shoes", "sandals"] ] } }// only show conversations about shoes that are marked visible.// this assumes you also have a custom field called `visibility`{ custom: { category: ["==", "shoes"], visibility: ["==", "visible" ] } }
Set this field to only select conversations that have, or don't have any, unread messages.
lastMessageTs (optional)
: NumberPredicateOnly 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:
// to show only the conversations that have the last message sent after the UNIX timestamp 1679298371586{ lastMessageTs: [">", 1679298371586] }
subject (optional)
: FieldPredicate<string | null>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:
// to show only the conversations that have "Black leather boots" or "Hair Wax 5 Gallons" as the subject{ subject: ["oneOf", ["Black leather boots", "Hair Wax 5 Gallons"]] }
conversation
: ConversationData | nullThe current conversation object
me
: UserDataThe current TalkJS User
interface UserData
Availability acts similarly to User.welcomeMessage but appears as a system message.
custom
: CustomDataAllows 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 locale field expects an IETF language tag. See the localization documentation.
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.
others (optional)
: Array<UserData>The other participants in the conversation that are not the current user
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.
preventDefault | Call this to prevent the conversation from being left, ie to cancel the user action. |
conversation
: ConversationDataThe conversation that the user intends to leave
interface ConversationData
custom
: CustomDataContains custom metadata for the conversation if it was set using ConversationBuilder.custom.
Set any property to null
to delete the existing value (if any). When omitted or undefined
, the existing value remains unchanged. When sending custom: null
all properties and values will be removed.
Contains the URL of a photo was set using ConversationBuilder.subject.
Contains the conversation subject if it was set using ConversationBuilder.subject.
One or more welcome messages that will display to the user as a SystemMessage
leaveConversationEvent.preventDefault()
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.
Parameters
Returns
preventDefault | Call this to prevent the conversation from being marked as unread, ie to cancel the user action. |
conversation
: ConversationDataThe conversation that the user intends to mark as unread
interface ConversationData
custom
: CustomDataContains custom metadata for the conversation if it was set using ConversationBuilder.custom.
Set any property to null
to delete the existing value (if any). When omitted or undefined
, the existing value remains unchanged. When sending custom: null
all properties and values will be removed.
Contains the URL of a photo was set using ConversationBuilder.subject.
Contains the conversation subject if it was set using ConversationBuilder.subject.
One or more welcome messages that will display to the user as a SystemMessage
markConversationAsUnreadEvent.preventDefault()
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.
Parameters
Returns
message
: Messageinterface Message
Only given if the message's type
equals "media"
. 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.
conversation
: ConversationDataContains the ConversationData that the message belongs to.
custom
: CustomDataCustom metadata that is stored with the conversation
Set any property to null
to delete the existing value (if any). When omitted or undefined
, the existing value remains unchanged.
Only given if the message's type
equals "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:
[51.481083, -3.178306]
Determines how this message was sent: respectively, Via a web browser (or mobile Webview), via the REST API, via reply-to-email, or using the import API.
params
: ActionEventParamsfocus | 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()
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.
Parameters
Returns
messageField.getText(): Promise<string>
Parameters
Returns
messageField.setText(text)
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
text
: stringThe text to be displayed in the message entry field
Returns
messageField.setVisible(visible)
See MessageFieldOptions.visible for examples.
Parameters
visible
: boolean | ConversationPredicateboolean or a more advanced predicate.
Returns
messageField.typeText(text)
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
text
: stringThe text to be inserted in the message entry field
Returns
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
.
visible (optional)
: boolean | ConversationPredicateDetermines 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:
// this predicate holds iff the current user's `access` to the current conversation is// set to "ReadWrite"`:const showMessageField = { access: ["==", "ReadWrite"] };session.createInbox(conversation, { messageField: { visible: showMessageField } });
Defaults to true
.
Used in methods like Chatbox.setMessageFilter. For example, to hide all system messages (eg only show user messages), do:
chatbox.setMessageFilter({type: ["==", "UserMessage"]})
To show all messages (ie disable the filter), just pass an empty object:
chatbox.setMessageFilter({})
custom (optional)
: { [key: string]: CustomFieldPredicate }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 (optional)
: FieldPredicate<"web" | "rest" | "email" | "import">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 (optional)
: SenderPredicateOnly 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"]}}
interface SenderPredicate
custom (optional)
: { [key: string]: CustomFieldPredicate }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:
// Only show messages from senders that have the field alternateRole set:{custom: {alternateRole: "!exists" }}// Only show messages from senders that have the field alternateRole set to "support":{custom: {alternateRole: ["==", "support"]}}
id (optional)
: FieldPredicate<string>Only show messages from a sender(s) with a given id.
For example:
// Don't show messages sent by user with ID 1{sender: {id: ["!=", "1"]}}
locale (optional)
: FieldPredicate<string>Only show messages from senders with a given locale.
For example:
// Only show messages from senders with locale: en-GB or en-US{sender: {locale: ["oneOf", ["en-GB", "en-US"]}}
role (optional)
: FieldPredicate<string>Only show messages from senders who have a particular role.
For example:
// Only show messages from senders with role: Admin and locale: en-GB{sender: {role: ["==", "Admin"], locale: ["==", "en-GB"]}}
type (optional)
: FieldPredicate<"UserMessage" | "SystemMessage">Only show messages of a given type, for example:
{type: ["==", "SystemMessage"]}
preventDefault | Prevents the clicked conversation from being selected. |
conversation
: ConversationDataThe current conversation object
interface ConversationData
custom
: CustomDataContains custom metadata for the conversation if it was set using ConversationBuilder.custom.
Set any property to null
to delete the existing value (if any). When omitted or undefined
, the existing value remains unchanged. When sending custom: null
all properties and values will be removed.
Contains the URL of a photo was set using ConversationBuilder.subject.
Contains the conversation subject if it was set using ConversationBuilder.subject.
One or more welcome messages that will display to the user as a SystemMessage
me
: UserDataThe current TalkJS User
interface UserData
Availability acts similarly to User.welcomeMessage but appears as a system message.
custom
: CustomDataAllows 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 locale field expects an IETF language tag. See the localization documentation.
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.
others
: Array<UserData>The other participants in the conversation that are not the current user
selectConversationEvent.preventDefault()
Parameters
Returns
custom (optional)
: { [key: string]: CustomFieldPredicate }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:
// Only show messages from senders that have the field alternateRole set:{custom: {alternateRole: "!exists" }}// Only show messages from senders that have the field alternateRole set to "support":{custom: {alternateRole: ["==", "support"]}}
id (optional)
: FieldPredicate<string>Only show messages from a sender(s) with a given id.
For example:
// Don't show messages sent by user with ID 1{sender: {id: ["!=", "1"]}}
locale (optional)
: FieldPredicate<string>Only show messages from senders with a given locale.
For example:
// Only show messages from senders with locale: en-GB or en-US{sender: {locale: ["oneOf", ["en-GB", "en-US"]}}
role (optional)
: FieldPredicate<string>Only show messages from senders who have a particular role.
For example:
// Only show messages from senders with role: Admin and locale: en-GB{sender: {role: ["==", "Admin"], locale: ["==", "en-GB"]}}
override()
.conversation
: ConversationDataThe current conversation object
interface ConversationData
custom
: CustomDataContains custom metadata for the conversation if it was set using ConversationBuilder.custom.
Set any property to null
to delete the existing value (if any). When omitted or undefined
, the existing value remains unchanged. When sending custom: null
all properties and values will be removed.
Contains the URL of a photo was set using ConversationBuilder.subject.
Contains the conversation subject if it was set using ConversationBuilder.subject.
One or more welcome messages that will display to the user as a SystemMessage
me
: UserDataThe current TalkJS user
interface UserData
Availability acts similarly to User.welcomeMessage but appears as a system message.
custom
: CustomDataAllows 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 locale field expects an IETF language tag. See the localization documentation.
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.
message
: SentMessageThe message that was sent
interface SentMessage
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:
[51.481083, -3.178306]
Contains an Array of User.id's that have read the message
Identifies the message as either a User message or System message
override
: ({ text, custom, }: {text?: string custom?: CustomData }) => voidThis function allows you to modify the contents of the message or its metadata before the message is sent
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:
[51.481083, -3.178306]
Contains an Array of User.id's that have read the message
Identifies the message as either a User message or System message
unsubscribe | Stop receiving events for this subscription |
subscription.unsubscribe()
Parameters
Returns
custom (optional)
: { [key: string]: JsonSerializable }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.
fullstory (optional)
: FullStoryOptionsconversation
: ConversationDataConversation for which translation has been toggled
interface ConversationData
custom
: CustomDataContains custom metadata for the conversation if it was set using ConversationBuilder.custom.
Set any property to null
to delete the existing value (if any). When omitted or undefined
, the existing value remains unchanged. When sending custom: null
all properties and values will be removed.
Contains the URL of a photo was set using ConversationBuilder.subject.
Contains the conversation subject if it was set using ConversationBuilder.subject.
One or more welcome messages that will display to the user as a SystemMessage
Availability acts similarly to User.welcomeMessage but appears as a system message.
custom
: CustomDataAllows 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.
interface CustomData
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:
{"country":"nl", "itemId": "720"}
Set to null
to delete the existing value (if any). When omitted or undefined
, the existing value remains unchanged.
The locale field expects an IETF language tag. See the localization documentation.
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.
TalkJS methods may throw (or reject promises with) instances of this class if specific catchable information can be provided through the code
property.
code
: ErrorCodeMachine-readable error code
Supports the following values:
- NOTIFICATIONS_PERMISSION_DENIED
- NOTIFICATIONS_NOT_SUPPORTED
- ARGUMENT_INVALID
"ReadWrite"
, "Read"
or "None"
.custom
field.Used in MessagePredicate and ConversationPredicate. Allows all forms in FieldPredicate plus the following:
- "exists"
- "!exists"
Used in MessagePredicate and ConversationPredicate. Possible forms:
- ["==", "someValue"]
- ["!=", "someValue"]
- ["oneOf", ["someValue", "someOtherValue"]]
- ["!oneOf", ["someValue", "someOtherValue"]]
Used in ConversationPredicate. Possible forms:
- [">", someNumber]
- ["<", someNumber]
- [">=", someNumber]
- ["<=", someNumber]
- ["between", [lowerBound, upperBound]]
- ["!between", [lowerBound, upperBound]]