Chatbox

This component represents a messaging UI for a single conversation.

A Chatbox MUST be a descendant of Session. It does not need to be a direct descendant. Check out the example below.

Props

NameTypeDescription
conversationBuilder Required
ConversationBuilderRepresents the conversation to be shown in the UI.
loadingComponent
ReactNodeA component that will be displayed while the UI is loading.
asGuest
booleanIt used to join the conversation as a guest, with limited functions. You can read more about this feature here.
captureKeyboardEvents
booleanEnables capturing on("keyup") events.

Setting this to true also disables any non-standard keyboard shortcuts in TalkJS. Currently, the only such shortcut is that when captureKeyboardEvents is disabled, TalkJS will auto-focus the message field if the user starts typing but no input field is focused.
dir
"rtl" | "ltr"Controls the text direction (for supporting right-to-left languages such as Arabic and Hebrew). TalkJS tries to determine the appropriate text direction from the parent page, but if that does not work or you want to explicitly control it, you can override it here. Defaults to "rtl".
messageField
MessageFieldOptionsSettings that affect the behavior of the message field
messageFilter
MessagePredicateUsed to control which messages are shown in the message list, depending on a type, origin, sender or custom message attributes.
showChatHeader
booleanUsed to control if the chat header is displayed in the UI. Defaults to true.
showTranslationToggle
boolean | "auto"Set this to true to show a translation toggle in all conversations. Set this to "auto" to show a translation toggle in conversations where there are participants with different locales. This setting defaults to false, meaning that no toggles will be shown. In order to use this, you must be on the Growth plan or above, and set a Google Translate API key in the dashboard.
theme
string | ThemeOptionsOverrides the theme used for this chat UI.
This only works with themes created in the Theme Editor.
If you omit this field, the UI uses the theme that is selected in the current user's role.
enableTranslation
booleanEnable or disable translation for a conversation. Defaults to false.
highlightedWords
string[]This enables you to highlight certain words in messages. Remove the prop or pass an empty array to disable highlighting. Note: this feature only works on the Growth plan and above.
presence
PresenceOptionsSets metadata for the current session
onKeyup
KeyupHandlerTriggers a KeyupEvent when the user releases a key
onSendMessage
SendMessageHandlerTriggers when the user sends a message using the TalkJS UI
onTranslationToggled
TranslationToggledHandlerTriggers when the user toggles translation in a conversation
translateConversations
boolean | "auto" | string[] | ConversationBuilderTalkJS can translate conversations to the current user's locale using Google Translate. This option specifies which conversations should be translated in this UI. You can pass a boolean to enable/disable translation for all conversations, "auto" to enable translation on conversations where users have different locales, or you can pass an array of conversation Ids to be translated. This feature is only available on the Growth plan and above. Make sure you add your Google Translate API key in the dashboard.
onBlur
Deprecated
BlurHandlerTriggers when the chat UI gets unfocused (i.e. the user clicks/taps anywhere outside it)
onFocus
Deprecated
FocusHandlerTriggers when the chat UI gets focused (i.e. the user clicks/taps anywhere inside it)
thirdparties
Deprecated
ThirdPartyOptionsTalkJS leverages iframes behind the scenes and therefore not all services that you use in your app will work out of the box. This option adds support for a number of services to help you use them. Let us know if you're missing any.
chatSubtitleMode
Deprecated
"subject" | "participants" | nullControls what text appears in the chat subtitle, right below the chat title. No subtitle is displayed when the conversation has no subject set or when set to null. Defaults to "subject".
chatTitleMode
Deprecated
"subject" | "participants"Controls what text appears in the chat title, in the header above the messages. Defaults to "participants".

Properties

FieldTypeDescription
messageField
MessageFieldEncapsulates the message entry field tied to the currently selected conversation.

Methods

sendLocation

Send the user's current location to the currently active conversation.

The behaviour of this method is identical to the user clicking the location button in message field i.e the confirmation dialog is shown.

sendLocation(): void;

Returns

void

getCurrentConversation

Retrieves the conversation currently shown in the UI.

The result is null when the selected conversation could not be found.

getCurrentConversation(): Promise<ConversationData | null>

Returns

Promise<ConversationData | null>

onLeaveConversation

Triggers when the user clicks on the "Leave conversation" action.

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.

onLeaveConversation(handler: LeaveConversationHandler): Subscription;

Parameters

NameTypeDescription
handler RequiredLeaveConversationHandlerThe handler to be called.

Returns

Subscription

onCustomMessageAction

Triggers when a user launches a custom action on a message within the TalkJS UI.

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.

onCustomMessageAction(action: string, handler: CustomMessageActionHandler): Subscription;

Parameters

NameTypeDescription
action RequiredstringThe action you want to listen for
handler RequiredCustomMessageActionHandlerThe handler to be called

Returns

Subscription

onCustomConversationAction

Triggers when a user launches a custom action on a conversation within the TalkJS UI.

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.

