BotConfiguration class abstract

Configuration for the chatbot widget behavior and appearance.

Contains all settings needed to customize the chatbot's functionality, styling, and initial state.

Example:

final config = BotConfiguration(
  userID: 'user123',
  projectSecretKey: 'your-secret-key',
  name: 'Support Bot',
  welcomeMessage: 'Hello! How can I help you?',
);

Available extensions

• BotConfigurationLocalization
• BotConfigurationPatterns

Annotations

• @freezed

Constructors

BotConfiguration({required String userID, required String projectSecretKey, String? userIdSignature, LocalizedText? welcomeMessage, LocalizedText? name, LocalizedText? systemInstructions, @Default.new('en') String defaultLocale, @Default.new(['en']) List<String> supportedLocales, String? currentLocale, String? allowedOrigins, @Default.new('Roboto') String? fontFamily, String? color, @unfreezed Uint8List? avatar, @Default.new(false) bool isPreviewMode, @Default.new(false) bool isReadOnly, @Default.new(true) bool showAvatar, @Default.new(false) bool hideBarsOnScroll, @Default.new(true) bool enableUserExport, @Default.new(true) bool enableClearHistory, @Default.new(true) bool enableFileAttach, @Default.new(false) bool dynamicLanguageEnabled, @Default.new(true) bool aiDisclosureEnabled, LocalizedText? aiDisclosureText, @Default.new(false) bool aiDisclosureRequireAck, @Default.new(true) bool messageReportingEnabled, String? aiInfoUrl, String? privacyUrl, @Default.new(false) bool aiDataReuseNotice, @Default.new(FabConfiguration()) FabConfiguration fabConfiguration, @Default.new(SoundConfiguration()) SoundConfiguration soundConfiguration, ChatAppearance? chatAppearance, ChatAppearance? chatAppearanceDark, @Default.new(true) bool showThemeToggle, @Default.new('system') String defaultThemeMode, Map<String, dynamic>? userContext, String? authToken})

const

factory

Properties

aiDataReuseNotice → bool

When true, the chip shows an extra line that chats may be used to improve the service (display-only). Surfaced via the server config (ai_data_reuse_notice).

no setter, inherited

aiDisclosureEnabled → bool

When true (default), the chat renders a light "You're chatting with an AI" disclosure inside the chat surface. Surfaced via the server config (ai_disclosure_enabled).

no setter, inherited

aiDisclosureRequireAck → bool

When true, the disclosure shows a one-time "OK" the user must acknowledge (persisted locally). Surfaced via the server config (ai_disclosure_require_ack).

no setter, inherited

aiDisclosureText → LocalizedText?

Per-locale disclosure text. Null = use the SDK's localized default (ai_disclosure ARB key). Surfaced via the server config (ai_disclosure_text).

no setter, inherited

aiInfoUrl → String?

"Learn more" target for the disclosure chip — an About-AI page. Falls back to privacyUrl when empty. Surfaced via the server config (ai_info_url).

no setter, inherited

allowedOrigins → String?

Comma-separated list of allowed origins for CORS.

no setter, inherited

authToken → String?

End-user JWT (or equivalent bearer token) forwarded to the bot backend on every chat request so authenticated downstream tools can attribute calls to the right account.

no setter, inherited

avatar → Uint8List?

Avatar image data. Note: This is excluded from JSON serialization.

no setter, inherited

chatAppearance → ChatAppearance?

Tenant-configurable chat-surface colours. When the server returns a chat_appearance block in /api/project/config/, the repository inflates it into this field; hosts can also pass one explicitly to override at the per-session level.

no setter, inherited

chatAppearanceDark → ChatAppearance?

Dark-mode counterpart to chatAppearance. Selected when the active theme brightness is dark. Same precedence rules as chatAppearance.

no setter, inherited

color → String?

Primary color for the chat interface in hex format. When null, the SDK inherits the host app's theme colour (ColorScheme.primary) — see _getPrimaryColor in chat_screen. Left intentionally without a default so "unset" means "inherit from app" rather than a forced hex.

no setter, inherited

copyWith → $BotConfigurationCopyWith<BotConfiguration>

Create a copy of BotConfiguration with the given fields replaced by the non-null parameter values.

no setter, inherited

currentLocale → String?

no setter, inherited

defaultLocale → String

Default locale code for the chat interface (e.g., 'en', 'fr', 'es').

no setter, inherited

