<t-chatbox>

The <t-chatbox> web 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

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.

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.

onDeleteMessage (optional)

: (event: DeleteMessageEvent) => void

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

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 for Chatbox theme components and through 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 ChatboxElement

The t-chatbox element is a custom element that extends the HTMLElement class. It exposes the following methods:

Method Overview

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.

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

Examples

The following gives some examples of how to use the t-chatbox component.

Create a chatbox with an existing user and conversation

Create a chatbox and pass it an existing user and conversation:

HTML


1<t-chatbox
2  app-id="<APP_ID>"
3  user-id="sample_user_alice"
4  conversation-id="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 the @talkjs/core package into the component where you want to use it:


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

Then create the session, user, and conversation:

TS


1appId = '<APP_ID>';
2userId = 'sebastian';
3conversationId = 'my_conversation';
4session: TalkSession | null = null;
5
6ngOnInit() {
7  this.session = getTalkSession({
8    appId: this.appId,
9    userId: this.userId,
10  });
11  this.session.currentUser.createIfNotExists({ name: 'Sebastian' });
12  const conversation = this.session.conversation(this.conversationId);
13  conversation.createIfNotExists();
14}

Pass the new user and conversation to your chatbox:

HTML


1<t-chatbox
2  [app-id]="appId"
3  [user-id]="userId"
4  [conversation-id]="conversationId"
5/>

If you're using web components without a package manager, see the following guide.

Hide the chat header

Hide the chat header:

HTML


1<t-chatbox
2  app-id="<APP_ID>"
3  user-id="sample_user_alice"
4  conversation-id="sample_conversation"
5  [chat-header-visible]="false"
6/>

If you hide the chat header, other UI elements remain visible by default.

Respond to events

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

TXT


1// chat.component.html
2<t-chatbox
3  app-id="<APP_ID>"
4  user-id="sample_user_alice"
5  conversation-id="sample_conversation"
6  (sendMessage)="onSendMessage($event)"
7></t-chatbox>
8
9// chat.component.ts
10onSendMessage(event: any): void {
11  console.log("Message sent:", event.message);
12}