onCustomConversationAction(action: string, handler: CustomConversationActionHandler): Subscription

Parameters

NameTypeDescription
action RequiredstringThe action you want to listen for
handler RequiredCustomConversationActionHandlerThe handler to be called

Returns

Subscription

off

Used to stop listening to TalkJS events.

off(eventType: 'blur' | 'focus' | 'sendMessage' | 'translationToggled'): void;

Parameters

NameTypeDescription
eventType Required'blur' | 'focus' | 'sendMessage' | 'translationToggled'The event you want to stop listening to.

Returns

void

setTranslationEnabledDefault

Enable/disable translation by default. This setting is applied to any conversation for which you haven't set a specific value.

setTranslationEnabledDefault(enabled: boolean | 'auto'): void

Parameters

NameTypeDescription
enabled Requiredboolean | 'auto'Whether conversations should be translated by default or not. Pass "auto" to enable translation for conversations with users with different locales. Default: false.

Returns

void


Example

TSX
import * as React from 'react';
import * as TalkRn from '@talkjs/react-native';
export default function App() {
const chatboxRef = React.useRef<TalkRn.ChatboxRef>(null);
React.useEffect(() => {
/* Stop listening to the focus event.
A handler for this event has been set in Chatbox below. */
chatboxRef!.current!.off('focus');
});
const user: TalkRn.User = {
id: '123456789',
name: 'Alice',
photoUrl: 'https://talkjs.com/images/avatar-1.jpg',
welcomeMessage: 'Hey there! How are you? :-)',
role: 'default',
};
const other: TalkRn.User = {
id: '432156789',
name: 'Sebastian',
photoUrl: 'https://talkjs.com/images/avatar-5.jpg',
welcomeMessage: 'Hey, how can I help? https://google.com',
role: 'default',
};
const conversationId = TalkRn.oneOnOneId(user.id, other.id);
const conversationBuilder = TalkRn.getConversationBuilder(conversationId);
conversationBuilder.setParticipant(user);
conversationBuilder.setParticipant(other, { notify: false });
conversationBuilder.setAttributes({ subject: 'Random conversation' });
return (
<TalkRn.Session appId='YOUR_APP_ID' me={user} enablePushNotifications={true}>
<TalkRn.Chatbox
ref={chatboxRef}
conversationBuilder={conversationBuilder}
messageField={{
enterSendsMessage: false,
placeholder: 'Type a message'
}}
highlightedWords={['me', 'you']}
onBlur={(event) => console.log('onBlur: ', event)}
onFocus={(event) => console.log('onFocus: ', event)}
onSendMessage={(event) => console.log('onSendMessage: ', event)}
>
</TalkRn.Session>
)
}

Type Definitions

KeyupHandler

Triggers a KeyupEvent when the user releases a key.

This event is only emitted when captureKeyboardEvents is enabled. In that case, it is emitted for every keypress, including regular letters typed into text fields.

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.

All other event fields are the same as the corresponding fields in the browser's KeyboardEvent.

type KeyupHandler = (event: KeyupEvent) => void;

KeyupEvent

Emitted through on("keyup") when the user presses a key. All fields except isInputFocused precisely match the corresponding fields in the browser's KeyboardEvent.

Properties

FieldTypeDescription
isInputFocusedbooleanTrue if the event was triggered while an element was focused that can handle keyboard events.
altKeyboolean
ctrlKeyboolean
metaKeyboolean
shiftKeyboolean
codestring
keystring
locationnumber

SendMessageHandler

Triggers when the user sends a message using the TalkJS UI

type SendMessageHandler = (event: SendMessageEvent) => void;

SendMessageEvent

This event is triggered before the message is sent to TalkJS.

Properties

FieldTypeDescription
conversationConversationDataThe current conversation object
meUserDataThe current TalkJS user. The email and phone fields are suppressed as stated here.
messageSentMessageThe message that was sent

LeaveConversationHandler

Triggers when the user clicks on the "Leave conversation" action

type LeaveConversationHandler = (event: LeaveConversationEvent) => void;

LeaveConversationEvent

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.

Properties

FieldTypeDescription
conversationConversationDataThe conversation that the user intends to leave

CustomMessageActionHandler

Triggers when the user clicks on a given custom action on a message within the Chatbox.

type CustomMessageActionHandler = (event: MessageActionEvent) => void;

MessageActionEvent

This event is emitted from Chatbox.onCustomMessageAction when a user clicks on custom action defined in the dashboard.

Properties

FieldTypeDescription
actionstringThe action you were listening for
messageMessageThe message where the custom action was clicked.

Message

A TalkJS message.