defaultThemeMode → String

Initial theme mode before the user overrides it — 'light', 'dark', or 'system' (follows the host device brightness).

no setter, inherited

dynamicLanguageEnabled → bool

When true, the bot may switch the chat language live (via the backend change_language tool) and the SDK exposes a manual language picker in the header. Surfaced via the server config (dynamic_language_enabled). Picker also requires 2+ supportedLocales.

no setter, inherited

enableClearHistory → bool

Whether to surface a "Clear chat history" item in the chat header's more-options menu. When true (default) the user can wipe their own conversation; when false, the item is hidden.

no setter, inherited

enableFileAttach → bool

Whether to render the paperclip attach button in the chat input. When true (default) the user can pick an image to send with their message; when false, the button is hidden.

no setter, inherited

enableUserExport → bool

Whether to surface an "Export chat" item in the chat header's more-options menu. When true (default) the user can download their own transcript as a .zip and hand it to the platform share sheet. When false, the menu item is hidden — useful for hosts whose privacy posture or app-store category requires suppressing data-export affordances.

no setter, inherited

fabConfiguration → FabConfiguration

Configuration for the floating action button appearance.

no setter, inherited

fontFamily → String?

Font family for chat text. Defaults to 'Roboto'.

no setter, inherited

hashCode → int

The hash code for this object.

no setter, inherited

hideBarsOnScroll → bool

When true, the chat header and the message-input bar auto-hide as the user scrolls up through older messages, and slide back in when they scroll back toward the newest message — maximising reading space on a full-page chat. Defaults false (both bars stay pinned).

no setter, inherited

isPreviewMode → bool

Whether the bot is running in preview mode.

no setter, inherited

isReadOnly → bool

Whether the chat is in read-only mode (no user input allowed). When true, the chat input field will be disabled.

no setter, inherited

localizedAiDisclosure → String?

Available on BotConfiguration, provided by the BotConfigurationLocalization extension

Localized AI-disclosure text, or null when the project hasn't set one — in which case the widget falls back to the ai_disclosure ARB string.

no setter

localizedName → String

Available on BotConfiguration, provided by the BotConfigurationLocalization extension

Returns the localized bot name based on the current locale.

no setter

localizedSystemInstructions → String

Available on BotConfiguration, provided by the BotConfigurationLocalization extension

Returns the localized system instructions based on the current locale.

no setter

localizedWelcomeMessage → String

Available on BotConfiguration, provided by the BotConfigurationLocalization extension

Returns the localized welcome message based on the current locale.

no setter

messageReportingEnabled → bool

When true, bot messages expose a long-press "Good/Bad response" menu; "Bad response" opens a reason sheet that reports the message (App Store UGC / Guideline 1.2). On by default. Surfaced via the server config (message_reporting_enabled).

no setter, inherited

name → LocalizedText?

Display name for the chatbot (localized).

no setter, inherited

privacyUrl → String?

Privacy page link; fallback "Learn more" target. Surfaced via the server config (privacy_url).

no setter, inherited

projectSecretKey → String

