Other interfaces

interface Conversation

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.

Deprecated.

Properties

custom (optional)
: {    [name: string]: string | null} | null

Optional custom conversation meta data

id
: string

The ID of the conversation

photoUrl (optional)
: string | null

An optional URL to a photo which will be shown as the photo for the conversation.

subject (optional)
: string | null

An optional conversation subject which is displayed in the chat header

topicId
: string

Legacy - please use subject instead.

welcomeMessages (optional)
: Array<string> | null

interface ConversationPredicate

Allows you to filter conversations down to a specific subset.

Use 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({}).

Properties

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" ] } }

hasUnreadMessages (optional)
: boolean

Set this field to only select conversations that have, or don't have any, unread messages.


interface ConversationSelectedEvent

This represents the interface of the event triggered from Inbox.on("conversationSelected").

Properties

conversation
: ConversationData | null

The current conversation object

The current TalkJS User

interface UserData

availabilityText
: string | null

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

custom
: CustomData

Allows you to set custom metadata for the User

id
: string | number

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

locale
: string | null

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

name
: string

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

photoUrl
: string | null

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

role
: string | null

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.

welcomeMessage
: string | null

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

Deprecated configuration
: string | null

Deprecated.

Please use role instead.

others (optional)
: Array<UserData>

The other participants in the conversation that are not the current user


interface DesktopNotificationClickedEvent

Sent by Session.on("desktopNotificationClicked") when a user clicks on a browser notification.

Properties

conversation
: ConversationData

interface ConversationData

custom
: CustomData

Contains custom metadata for the conversation if it was set using ConversationBuilder.custom.

id
: string

The ID of the conversation

photoUrl
: string | null

Contains the URL of a photo was set using ConversationBuilder.subject.

subject
: string | null

Contains the conversation subject if it was set using ConversationBuilder.subject.

welcomeMessages
: Array<string> | null

One or more welcome messages that will display to the user as a SystemMessage

Deprecated topicId
: string | null

Deprecated.

Please use ConversationBuilder.subject instead.


interface MessageField

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

Methods

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.

Sets the message entry 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

Sets the visibility of the Message Field to a given value or to a certain predicate. See MessageFieldOptions.visible for examples.

Method Details

focus

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.

Parameters

None.

Returns

void

setText

messageField.setText(text)
Sets the message entry 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

Parameters

text
: string

The text to be displayed in the message entry field

Returns

void

setVisible

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

visible
: boolean | ConversationPredicate

boolean or a more advanced predicate.

Returns

void

interface MessageFieldOptions

Properties

autofocus (optional)
: false | "smart"

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.

enterSendsMessage (optional)
: boolean

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.

placeholder (optional)
: string

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

spellcheck (optional)
: boolean

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

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:

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


interface MessagePredicate

Lets you show only specific messages in the chat panel of a Chatbox, Inbox or Popup.

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({})

Properties

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)
: {    id?: FieldPredicate<string>     custom?: {        [key: string]: CustomFieldPredicate    }    locale?: FieldPredicate<string>     role?: FieldPredicate<string>}

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 (optional)
: FieldPredicate<"UserMessage" | "SystemMessage">

Only show messages of a given type, for example:

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


interface SelectConversationEvent

Event data triggered from Inbox.on("selectConversation").

Methods

Prevents the clicked conversation from being selected.

Properties

conversation
: ConversationData

The current conversation object

interface ConversationData

custom
: CustomData

Contains custom metadata for the conversation if it was set using ConversationBuilder.custom.

id
: string

The ID of the conversation

photoUrl
: string | null

Contains the URL of a photo was set using ConversationBuilder.subject.

subject
: string | null

Contains the conversation subject if it was set using ConversationBuilder.subject.

welcomeMessages
: Array<string> | null

One or more welcome messages that will display to the user as a SystemMessage

Deprecated topicId
: string | null

Deprecated.

Please use ConversationBuilder.subject instead.

The current TalkJS User

interface UserData

availabilityText
: string | null

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

custom
: CustomData

Allows you to set custom metadata for the User

id
: string | number

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

locale
: string | null

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

name
: string

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

photoUrl
: string | null

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

role
: string | null

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.

welcomeMessage
: string | null

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

Deprecated configuration
: string | null