FieldTypeDescription
idstringThe message's ID.
conversationConversationDataContains the conversation data that the message belongs to.
isByMebooleantrue if the message was sent by the current user.
senderIdstring | nullThe senderID (userID) for the person that sent the message.
senderUserData | nullThe user that sent the message.
bodystringContains the message's content
type"media" | "text" | "location"Specified if the message is media (file), text or a shared location.
timestampnumberUNIX timestamp specifying when the message was sent (UTC, in milliseconds)
readbooleantrue if the message has been read, false when it has not been seen yet.
originstringDetermines 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
customCustomDataAllows you to set custom metadata for the Message. Set any property to null to delete the existing value (if any). When omitted or undefined, the existing value remains unchanged.
attachment{url: string; size: number} | nullOnly given if the message's type equals "media". An object with the URL and filesize (in bytes) of the given file.
location[number, number] | nullOnly 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.

CustomConversationActionHandler

Triggers when the user clicks on a given Conversation Action.

type CustomConversationActionHandler = (event: ConversationActionEvent) => void;

ConversationActionEvent

This event is emitted from Chatbox​.onCustomConversationAction when a user clicks on a custom action in a conversation within the TalkJS UI.

Properties

FieldTypeDescription
actionstringThe action you were listening for
conversationConversationDataThe conversation where the action was clicked.

BlurHandler

Triggers when the chat UI gets unfocused (i.e. the user clicks/taps anywhere outside it)

type BlurHandler = (event: BlurEvent) => void;

BlurEvent is an empty object

FocusHandler

Triggers when the chat UI gets focused (i.e. the user clicks/taps anywhere inside it)

type FocusHandler = (event: FocusEvent) => void;

FocusEvent is an empty object

TranslationToggledHandler

Triggers when the user toggles translation in a conversation

type TranslationToggledHandler = (event: TranslationToggledEvent) => void;

TranslationToggledEvent

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

Properties

FieldTypeDescription
isEnabledbooleanIndicates if translation is enabled or not
conversationConversationDataThe Conversation for which translation has been toggled.

ConversationData

This object represents data associated with a conversation.

The subject, photoUrl, custom and welcomeMessages properties can be set through ConversationBuilder.setAttributes.

Example

{
id: '87d70908d90cee5d12bd',
subject: 'Random conversation',
photoUrl: null,
topicId: null,
welcomeMessages: null,
custom: {}
}

Properties

FieldTypeDescription
idstringThe ID of the conversation
customCustomDataContains custom metadata for the conversation.
subjectstring | nullContains the conversation subject.
photoUrlstring | nullContains the URL of a photo.
welcomeMessagesstring[] | nullOne or more welcome messages displayed to the user as SystemMessage.
topicId Deprecatedstring | nullDeprecated

UserData

Properties

FieldTypeDescription
idstring | numberThe unique ID which is used to identify the user in TalkJS.
namestringThe user's name which will be displayed on the TalkJS UI.
photoUrlstring | nullAn optional URL to a photo which will be displayed as the user's avatar.
welcomeMessagestring | nullThe default message a user sees when starting a chat with that person.
rolestring | nullTalkJS supports multiple sets of settings, called "roles". These allow you to change the behaviour of TalkJS for different users. You have full control over which user gets which configuration.
customCustomDataAllows 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.
availabilityTextstring | nullAvailability acts similarly to welcomeMessage but appears as a System Message
localestring | nullThe locale field expects an IETF language tag. See the localization documentation

MessageFieldOptions

Example

{
autofocus: 'smart',
enterSendsMessage: false,
placeholder: 'Send a message',
spellcheck: true,
visible: {
// Show the message field only if user access is set to 'ReadWrite'
access: ['==', 'ReadWrite']
}
}

Properties

FieldTypeDescription
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.
enterSendsMessage (optional)booleanIf 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)stringOverrides 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)booleanSpecifies 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. Using a ConversationPredicate lets you show/hide the message field based on properties of the current conversation. Defaults to true.

MessagePredicate

Lets you show only specific messages in the chat panel.

Examples

// Assuming you have set a `category` custom field in your messages.
// Only show messages that have no category set:
{
custom: {
category: '!exists'
}
}

Properties

FieldTypeDescription
custom (optional)CustomPredicateOnly select messages that have particular custom fields set to particular values. It is not necessary for all messages to have these fields.
type (optional)FieldPredicate<"UserMessage" | "SystemMessage">Only show messages of a given type
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").
sender (optional)SenderFieldPredicateOnly show messages that are sent by a sender that has all of the given properties

SenderFieldPredicate

Example

{
id: ["oneOf", ["1", "5"]],
locale: ["==", "nl-NL"],
role: ["!=", "default"],
custom: {
category: ["==", "shoes"]
}
}

Properties

FieldTypeDescription
id (optional)FieldPredicate<string>Only show messages sent by users with the specified id(s).
locale (optional)FieldPredicate<string>Only show messages sent by users with the specified locale
role (optional)FieldPredicate<string>Only show messages sent by users with the specified role
custom (optional)CustomPredicateOnly show messages sent by users that have particular custom fields set to particular values.

Properties

FieldTypeDescription
[key: string]CustomFieldPredicateEvery key must correspond to a key in the custom data that you have set.