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

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}