<Chatbox>

The <Chatbox> React component represents a chatbox UI for a single conversation, and integrates with the user's TalkJS session.

Props

appId
: string Required

Your app's unique TalkJS ID. You can find it on the Settings page of the TalkJS dashboard.

userId
: string Required

The ID of the current user.

conversationId
: string Required

The ID of the conversation to display.

theme
: Theme

Optional. The name of the theme to apply to the chatbox. A theme is a collection of React components and styles that allow you to customize the appearance and behavior of your chat. By default, a preset theme is provided, which you can override by using a custom theme. See Customize your theme.

token
: string

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

Required when authentication is enabled, otherwise optional.

tokenFetcher
: () => string | Promise<string>

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

Optional. When set to true, pressing the Enter key sends the message, as long as there's text in the message field. When set to false, users can only send a message with the Send button. Defaults to true.

chatHeaderVisible
: boolean

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

messageFieldVisible
: boolean

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

messageFieldSpellcheck
: boolean

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

messageFieldPlaceholder
: string

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

onDeleteMessage
: (e: DeleteMessageEvent) => void

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

onSendMessage
: (e: SendMessageEvent) => void

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

themeCustom
: any

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

Examples

The following gives some examples of 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/>

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 = 'sebastian';
3const conversationId = 'new_conversation';
4const session = getTalkSession({ appId, userId });
5

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

Pass the new user and conversation to your chatbox:

1<Chatbox appId={appId} userId={userId} conversationId={conversationId} />

Hide the chat header

Hide the chat header:

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

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  onSendMessage={(event) => {
6    console.log('Message sent: ', event.message);
7  }}
8/>

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 a 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 a ConversationSnapshot.

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