<t-inbox>

The <t-inbox> web component combines a Chatbox with a ConversationList into a single responsive UI.

It is a thin wrapper around these two components, and accepts a combination of attributes from both. For example:


1<t-inbox
2  app-id="<APP_ID>"
3  user-id="sample_user_alice"
4></t-inbox>

This will show an inbox with all conversations of sample_user_alice listed on the left, and the selected conversation on the right.

The inbox is responsive, and by default switches to a mobile-friendly layout when the width is less than 700px. You can change the mobile breakpoint by passing a different value to the mobile-break-point attribute.

interface InboxProps

The Inbox takes all prop from Chatbox and all props from ConversationList.

Properties

app-id

: string

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

user-id

: string

The ID of the current user.

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

before-browser-permission-prompt (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.

chat-header-visible (optional)

: boolean

Sets whether the chat header is visible.

Defaults to true.

enter-sends-message (optional)

: boolean

When true, pressing Enter will send a message.

Defaults to true.

message-field-placeholder (optional)

: string

Adds custom placeholder text for the message input field.

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

message-field-spellcheck (optional)

: boolean

Sets whether spellcheck is enabled in the message field.

Defaults to false.

message-field-visible (optional)

: boolean

Sets whether the message input field is visible.

Defaults to true.

mobile-break-point (optional)

: number

The container width at which the Inbox switches to mobile mode.

When the container is less wide than this amount of pixels, the inbox will only show a chatbox or a conversation list, and the chatbox header will show a back button to move back to the conversation list.

When the inbox is in mobile mode, the inbox element will get a t-mobile-inbox attribute. This attribute is used in e.g. the CSS of the ChatHeader theme component to determine whether or not to show the back button.

on-delete-message (optional)

: (event: DeleteMessageEvent) => void

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

on-message-action (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.

on-missing-browser-permission (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.

on-select-conversation (optional)

: (event: SelectConversationEvent) => void

Callback that triggers when the user selects a conversation from the list.

Note that updating the selected conversation through the selectedConversationId prop **will not** trigger this callback.

Use this callback to have an adjacent chatbox show the correct conversation. See Respond to a select conversation event.

on-send-message (optional)

: (event: SendMessageEvent) => void

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

selected-conversation-id (optional)

: string

The ID of the conversation currently selected in the list.

Changing the value of this prop will cause the ConversationList UI to update.

Note that updating the selected conversation through this prop **will not** trigger the onSelectConversation callback.

theme (optional)

: Partial<Theme>

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

See Custom theme components for more info.

theme-custom (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.

class InboxElement

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

Method Overview

selectConversation

Select a conversation.

Properties

chatbox

: ChatboxController

The ChatboxController object of the underlying chatbox

This lets you programmatically control the chatbox side of this inbox, ie the right panel. For example, to control the message field text:


1// Obtain a reference to the inbox object, eg:
2// const inbox = inboxRef.current; // react
3// const inbox = document.querySelector("t-inbox") // web
4// const inbox = inboxRef.value // vue
5// etc
6
7inbox.chatbox.setMessageFieldText("Hey there");

selectConversation

inboxController.selectConversation(conversationId)

Select a conversation.

This method is called from the theme's ConversationListItem component when the user clicks on the given conversation. You can also call it programmatically from elsewhere to simulate a user click.

This method will trigger the InboxProps.onSelectConversation event. In most cases, if you want to change the selected conversation programmatically from outside the conversation list, it's better to pass a different value to the InboxProps.selectedConversationId prop instead, as that lets you keep your local state in sync with the props passed to the conversation list.

Parameters

conversationId

: string

Returns

void

Examples

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

Create an inbox with an existing user

Create an inbox and pass it an existing user and the default theme:

HTML


1<t-inbox
2  app-id="<APP_ID>"
3  user-id="sample_user_alice"
4/>

Create an inbox with a new user and a new 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 = 'new_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 inbox:

HTML


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

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

Hide the chat header

Control chatbox layout by eg hiding the chat header:

HTML


1<t-inbox
2  app-id="<APP_ID>"
3  user-id="sample_user_alice"
4  chat-header-visible="false"
5/>

Respond to events

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

TXT


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