class ChatBox

A messaging UI for just a single conversation.

There is no way for the user to switch between conversations (but you can change the active conversation by changing the conversation parameter of the constructor).

Available Methods

ConstructorCreates a Chatbox UI.


const ChatBox({
Key? key,
required Session session,
TextDirection? dir,
MessageFieldOptions? messageField,
bool? showChatHeader,
TranslationToggle? showTranslationToggle,
String? theme,
TranslateConversations? translateConversations,
MessagePredicate messageFilter = const MessagePredicate(),
Conversation? conversation,
bool? asGuest,
SendMessageHandler? onSendMessage,
TranslationToggledHandler? onTranslationToggled,
LoadingStateHandler? onLoadingStateChanged,
Map<String, MessageActionHandler>? onCustomMessageAction,
NavigationHandler? onUrlNavigation,

Creates a Chatbox UI.

NOTE: All the parameters passed to the constructor are also available as read-only properties of the constructed object.



A Key is an identifier for Flutter Widgets.


The TalkJS Session object to use for this ChatBox.

(optional)TextDirection.rtl | TextDirection.ltr | null

Controls the text direction (for supporting right-to-left languages such as Arabic and Hebrew). TalkJS tries to determine the appropriate text direction from the parent page, but if that does not work or you want to explicitly control it, you can override it here. Defaults to TextDirection.rtl.


Settings that affect the behavior of the message field


Used to control if the Chat Header is displayed in the UI. Defaults to true.

(optional) | TranslationToggle.on | | null

Set this to TranslationToggle.on to show a translation toggle in all conversations. Set this to to show a translation toggle in conversations where there are participants with different locales. This setting defaults to, meaning that no toggles will be shown. In order to use this, you must be on the Growth plan, and set a Google Translate API key in the dashboard.


Overrides the theme used for this chat UI.

This only works with themes created in the Theme Editor.

If you omit this field, the UI uses the theme that is selected in the current user's role.

(optional) | TranslateConversations.on | | null

TalkJS can translate conversations to the current user's locale using Google Translate. This option specifies which conversations should be translated in this UI. You can pass TranslateConversations.on or to enable/disable translation for all conversations, or to enable translation on conversations where users have different locales. This feature is only available on the Growth plan and above. Make sure you add your Google Translate API key in the dashboard.


Used to control which messages are shown in the message list

Lets you filter messages depending on a type, origin or custom message attributes.

See MessagePredicate for all available options.


// only show messages sent by users with role "admin"
messageFilter: MessagePredicate(
sender: SenderPredicate(
role: FieldPredicate.equals('admin'),

Selects the active conversation for the ChatBox.


asGuest can be used to select the conversation as a guest, with limited functions


Triggers when the user sends a message using the TalkJS UI


Triggers when the user toggles translation in a conversation


Triggers when the loading state of the ChatBox changes.

The Getting Started guide has an example on how to use the onLoadingStateChanged callback to show a loading indicator while the ChatBox is loading.

(optional)Map<String, MessageActionHandler>?

Triggers when a user launches a custom action within the TalkJS UI.

To set up a custom action, you need to create it in the role editor. If an action is allowed on a particular message, it'll show up in that message's action menu. The name you specify when setting up the action, is also the key of the Map (case sensitive). The event you get contains information about the message on which the action was called, including its ID, so you can look it up later via our REST API.


onCustomMessageAction: {
'favourite': (event) {
print('Favourited message with id: ${}');
'report': (event) {
print('Reported message with id: ${}');

Triggers when a user clicks on a link that leads outside of the TalkJS app.

The event handler receives the Url of the link that was clicked, and decides whether to allow or deny navigating to that Url.


onUrlNavigation: (navigationRequest) {
print('Attempted to navigate to: ${navigationRequest.url}');
if (navigationRequest.url.contains("twitter")) {
return UrlNavigationAction.deny;
} else {
return UrlNavigationAction.allow;

class MessageFieldOptions

Available Methods

ConstructorThe message field


const MessageFieldOptions({
bool? autofocus,
bool? enterSendsMessage,
String? placeholder,
bool? spellcheck,

The message field

NOTE: All the parameters passed to the constructor are also available as read-only properties of the constructed object.



Determines whether the message field should automatically focus when the user navigates.

Defaults to true, which means that the message field gets focused whenever a conversation is selected, if possible without negative side effects. I.e. only when:

  • The message field is inside the browser viewport (so focusing will not unexpectedly cause the page to scroll)

  • The user is likely on a desktop/laptop computer (so focusing will not unexpectedly expand a mobile on-screen keyboard).


If set to true, pressing the enter key sends the message (if there is text in the message field). When set to false, the only way to send a message is by clicking or touching the "Send" button. Defaults to true.


Overrides the "placeholder" in the message field, which displays a dimmed text when no text has yet been entered.

Defaults to "Say something..." (or a translation thereof).


Specifies whether the spellcheck attribute is set on the message field. Note that setting this to true may also enable autocorrect on some mobile devices. Defaults to false.

Event Handlers


typedef SendMessageHandler = void Function(SendMessageEvent event);

See SendMessageEvent for the callback parameter.


typedef TranslationToggledHandler = void Function(TranslationToggledEvent event);

See TranslationToggledEvent for the callback parameter.


typedef LoadingStateHandler = void Function(LoadingState state);

Notifies when the loading state of the ChatBox changes.

The LoadingState can be either loading or loaded, and it can be useful for showing a placeholder widget while the ChatBox is loading.

The Getting Started guide has an example on how to use the onLoadingStateChanged callback to show a loading indicator while the ChatBox is loading.


typedef MessageActionHandler = void Function(MessageActionEvent event);

See MessageActionEvent for the callback parameter.

typedef NavigationHandler = UrlNavigationAction Function(UrlNavigationRequest navigationRequest);

See UrlNavigationRequest for the callback parameter, and UrlNavigationAction for the callback return value.