Chatbox

key

(optional): Key?

A Key is an identifier for Flutter Widgets.

session

: Session

The TalkJS Session object to use for this Chatbox.

dir

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

messageField

(optional): MessageFieldOptions?

Settings that affect the behavior of the message field

showChatHeader

(optional): bool?

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

showTranslationToggle

(optional): TranslationToggle.off | TranslationToggle.on | TranslationToggle.auto | null

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.

theme

(optional): String?

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.

themeOptions

(optional): ThemeOptions?

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.

translateConversations

(optional): TranslateConversations.off | TranslateConversations.on | TranslateConversations.auto | 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 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.

highlightedWords

(optional): List<String>

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.

messageFilter

(optional): BaseMessagePredicate?

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 and CompoundMessagePredicate for all available options.

Example

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

Example

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

conversation

(optional): Conversation?

Selects the active conversation for the Chatbox.

asGuest

(optional): bool?

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

onSendMessage

(optional): SendMessageHandler?

Triggers when the user sends a message using the TalkJS UI

onTranslationToggled

(optional): TranslationToggledHandler?

Triggers when the user toggles translation in a conversation

onLoadingStateChanged

(optional): LoadingStateHandler?

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.

onCustomMessageAction

(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 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},

onCustomConversationAction

(optional): Map<String, ConversationActionHandler>?

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.

onUrlNavigation

(optional): NavigationHandler?

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},

autofocus

(optional): bool?

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

enterSendsMessage

(optional): bool?

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.

placeholder

(optional): String?

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

spellcheck

(optional): bool?

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.