<Chatbox>

View as Markdown

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

interface ChatboxProps

Properties

appId

: string

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

conversationId

: string | null

The ID of the conversation to display.

If the conversation doesn't exist or if the current user isn't a participant of the current conversation, a "Chat not found" message will be displayed (after a timeout). If you create the conversation in parallel (eg via the REST API or via the Data API), it will show in the chatbox automatically. This means that you can safely point a chatbox at a conversation that might not yet exist. This way the chatbox UI and the conversation can load in parallel, which results in snappier UX.

Passing null deselects the current conversation and shows an empty panel. This may be useful for Inbox-like scenarios where you want to keep the chatbox loaded, without showing a conversation.

In the background, the Chatbox keeps active subscriptions to recent conversations, so that switching back and forth between conversations has snappy UX.

userId

: string

The ID of the current user.

If the given user ID doesn't exist, a "Something went wrong" message will be displayed.

beforeBrowserPermissionPrompt (optional)

: (request: BrowserPermissionRequest) => void

Callback that triggers when the user initiates an action that will require a permissions request from the browser, but right before actually requesting the permission from the browser.

You can use this callback to inform the user that they will need to grant a browser permission in order to perform an action.

chatHeaderVisible (optional)

: boolean

Sets whether the chat header is visible.

Defaults to true.

enterSendsMessage (optional)

: boolean

When true, pressing Enter will send a message.

Defaults to true.

messageFieldPlaceholder (optional)

: string

Adds custom placeholder text for the message input field.

The default placeholder text is "Say something..."

messageFieldSpellcheck (optional)

: boolean

Sets whether spellcheck is enabled in the message field.

Defaults to false.

messageFieldVisible (optional)

: boolean

Sets whether the message input field is visible.

Defaults to true.

onBackButtonClick (optional)

: (event: BackButtonClickEvent) => void

Fired when the back button in the chat header is clicked.

By default this back button is only shown inside an inbox on small screens. You can change this behavior in the ChatHeader theme.

onDeleteMessage (optional)

: (event: DeleteMessageEvent) => void

Callback that triggers when the user deletes a message with the TalkJS UI.

onMessageAction (optional)

: (event: MessageActionEvent) => void

This event fires when the user clicks an action button or an action Link inside a message.

The event's action and params fields specify the name of action and its parameters, if any.

See Action Buttons and Links for more info.

onMissingBrowserPermission (optional)

: (event: MissingBrowserPermissionEvent) => void

Callback that triggers when the user attempts to initiate an action that requires a specific browser permission, but that permission was not granted.

onSendMessage (optional)

: (event: SendMessageEvent) => void

Callback that triggers when the user sends a message with the TalkJS UI.

theme (optional)

: Partial<Theme>

Lets you override theme components with your own implementations to customize them.

See Custom theme components for more info.

themeCustom (optional)

: any

Arbitrary custom data passed down to the theme.

Whatever data you pass here will be made available for use in theme components through CommonChatboxProps.themeCustom for Chatbox theme components and through CommonConversationListProps.themeCustom for ConversationList theme components.

token (optional)

: 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 (optional)

: () => string | Promise<string>

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.

class ChatboxController

A collection of actions available on the Chatbox UI.

The ref prop lets you obtain a reference to the ChatboxController. For example:


1const chatbox = useRef(null);
2const onSomeEvent = useCallback(() => {
3  chatbox.current.setMessageFieldText("Hello, world!");
4}, [chatbox]);
5
6return (
7  <Chatbox userId="..." ...other props... ref={chatbox} />
8);

Method Overview

clickBackButton	Emits a onBackButtonClick event.
deleteMessage	Deletes the message with the given ID.
editMessage	Edit the message with the given ID.
focusMessageField	Focus the message field
getMessageFieldText	Get the plaintext from the message field
sendFileMessage	Send a file message to the current conversation.
sendLocationMessage	Send a location message to the current conversation.
sendMessage	Send a text message to the current conversation.
setEditing	Enable/disable editing of a given message.
setMessageFieldText	Set the plaintext in the message field
setReferencedMessage	Set/unset the message that's currently being replied to.
toggleReaction	Toggle the given emoji reaction for the given message. If the current user already added this reaction, it's removed, and otherwise, it's added. Called from the theme's Message component when the user clicks on an existing emoji reaction.

clickBackButton

chatboxController.clickBackButton()

Emits a onBackButtonClick event.

Called from the default ChatHeader theme component for the "back" button which is shown when the chatbox is part of an inbox that's being rendered in mobile mode.

Returns

void

deleteMessage

chatboxController.deleteMessage(messageId): Promise<void>

Deletes the message with the given ID.

Parameters

messageId

: string

Returns

Promise<void>

editMessage

chatboxController.editMessage(messageId, params): Promise<void>

Edit the message with the given ID.

Parameters

messageId

: string

params

: EditTextMessageParams | EditMessageParams

Returns

Promise<void>

focusMessageField

chatboxController.focusMessageField()

Focus the message field

Returns

void

getMessageFieldText

chatboxController.getMessageFieldText(): string

Get the plaintext from the message field

Returns

string

The text

sendFileMessage

chatboxController.sendFileMessage(params): Promise<void>

Send a file message to the current conversation.

Parameters

params

: { fileToken: FileToken custom?: Record<string, string> }

Returns

Promise<void>

sendLocationMessage

chatboxController.sendLocationMessage(message): Promise<void>

Send a location message to the current conversation.

Parameters

message

: { location: Coordinates custom?: Record<string, string> }

Returns

Promise<void>

sendMessage

chatboxController.sendMessage(params): Promise<void>

Send a text message to the current conversation.

Parameters

params

: SendTextMessageParams | SendMessageParams

Returns

Promise<void>

setEditing

chatboxController.setEditing(messageId)

Enable/disable editing of a given message.

Parameters

messageId

: string | null

When null is provided, editing mode will be disabled

Returns

void

setMessageFieldText

chatboxController.setMessageFieldText(text)

Set the plaintext in the message field

Parameters

text

: string

Returns

void

setReferencedMessage

chatboxController.setReferencedMessage(messageId)

Set/unset the message that's currently being replied to.

Parameters

messageId

: string | null

When null is provided, the "replying to" message is cleared

Returns

void

toggleReaction

chatboxController.toggleReaction(messageId, emoji): Promise<void>

Toggle the given emoji reaction for the given message. If the current user already added this reaction, it's removed, and otherwise, it's added.

Called from the theme's Message component when the user clicks on an existing emoji reaction.

Parameters

messageId

: string

The ID of the message you want to toggle the reaction on. This message must exist in the current conversation.

emoji

: string

The emoji you want to toggle. Must be a string of a single unicode emoji glyph, eg "🎉".

Returns

Promise<void>

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:

SHELL


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.plaintext);
7  }}
8/>