Deprecated.

Please use role instead.

others
: Array<UserData>

The other participants in the conversation that are not the current user

Method Details

preventDefault

selectConversationEvent.preventDefault()
Prevents the clicked conversation from being selected.

Parameters

None.

Returns

void

interface SendMessageEvent

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

Properties

conversation
: ConversationData

The current conversation object

interface ConversationData

custom
: CustomData

Contains custom metadata for the conversation if it was set using ConversationBuilder.custom.

id
: string

The ID of the conversation

photoUrl
: string | null

Contains the URL of a photo was set using ConversationBuilder.subject.

subject
: string | null

Contains the conversation subject if it was set using ConversationBuilder.subject.

welcomeMessages
: Array<string> | null

One or more welcome messages that will display to the user as a SystemMessage

Deprecated topicId
: string | null

Deprecated.

Please use ConversationBuilder.subject instead.

The current TalkJS user

interface UserData

availabilityText
: string | null

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

custom
: CustomData

Allows you to set custom metadata for the User

id
: string | number

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

locale
: string | null

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

name
: string

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

photoUrl
: string | null

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

role
: string | null

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.

welcomeMessage
: string | null

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

Deprecated configuration
: string | null

Deprecated.

Please use role instead.

message
: SentMessage

The message that was sent

interface SentMessage

A message that was sent to TalkJS

attachment (optional)
: {    url: string     size: number}

Only given if the message contains a file. An object with the URL and filesize (in bytes) of the given file.

conversationId
: string

The ID of the conversation that the message belongs to

id
: string | undefined

The message ID of the message that was sent

location (optional)
: [number, number]

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]

readBy
: string[]

Contains an Array of User.id's that have read the message

senderId
: string

Contains the user ID for the person that sent the message

text (optional)
: string

Contains the message's text

type
: "UserMessage" | "SystemMessage"

Identifies the message as either a User message or System message

override
: ({    text,     custom,}{    text?: string     custom?: CustomData}) => void

This function allows you to modify the contents of the message or its metadata before the message is sent


interface SentMessage

A message that was sent to TalkJS

Properties

attachment (optional)
: {    url: string     size: number}

Only given if the message contains a file. An object with the URL and filesize (in bytes) of the given file.

conversationId
: string

The ID of the conversation that the message belongs to

id
: string | undefined

The message ID of the message that was sent

location (optional)
: [number, number]

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]

readBy
: string[]

Contains an Array of User.id's that have read the message

senderId
: string

Contains the user ID for the person that sent the message

text (optional)
: string

Contains the message's text

type
: "UserMessage" | "SystemMessage"

Identifies the message as either a User message or System message


class TalkError

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.

Properties

code
: ErrorCode

Machine-readable error code

message
: string

Human-readable error message


interface ThirdPartyOptions

Used to configure supported third-party integrations with TalkJS. See third party integrations

Properties

fullstory (optional)
: FullStoryOptions

interface FullStoryOptions

host (optional)
: string

Fullstory hostname

org
: string

Fullstory organization ID


interface TranslationToggledEvent

This event is triggered when the user toggles real-time message translation using the built-in toggle.

Properties

conversation
: ConversationData

Conversation for which translation has been toggled

interface ConversationData

custom
: CustomData

Contains custom metadata for the conversation if it was set using ConversationBuilder.custom.

id
: string

The ID of the conversation

photoUrl
: string | null

Contains the URL of a photo was set using ConversationBuilder.subject.

subject
: string | null

Contains the conversation subject if it was set using ConversationBuilder.subject.

welcomeMessages
: Array<string> | null

One or more welcome messages that will display to the user as a SystemMessage

Deprecated topicId
: string | null

Deprecated.

Please use ConversationBuilder.subject instead.

isEnabled
: boolean

Boolean indicating if translation is enabled or not


interface UserData

Properties

availabilityText
: string | null

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

custom
: CustomData

Allows you to set custom metadata for the User

interface CustomData

Used to store additional metadata on users, conversations and messages

[key] (optional)
: string

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

id
: string | number

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

locale
: string | null

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

name
: string

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

photoUrl
: string | null

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

role
: string | null

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.

welcomeMessage
: string | null

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

Deprecated configuration
: string | null

Deprecated.

Please use role instead.