<Chatbox> | <t-chatbox>

The Chatbox component represents a chatbox UI for a single conversation.

Properties

appId
: string Required
HTML attribute: app-id

Your app's unique TalkJS ID. Get it from the Settings page of the dashboard.

userId
: string Required
HTML attribute: user-id

The ID of the current user.

conversationId
: string Required
HTML attribute: conversation-id

The ID of the conversation to display.

theme
: string Required
HTML attribute: theme

The theme to use.

token
: string
HTML attribute: token

A token to authenticate the session with. See our Authentication guide and Token reference for details and examples.

tokenFetcher
: () => string | Promise<string>
No HTML attribute

A function that fetches and returns a new authentication token from your server. TalkJS calls this function whenever the current token is about to expire. This callback is designed to work with any backend setup. See Refreshable tokens for details and examples.

enterSendsMessage
: boolean
HTML attribute: enter-sends-message

When 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 the Send button. Defaults to true.

chatHeaderVisible
: boolean
HTML attribute: chat-header-visible

Sets whether the chat header is visible. Defaults to true.

messageFieldVisible
: boolean
HTML attribute: message-field-visible

Sets whether the message input field is visible. Defaults to true.

messageFieldSpellcheck
: boolean
HTML attribute: message-field-spellcheck

Sets whether spellcheck is enabled in the message field. Defaults to false.

messageFieldPlaceholder
: string
HTML attribute: message-field-placeholder

Adds custom placeholder text for the message input field. The default placeholder text is "Say something...".

onDeleteMessage
: (e: DeleteMessageEvent) => void
No HTML attribute

Function that triggers when the user deletes a message with the TalkJS UI. It receives a DeleteMessageEvent as an argument.

onSendMessage
: (e: SendMessageEvent) => void
No HTML attribute

Function that triggers when the user sends a message with the TalkJS UI. It receives a SendMessageEvent as an argument.

themeCustom
: any
No HTML attribute

Whatever value you pass here is available for you to use in your theme components as the themeCustom prop.

Examples

This section gives some examples that demonstrate how to use the Chatbox component.

Create a chatbox with an existing user and conversation

Create a chatbox and pass it an existing user, conversation, and the default theme:

1<Chatbox
2  appId="<APP_ID>"
3  userId="sample_user_alice"
4  conversationId="sample_conversation"
5  theme={defaultTheme}
6/>

Create a chatbox with a new user and conversation

Install the @talkjs/core package, which lets you read, subscribe to, and update your chat data:

1npm install @talkjs/core

Import it into the component where you want to use it:

1import { getTalkSession } from '@talkjs/core';

Then create the session, user and conversation:

1const appId = '<APP_ID>';
2const userId = 'frank';
3const conversationId = 'new_conversation';
4const session = getTalkSession({ appId, userId });
5

6useEffect(() => {
7  session.currentUser.createIfNotExists({ name: 'Frank' });
8  const conversation = session.conversation(conversationId);
9  conversation.createIfNotExists();
10}, [session, conversationId]);

Pass the new user and conversation to your chatbox:

1<Chatbox
2  appId={appId}
3  userId={userId}
4  conversationId={conversationId}
5  theme={defaultTheme}
6/>

If you are using Components without a package manager, see our guide.

Hide the chat header

Hide the chat header:

1<Chatbox
2  appId="<APP_ID>"
3  userId="sample_user_alice"
4  conversationId="sample_conversation"
5  theme={defaultTheme}
6  chatHeaderVisible={false}
7/>

Respond to events

Respond to a sent message event by printing details to the console:

1<Chatbox
2  appId="<APP_ID>"
3  userId="sample_user_alice"
4  conversationId="sample_conversation"
5  theme={defaultTheme}
6  onSendMessage={(event) => {
7    console.log('Message sent: ', event.message);
8  }}
9/>

Event interfaces

The following interfaces define the event objects that are passed to chatbox properties.

DeleteMessageEvent

Event object passed to the onDeleteMessage callback. Contains a UserSnapshot, MessageSnapshot and ConversationSnapshot.

1export interface DeleteMessageEvent {
2  currentUser: UserSnapshot;
3  message: MessageSnapshot;
4  conversation: ConversationSnapshot;
5}

SendMessageEvent

Event object passed to the onSendMessage callback. Contains a UserSnapshot, MessageSnapshot and ConversationSnapshot.

1export interface SendMessageEvent {
2  currentUser: UserSnapshot;
3  message: MessageSnapshot;
4  conversation: ConversationSnapshot;
5}