<t-inbox>

View as Markdown

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

appId
: string

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

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.

focusedMessageId (optional)
: string

The ID of the currently focused message.

Whenever this value changes to a valid message ID, the relevant message will be scrolled into view.

If you're using a modern web framework like React or Vue, also include an onFocusMessage prop where you'll update your local focusedMessageId state so that it stays in sync with the UI's internals.

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

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.

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

onDeleteMessage (optional)
: (event: DeleteMessageEvent) => void

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

onFocusMessage (optional)
: (event: FocusMessageEvent) => void

Callback that triggers when a message is focused or unfocused.

Note that updating the focused message through the focusedMessageId prop **will not** trigger this callback.

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.

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

onSendMessage (optional)
: (event: SendMessageEvent) => void

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

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

If you're using a modern web framework like React or Vue, also include an onSelectConversation prop where you'll update your local selectedConversationId state so that it stays in sync with the UI's internals.

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.

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 CommonConversationList­Props​.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

Properties

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");

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:

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:

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:

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:

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:

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:

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}