Public project identifier shipped to the widget. Used by the chat backend to look up the project; safe to inline in HTML or app bundles (it's the equivalent of a Stripe publishable key). By itself it cannot read another user's history — that requires a matching userIdSignature.

no setter, inherited

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

showAvatar → bool

Whether to show the bot avatar next to bot MESSAGES (and the typing indicator). The header avatar is unconditionally shown — this flag only gates the per-bubble avatar circle.

no setter, inherited

showThemeToggle → bool

Whether the light/dark theme switcher appears in the header's more-options menu. Server-gated via show_theme_toggle.

no setter, inherited

soundConfiguration → SoundConfiguration

Configuration for sound effects.

no setter, inherited

supportedLocales → List<String>

List of supported locale codes

no setter, inherited

systemInstructions → LocalizedText?

System instructions that guide the bot's behavior (localized).

no setter, inherited

userContext → Map<String, dynamic>?

Free-form host-app context forwarded to the bot on every /api/chat/ request and surfaced into the system prompt.

no setter, inherited

userID → String

Unique identifier for the user interacting with the bot.

no setter, inherited

userIdSignature → String?

HMAC-SHA256 hex digest of userID keyed by the project's identity_secret, computed on the host app's backend and forwarded here.

no setter, inherited

welcomeMessage → LocalizedText?

Initial message displayed when the chat opens (localized).

no setter, inherited

Methods

map<TResult extends Object?>(TResult $default(_BotConfiguration value)) → TResult

Available on BotConfiguration, provided by the BotConfigurationPatterns extension

A switch-like method, using callbacks.

mapOrNull<TResult extends Object?>(TResult? $default(_BotConfiguration value)?) → TResult?

Available on BotConfiguration, provided by the BotConfigurationPatterns extension

A variant of map that fallback to returning null.

maybeMap<TResult extends Object?>(TResult $default(_BotConfiguration value)?, {required TResult orElse()}) → TResult

Available on BotConfiguration, provided by the BotConfigurationPatterns extension

A variant of map that fallback to returning orElse.

maybeWhen<TResult extends Object?>(TResult $default(String userID, String projectSecretKey, String? userIdSignature, LocalizedText? welcomeMessage, LocalizedText? name, LocalizedText? systemInstructions, String defaultLocale, List<String> supportedLocales, String? currentLocale, String? allowedOrigins, String? fontFamily, String? color, Uint8List? avatar, bool isPreviewMode, bool isReadOnly, bool showAvatar, bool hideBarsOnScroll, bool enableUserExport, bool enableClearHistory, bool enableFileAttach, bool dynamicLanguageEnabled, bool aiDisclosureEnabled, LocalizedText? aiDisclosureText, bool aiDisclosureRequireAck, bool messageReportingEnabled, String? aiInfoUrl, String? privacyUrl, bool aiDataReuseNotice, FabConfiguration fabConfiguration, SoundConfiguration soundConfiguration, ChatAppearance? chatAppearance, ChatAppearance? chatAppearanceDark, bool showThemeToggle, String defaultThemeMode, Map<String, dynamic>? userContext, String? authToken)?, {required TResult orElse()}) → TResult

Available on BotConfiguration, provided by the BotConfigurationPatterns extension

A variant of when that fallback to an orElse callback.

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

toString() → String

A string representation of this object.

inherited

when<TResult extends Object?>(TResult $default(String userID, String projectSecretKey, String? userIdSignature, LocalizedText? welcomeMessage, LocalizedText? name, LocalizedText? systemInstructions, String defaultLocale, List<String> supportedLocales, String? currentLocale, String? allowedOrigins, String? fontFamily, String? color, Uint8List? avatar, bool isPreviewMode, bool isReadOnly, bool showAvatar, bool hideBarsOnScroll, bool enableUserExport, bool enableClearHistory, bool enableFileAttach, bool dynamicLanguageEnabled, bool aiDisclosureEnabled, LocalizedText? aiDisclosureText, bool aiDisclosureRequireAck, bool messageReportingEnabled, String? aiInfoUrl, String? privacyUrl, bool aiDataReuseNotice, FabConfiguration fabConfiguration, SoundConfiguration soundConfiguration, ChatAppearance? chatAppearance, ChatAppearance? chatAppearanceDark, bool showThemeToggle, String defaultThemeMode, Map<String, dynamic>? userContext, String? authToken)) → TResult

Available on BotConfiguration, provided by the BotConfigurationPatterns extension

A switch-like method, using callbacks.

whenOrNull<TResult extends Object?>(TResult? $default(String userID, String projectSecretKey, String? userIdSignature, LocalizedText? welcomeMessage, LocalizedText? name, LocalizedText? systemInstructions, String defaultLocale, List<String> supportedLocales, String? currentLocale, String? allowedOrigins, String? fontFamily, String? color, Uint8List? avatar, bool isPreviewMode, bool isReadOnly, bool showAvatar, bool hideBarsOnScroll, bool enableUserExport, bool enableClearHistory, bool enableFileAttach, bool dynamicLanguageEnabled, bool aiDisclosureEnabled, LocalizedText? aiDisclosureText, bool aiDisclosureRequireAck, bool messageReportingEnabled, String? aiInfoUrl, String? privacyUrl, bool aiDataReuseNotice, FabConfiguration fabConfiguration, SoundConfiguration soundConfiguration, ChatAppearance? chatAppearance, ChatAppearance? chatAppearanceDark, bool showThemeToggle, String defaultThemeMode, Map<String, dynamic>? userContext, String? authToken)?) → TResult?

Available on BotConfiguration, provided by the BotConfigurationPatterns extension

A variant of when that fallback to returning null

Operators

operator ==(Object other) → bool

The equality operator.

inherited