Chatbox

const ChatBox({
  Key? key,
  required Session session,
  TextDirection? dir,
  Map<String, CustomEmojiDefinition>? customEmojis,
  MessageFieldOptions? messageField,
  bool? showChatHeader,
  String? scrollToMessage,
  TranslationToggle? showTranslationToggle,
  String? theme,
  ThemeOptions? themeOptions,
  TranslateConversations? translateConversations,
  List<String> highlightedWords = const <String>[],
  MessagePredicate? messageFilter,
  Conversation? conversation,
  bool? asGuest,
  bool enableZoom = false,
  SendMessageHandler? onSendMessage,
  LeaveConversationHandler? onLeaveConversation,
  TranslationToggledHandler? onTranslationToggled,
  LoadingStateHandler? onLoadingStateChanged,
  MarkConversationAsUnreadHandler? onMarkConversationAsUnread,
  Map<String, MessageActionHandler>? onCustomMessageAction,
  Map<String, ConversationActionHandler>? onCustomConversationAction,
  NavigationHandler? onUrlNavigation,
  ErrorHandler? onError,
});

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.

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.

Allows users to send and receive custom emojis.

This adds a set of custom emoji images to the emoji picker, the emoji autocompleter, and emoji reactions.

Every emoji name must start and end with a colon, for example :lol:. Emoji names can be up to 50 characters long, including the colons.

Make sure you always specify a consistent, backward-compatible set of custom emojis. If an existing message contains a custom emoji that is not specified in customEmojis here, then the emoji cannot be displayed and the textual name will be displayed instead (including colons).

If you want to allow an emoji to be displayed if it's used in existing data, but not let users select it in new messages/reactions, set the hidden option to true for that emoji.

Example: Create three custom emojis

1{
2  // Static image
3  ":lol:": CustomEmojiDefinition(url: "https://example.com/images/emoji-lol.svg"),
4  // Animated
5  ":roomba-cat:": CustomEmojiDefinition(url: "https://example.com/images/roomba-cat.gif"),
6  // Hidden
7  ":alert:": CustomEmojiDefinition(url: "https://example.com/images/alert.gif", hidden: true),
8}

Settings that affect the behavior of the message field

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

The ID of the message you would like to scroll to and highlight

Set this to TranslationToggle.on to show a translation toggle in all conversations. Set this to TranslationToggle.auto to show a translation toggle in conversations where there are participants with different locales. This setting defaults to TranslationToggle.off, 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 on the Settings page of your dashboard.

Overrides the theme used for this chat UI. Overriding the theme only works with themes created in the Theme Editor.

If you omit both the theme and themeOptions properties, the UI uses the theme that is selected in the current user's role.

If both the theme and themeOptions properties are specified, the themeOptions property takes precedence.

Overrides the theme used for this chat UI. Overriding the theme only works with themes created in the Theme Editor.

You can use the themeOptions property instead of theme to pass variables to your theme.

If you omit both the theme and themeOptions properties, the UI uses the theme that is selected in the current user's role.

If both the theme and themeOptions properties are specified, the themeOptions property takes precedence.

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 TranslateConversations.off to enable/disable translation for all conversations, or TranslateConversations.auto 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 on the Settings page of your dashboard.

Highlights certain words in messages

The TalkJS search feature includes the ability to highlight certain words in messages. Use this property to highlight certain words without having the user invoke the search feature. Call again with an empty array to disable highlighting.

Note: like the search feature, this option only works on the Growth plan and up.

Used to control which messages are shown in the message list, depending on a type, origin or custom message attributes.

See MessagePredicate for all available options.

Example 1:

1// only show messages sent by users with role "admin"
2messageFilter: SimpleMessagePredicate(
3  sender: SenderPredicate(
4    role: FieldPredicate.equals('admin'),
5  ),
6),

Example 2:

1// only show messages sent by users with role "admin" OR messages of type SystemMessage
2messageFilter: CompoundMessagePredicate.any([
3  SimpleMessagePredicate(
4    sender: SenderPredicate(
5      role: FieldPredicate.equals('admin'),
6    ),
7  ),
8  SimpleMessagePredicate(
9    type: FieldPredicate.equals(MessageType.systemMessage),
10  ),
11]),

Selects the active conversation for the Chatbox.

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

Controls whether the user can pinch to zoom the UI.

Defaults to false.

Triggers when the user sends a message using the TalkJS UI

Triggers when the user clicks on the "Leave conversation" action.

This event only triggers when the user performs a Leave action from inside the chat UI. Notably, when a user leaves the conversation through other means (for example, they're removed from the conversation using the REST API), this event does not trigger.

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.

Triggers when the user clicks on the "Mark as unread" action.

This event only triggers when the user performs a "Mark as unread" action from inside the chat UI. Notably, when a user marks the conversation as unread through other means (for example, via the REST API), this event does not trigger.

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

To set up a custom action, you need to create it from the Chat UI page in your dashboard. 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.

Example

1onCustomMessageAction: {
2  'favourite': (event) {
3    print('Favourited message with id: ${event.message.id}');
4  },
5  'report': (event) {
6    print('Reported message with id: ${event.message.id}');
7  },
8},

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

To set up a custom action, you can either create it on the Chat UI page in your dashboard or add an action button to the ChatHeader, MessageField, ConversationListHeader or ConversationListItem components of your theme in the Theme Editor, which you can access from the "Themes" page in your dashboard. If an action is allowed on a particular conversation, it'll show up in that conversation's action menu. The name you specify when setting up the action, is also the name you should pass in here (case sensitive). The event you get contains information about the conversation on which the action was called, including its ID, so you can look it up later via our REST API.

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.

Example

1onUrlNavigation: (navigationRequest) {
2  print('Attempted to navigate to: ${navigationRequest.url}');
3
4  if (navigationRequest.url.contains("twitter")) {
5    return UrlNavigationAction.deny;
6  } else {
7    return UrlNavigationAction.allow;
8  }
9},

Triggered when the TalkSession encounters an unrecoverable error.

For example, if the session cannot authenticate, or if you specify an incorrect app ID.

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.