Chatbox
This component represents a messaging UI for a single conversation.
A Chatbox
must be a descendant of Session
.
It doesn't need to be a direct descendant. Check out the example below.
Name | Type | Description |
---|---|---|
ConversationBuilder | The conversation to be shown in the UI | |
ReactNode | A component that is displayed while the UI is loading | |
boolean | Used to join the conversation as a guest. Read more about guest access. | |
string | The ID of the message you want to scroll to and highlight. | |
boolean | Enables 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 turned off, TalkJS autofocuses the message field if the user starts typing but no input field is focused. | |
"rtl" | "ltr" | Controls the text direction to support both left-to-right languages and right-to-left languages, such as Arabic and Hebrew. TalkJS tries to determine the appropriate text direction from the parent page, but if that doesn't work or you want to explicitly control it, you can override it here. Defaults to "rtl" . | |
boolean | Controls whether the user can pinch to zoom the UI. Defaults to false . | |
MessageFieldOptions | Settings that affect the behavior of the message field | |
MessagePredicate | Used to control which messages are shown in the message list, depending on the message's type, origin, sender or custom message attributes | |
boolean | Used to control if the chat header is displayed in the UI. Defaults to true . | |
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 are shown. In order to use this, you must be on the Growth plan or higher, and set a Google Translate API key on the Settings page of your dashboard. | |
string | ThemeOptions | Overrides 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. | |
boolean | Enable or turn off translation for a conversation. Defaults to false . | |
string[] | This enables you to highlight certain words in messages. Remove the prop or pass an empty array to turn off highlighting. Note: this feature only works on the Growth plan or higher. | |
PresenceOptions | Sets metadata for the current session | |
ConversationActionHandler | Triggers a ConversationActionEvent when the user clicks on a given conversation action | |
MessageActionHandler | Triggers a MessageActionEvent when the user clicks on a given custom action on a message within the Chatbox | |
KeyupHandler | Triggers a KeyupEvent when the user releases a key | |
LeaveConversationHandler | Triggers a LeaveConversationEvent when the user clicks the "Leave conversation" action | |
SendMessageHandler | Triggers when the user sends a message using the TalkJS UI | |
TranslationToggledHandler | Triggers when the user toggles translation in a conversation | |
boolean | "auto" | string[] | ConversationBuilder | TalkJS 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 or turn off 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 or higher. Make sure you add your Google Translate API key on the Settings page of your dashboard. | |
BlurHandler | Triggers when the chat UI gets unfocused, that is, the user clicks or taps anywhere outside the chat | |
FocusHandler | Triggers when the chat UI gets focused, that is, the user clicks or taps anywhere inside the chat | |
ThirdPartyOptions | TalkJS leverages iframes behind the scenes. As a result, some services that you use in your app won't 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. | |
"subject" | "participants" | null | Controls 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" . | |
"subject" | "participants" | Controls what text appears in the chat title, in the header above the messages. Defaults to "participants" . |
Field | Type | Description |
---|---|---|
MessageField | Encapsulates the message entry field tied to the currently selected conversation |
Send the user's current location to the currently active conversation.
The behavior of this method is identical to the user clicking the location button in the message field, that is, the confirmation dialog is shown.
1sendLocation(): void;
void
Retrieves the conversation currently shown in the UI.
The result is null
when the selected conversation couldn't be found.
1getCurrentConversation(): Promise<ConversationData | null>
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 doesn't trigger.
1onLeaveConversation(handler: LeaveConversationHandler): Subscription;
Name | Type | Description |
---|---|---|
handler Required | LeaveConversationHandler | The handler to be called. |
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 on the Chat UI page of your dashboard. 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. Names are 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 the REST API.
1onCustomMessageAction(action: string, handler: CustomMessageActionHandler): Subscription;
Name | Type | Description |
---|---|---|
action Required | string | The action you want to listen for |
handler Required | CustomMessageActionHandler | The handler to be called |
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 on the Chat UI page of your dashboard. 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. Names are 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 the REST API.
1onCustomConversationAction(action: string, handler: CustomConversationActionHandler): Subscription
Name | Type | Description |
---|---|---|
action Required | string | The action you want to listen for |
handler Required | CustomConversationActionHandler | The handler to be called |
Used to stop listening to TalkJS events.
1off(eventType: 'blur' | 'focus' | 'sendMessage' | 'translationToggled'): void;
Name | Type | Description |
---|---|---|
eventType Required | 'blur' | 'focus' | 'sendMessage' | 'translationToggled' | The event you want to stop listening to |
void
Enable or turn off translation by default. This setting is applied to any conversation for which you haven't set a specific value.
1setTranslationEnabledDefault(enabled: boolean | 'auto'): void
Name | Type | Description |
---|---|---|
enabled Required | boolean | 'auto' | Whether conversations should be translated by default or not. Pass "auto" to enable translation for conversations with users with different locales. Default: false . |
void
1import * as React from 'react';2import * as TalkRn from '@talkjs/react-native';34export default function App() {5 const chatboxRef = React.useRef<TalkRn.ChatboxRef>(null);67 React.useEffect(() => {8 /* Stop listening to the focus event.910 A handler for this event has been set in Chatbox below. */11 chatboxRef!.current!.off('focus');12 });1314 const user: TalkRn.User = {15 id: '123456789',16 name: 'Alice',18 photoUrl: 'https://talkjs.com/images/avatar-1.jpg',19 welcomeMessage: 'Hey there! How are you? :-)',20 };2122 const other: TalkRn.User = {23 id: '432156789',24 name: 'Sebastian',26 photoUrl: 'https://talkjs.com/images/avatar-5.jpg',27 welcomeMessage: 'Hey, how can I help? https://google.com',28 };2930 const conversationId = TalkRn.oneOnOneId(user.id, other.id);31 const conversationBuilder = TalkRn.getConversationBuilder(conversationId);3233 conversationBuilder.setParticipant(user);34 conversationBuilder.setParticipant(other, { notify: false });3536 conversationBuilder.setAttributes({ subject: 'Random conversation' });3738 return (39 <TalkRn.Session appId='<APP_ID>' me={user} enablePushNotifications={true}>40 <TalkRn.Chatbox41 ref={chatboxRef}42 conversationBuilder={conversationBuilder}43 messageField={{44 enterSendsMessage: false,45 placeholder: 'Type a message'46 }}47 highlightedWords={['me', 'you']}48 onBlur={(event) => console.log('onBlur: ', event)}49 onFocus={(event) => console.log('onFocus: ', event)}50 onSendMessage={(event) => console.log('onSendMessage: ', event)}51 >52 </TalkRn.Session>53 )54}
You'll need to replace <APP_ID>
with your TalkJS App ID. You can find your App ID in the Settings tab of the TalkJS dashboard.
Triggers a KeyupEvent
when the user releases a key.
This event is only emitted when captureKeyboardEvents
is enabled.
In that case, it's emitted for every keypress, including regular letters typed into text fields.
event.isInputFocused
is true when a TalkJS input area is focused (such as 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.
1type KeyupHandler = (event: KeyupEvent) => void;
Emitted through on("keyup")
when the user presses a key. All fields except isInputFocused
precisely
match the corresponding fields in the browser's KeyboardEvent.
Field | Type | Description |
---|---|---|
isInputFocused | boolean | True if the event was triggered while an element was focused that can handle keyboard events |
altKey | boolean | |
ctrlKey | boolean | |
metaKey | boolean | |
shiftKey | boolean | |
code | string | |
key | string | |
location | number |
Triggers when the user sends a message using the TalkJS UI.
1type SendMessageHandler = (event: SendMessageEvent) => void;
This event is triggered before the message is sent to TalkJS.
Field | Type | Description |
---|---|---|
conversation | ConversationData | The current conversation object |
me | UserData | The current TalkJS user. Sensitive data, such as a user's email or phone , are suppressed for privacy and security reasons. |
message | SentMessage | The message that was sent |
Triggers when the user clicks on the "Leave conversation" action.
1type LeaveConversationHandler = (event: LeaveConversationEvent) => void;
This event only triggers when the user performs an action to leave a conversation from inside the chat UI. When a user leaves the conversation through other means (for example, they're removed from the conversation using the REST API), this event doesn't trigger.
Field | Type | Description |
---|---|---|
conversation | ConversationData | The conversation that the user intends to leave |
Triggers when the user clicks on a given custom action on a message within the Chatbox.
1type CustomMessageActionHandler = (event: MessageActionEvent) => void;
This event is emitted from Chatbox.onCustomMessageAction
when a user clicks on custom action defined in the dashboard.
Field | Type | Description |
---|---|---|
action | string | The action you were listening for |
message | Message | The message where the custom action was clicked |
Triggers when the user clicks on a given Conversation Action.
1type CustomConversationActionHandler = (event: ConversationActionEvent) => void;
This event is emitted from Chatbox​.onCustomConversationAction
when a user clicks on a custom action in a conversation within the TalkJS UI.
Field | Type | Description |
---|---|---|
action | string | The action you were listening for |
conversation | ConversationData | The conversation where the action was clicked |
Triggers when the chat UI gets unfocused, that is, when the user clicks or taps anywhere outside of the chat.
1type BlurHandler = (event: BlurEvent) => void;
BlurEvent
is an empty object.
Triggers when the chat UI gets focused, that is, when the user clicks or taps anywhere inside the chat.
1type FocusHandler = (event: FocusEvent) => void;
FocusEvent
is an empty object
Triggers when the user toggles translation in a conversation.
1type TranslationToggledHandler = (event: TranslationToggledEvent) => void;
This event is triggered when the user toggles real-time message translation using the built-in toggle.
Field | Type | Description |
---|---|---|
isEnabled | boolean | Indicates if translation is enabled or not |
conversation | ConversationData | The conversation for which translation has been toggled |
1{2 autofocus: 'smart',3 enterSendsMessage: false,4 placeholder: 'Send a message',5 spellcheck: true,6 visible: {7 // Show the message field only if user access is set to 'ReadWrite'8 access: ['==', 'ReadWrite']9 }10}
Field | Type | Description |
---|---|---|
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 this is possible without negative side effects. |
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. 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. Using a ConversationPredicate lets you show or hide the message field based on properties of the current conversation. Defaults to true . |
Lets you show only specific messages in the chat panel.
1// Assuming you have set a `category` custom field in your messages.2// Only show messages that have no category set:3{4 custom: {5 category: '!exists';6 }7}
Field | Type | Description |
---|---|---|
custom (optional) | CustomPredicate | Only select messages that have particular custom fields set to particular values. It's 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) | SenderFieldPredicate | Only show messages that are sent by a sender that has all of the given properties |
1{2 id: ["oneOf", ["1", "5"]],3 locale: ["==", "nl-NL"],4 role: ["!=", "default"],5 custom: {6 category: ["==", "shoes"]7 }8}
Field | Type | Description |
---|---|---|
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) | CustomPredicate | Only show messages sent by users that have particular custom fields set to particular values |
Field | Type | Description |
---|---|---|
[key: string] | CustomFieldPredicate | Every key must correspond to a key in the custom data that you have set |