--- title: Flutter slug: sdk/web-view-sdk-api-reference-flutter createdAt: 2026-11-04T11:39:38.881Z --- The public API of the Flutter, generated from release 1.0.1 # Classes ## KindlyWebViewAuthCredentials `class` ```dart @immutable class KindlyWebViewAuthCredentials ``` Credentials for an authenticated chat, returned from a `KindlyWebViewAuthCredentialsCallback`. Set at least one of `idToken` and `accessToken`. The native SDK sends the `idToken` as the bearer token when there is one and the `accessToken` otherwise, so a provider that issues only an access token works. Next to an `idToken`, a different `accessToken` is the companion token your identity provider pairs with it. Put an opaque token checked by introspection in either field and set `issuer`. `toString` never prints a token, so an instance can be logged safely. | Member | Declaration | Description | | ------------------------------ | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `KindlyWebViewAuthCredentials` | `const KindlyWebViewAuthCredentials({ String? idToken, String? accessToken, String? issuer, int? expiresAt, })` | Creates credentials. When `idToken` and `accessToken` are both missing or empty, the SDK treats the answer as "no credentials", logs one warning and the chat stays anonymous. | | `accessToken` | `final String? accessToken` | The access token from your identity provider: the bearer token when there is no `idToken`, otherwise its companion token. | | `expiresAt` | `final int? expiresAt` | Optional expiry in Unix seconds. Worth setting for opaque tokens, whose expiry the SDK cannot read. | | `idToken` | `final String? idToken` | The OIDC id token, a JWT your backend signs, or an opaque token. The preferred bearer token when set. | | `issuer` | `final String? issuer` | Optional issuer of the token. Needed for opaque tokens and for bots with more than one identity provider. | | `toMap` | `Map toMap()` | The channel payload: `{idToken, accessToken, issuer, expiresAt}`. Optional values are sent as `null`, never omitted. | | `toString` | `@override String toString()` | A string representation of this object. Some classes have a default textual representation, often paired with a static `parse` function (like `int.parse`). These classes will provide the textual representation as their string representation. Other classes have no meaningful textual representation that a program will care about. Such classes will typically override `toString` to provide useful information when inspecting the object, mainly for debugging or logging. | ## KindlyWebViewEvent `class` ```dart @immutable class KindlyWebViewEvent ``` One event from the hosted chat widget. Parsing never fails: an unknown or malformed payload becomes a `KindlyWebViewEventType.unknown` event that keeps whatever raw values it had, so nothing is dropped. | Member | Declaration | Description | | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `KindlyWebViewEvent` | `const KindlyWebViewEvent({ required KindlyWebViewEventType type, required String rawType, required DateTime timestamp, required Map detail, required String detailJson, KindlyWebViewUiAction? uiAction, String? rawUiAction, })` | Creates an event. Normally built by `KindlyWebViewEvent.fromPlatform`. | | `KindlyWebViewEvent.fromPlatform` | `factory KindlyWebViewEvent.fromPlatform(Object? payload)` | Parses the event channel payload `{type, timestamp, detail}`, where `detail` is the projected widget detail as JSON text. | | `detail` | `final Map detail` | The projected widget detail. Empty when the text was not a JSON object. | | `detailJson` | `final String detailJson` | The projected widget detail as the JSON text the native SDK sent. | | `rawType` | `final String rawType` | The web event name as received, for example `kindly:ui`. | | `rawUiAction` | `final String? rawUiAction` | For `KindlyWebViewEventType.ui` events, the action as received. | | `timestamp` | `final DateTime timestamp` | When the native SDK emitted the event. | | `type` | `final KindlyWebViewEventType type` | The parsed type, or `KindlyWebViewEventType.unknown`. | | `uiAction` | `final KindlyWebViewUiAction? uiAction` | For `KindlyWebViewEventType.ui` events, the action; `null` otherwise. | | `uiSource` | `String? get uiSource` | For `KindlyWebViewEventType.ui` events, who caused it: `user` or `programmatic`. | | `toString` | `@override String toString()` | A string representation of this object. Some classes have a default textual representation, often paired with a static `parse` function (like `int.parse`). These classes will provide the textual representation as their string representation. Other classes have no meaningful textual representation that a program will care about. Such classes will typically override `toString` to provide useful information when inspecting the object, mainly for debugging or logging. | | `maxDetailJsonLength` | `static const int maxDetailJsonLength` | Detail text longer than this is not parsed (`detail` is then empty). The native bridge already caps a widget event at 512 KiB, so only a native bug can reach it. | ## KindlyWebViewException `class` ```dart class KindlyWebViewException implements Exception ``` The error every `KindlyWebViewSDK` call throws when the native side fails it. `code` is one of the protocol codes (see `KindlyWebViewErrorCode`). The `message` never contains a token, a chat id, a URL or message text. | Member | Declaration | Description | | ---------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `KindlyWebViewException` | `const KindlyWebViewException(String code, [String? message])` | Creates an exception with a raw protocol `code`. | | `KindlyWebViewException.fromPlatformException` | `factory KindlyWebViewException.fromPlatformException(PlatformException exception)` | Maps a `PlatformException` from the method channel. | | `code` | `final String code` | The raw protocol code, for example `NOT_STARTED`. | | `errorCode` | `KindlyWebViewErrorCode get errorCode` | `code` as an enum value. | | `message` | `final String? message` | A short description of the failure, if the native side gave one. | | `toString` | `@override String toString()` | A string representation of this object. Some classes have a default textual representation, often paired with a static `parse` function (like `int.parse`). These classes will provide the textual representation as their string representation. Other classes have no meaningful textual representation that a program will care about. Such classes will typically override `toString` to provide useful information when inspecting the object, mainly for debugging or logging. | ## KindlyWebViewSDK `class` ```dart abstract final class KindlyWebViewSDK ``` The Kindly web view chat: Kindly's web chat widget in a native screen. Call `start` once (it can be called again to change the language or the auth callbacks), then `displayChat`. Every call returns after the native SDK has finished it, and fails with a `KindlyWebViewException`. The native callbacks (auth and links) reach the Flutter engine whose isolate last called `start`. An engine that never calls `start`, such as a background isolate a messaging plugin creates, never receives them. After a hot restart, call `start` and `setDelegate` again to register the callbacks of the new isolate. | Member | Declaration | Description | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `events` | `static Stream get events` | Every widget event, as a broadcast stream with no replay: a listener sees the events emitted after it subscribed. Any number of listeners share one native subscription, and each event is decoded once for all of them. | | `state` | `static Stream get state` | The SDK state, as a broadcast stream. A new listener gets the current state first, then every change. Repeated identical states are dropped. | | `authenticate` | `static Future authenticate()` | Authenticates the chat again with the auth callback given to `start`, for example after the user signed in. | | `clearDelegate` | `static Future clearDelegate()` | Removes the link delegate set with `setDelegate`. | | `clearNewContext` | `static Future clearNewContext()` | Clears the context set with `setNewContext`. | | `closeChat` | `static Future closeChat()` | Dismisses the chat screen. The conversation stays live in the background. | | `currentState` | `static Future currentState()` | The current SDK state, without subscribing to `state`. | | `deauthenticate` | `static Future deauthenticate()` | Signs the user out of the chat without ending it; the chat goes on anonymously. | | `displayChat` | `static Future displayChat({ String? languageCode, String? triggerDialogueId, })` | Shows the chat full screen. The first display creates the chat page; later ones show the same live chat at once. `languageCode` renders the chat in that language when it differs from the live chat's. `triggerDialogueId` triggers that dialogue as the chat opens. Both are trimmed; one in a format the native SDK refuses throws an `ArgumentError`. Fails with `NOT_STARTED` before `start`. | | `endChat` | `static Future endChat()` | Ends the conversation; the next `displayChat` starts a new one. | | `isSupported` | `static Future isSupported()` | Whether this device's web view can run the chat. When it cannot, `displayChat` shows an update screen instead of the chat. | | `kill` | `static Future kill()` | Ends the conversation and stops the SDK. Call `start` again before anything else. Forgets the auth callbacks; the link delegate is kept. | | `launchChat` | `static Future launchChat({ String? languageCode, String? triggerDialogueId, })` | The same as `displayChat`. Kept for parity with the native Android API. | | `sendMessage` | `static Future sendMessage( String message, { Map? newContext, })` | Sends `message` on behalf of the user, with `newContext` attached to this message only. The chat must have been displayed (it may be hidden since); otherwise it fails with `CHAT_NOT_READY`. Throws an `ArgumentError` when `message` is blank, or when `newContext` uses `__proto__`, `constructor` or `prototype` as a key. | | `setCrashReporting` | `static Future setCrashReporting(bool enabled)` | Turns crash reporting to Kindly on or off. Applied at the next `start`. | | `setDelegate` | `static Future setDelegate({KindlyWebViewLinkCallback? shouldHandleLink})` | Sets the link delegate. `shouldHandleLink` is asked for every link the user taps in the chat; without it the SDK opens links outside the app. The delegate is kept across `start` and `kill`. | | `setNewContext` | `static Future setNewContext(Map context)` | Attaches `context` to the next message or button click. Throws an `ArgumentError` when a key is `__proto__`, `constructor` or `prototype`. | | `setVerboseLogging` | `static Future setVerboseLogging(bool enabled)` | Turns the native SDK's debug logging on or off. Logs never contain chat content, tokens or URLs. | | `start` | `static Future start({ required String botKey, required String market, String languageCode = 'en', KindlyWebViewAuthTokenCallback? authTokenCallback, KindlyWebViewAuthCredentialsCallback? authCredentialsCallback, })` | Initializes the SDK. The chat page is created on the first `displayChat`, but the usage metrics start here, and the error reports unless `setCrashReporting` turned them off, so an app that asks for the user's consent calls `start` after it. `market` is required and must be a market configured for the bot; there is no fallback. Calling `start` again with the same `botKey` and `market` only replaces `languageCode` and the callbacks; another bot or market closes the chat and starts over. When both callbacks are given, `authCredentialsCallback` wins. `botKey`, `market` and `languageCode` are trimmed. Throws an `ArgumentError` naming the argument, before anything changes, when one is blank or in a format the native SDK refuses: a bot key is 8 to 64 letters, digits and hyphens, a market 1 to 64 letters, digits, `_` and `-`, and a language code looks like `en`, `nb` or `pt-BR`. | | `triggerDialogue` | `static Future triggerDialogue(String dialogueId)` | Triggers the dialogue `dialogueId` in the live chat. It opens the chat only when the chat is displayed. `dialogueId` is trimmed; throws an `ArgumentError` when it is blank or not 1 to 128 letters, digits, `_` and `-`. | | `authCallbackTimeout` | `static const Duration authCallbackTimeout` | How long an auth callback may take. The native SDK stops waiting at 15 seconds, so the answer is always sent before it gives up. | | `linkCallbackTimeout` | `static const Duration linkCallbackTimeout` | How long a link callback may take. The native SDK opens the link itself when it has no answer after 5 seconds. | ## KindlyWebViewState `class` ```dart @immutable class KindlyWebViewState ``` The SDK state: `{isStarted, isChatDisplayed, isSocketConnected, isConnected, connectionState}`. In the web view SDK `isSocketConnected` and `isConnected` both mean "the chat page is loaded", including while the chat is hidden. Keys this version of the package does not know are kept in `raw`. | Member | Declaration | Description | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `KindlyWebViewState` | `const KindlyWebViewState({ required bool isStarted, required bool isChatDisplayed, required bool isSocketConnected, required bool isConnected, required KindlyWebViewConnectionState connectionState, required String rawConnectionState, Map raw = const {}, })` | Creates a state. Normally built by `KindlyWebViewState.fromPlatform`. | | `KindlyWebViewState.fromPlatform` | `factory KindlyWebViewState.fromPlatform(Object? payload)` | Parses the state channel payload. Missing or malformed fields read as `false` and `KindlyWebViewConnectionState.unknown`; nothing throws. | | `connectionState` | `final KindlyWebViewConnectionState connectionState` | The parsed connection state. | | `hashCode` | `@override int get hashCode` | The hash code for this object. A hash code is a single integer which represents the state of the object that affects `operator ==` comparisons. All objects have hash codes. The default hash code implemented by `Object` represents only the identity of the object, the same way as the default `operator ==` implementation only considers objects equal if they are identical (see `identityHashCode`). If `operator ==` is overridden to use the object state instead, the hash code must also be changed to represent that state, otherwise the object cannot be used in hash based data structures like the default `Set` and `Map` implementations. Hash codes must be the same for objects that are equal to each other according to `operator ==`. The hash code of an object should only change if the object changes in a way that affects equality. There are no further requirements for the hash codes. They need not be consistent between executions of the same program and there are no distribution guarantees. Objects that are not equal are allowed to have the same hash code. It is even technically allowed that all instances have the same hash code, but if clashes happen too often, it may reduce the efficiency of hash-based data structures like `HashSet` or `HashMap`. If a subclass overrides `hashCode`, it should override the `operator ==` operator as well to maintain consistency. | | `isChatDisplayed` | `final bool isChatDisplayed` | Whether the chat screen is visible. | | `isConnected` | `final bool isConnected` | The same as `isSocketConnected`. | | `isSocketConnected` | `final bool isSocketConnected` | Whether the chat page is loaded (also while the chat is hidden). | | `isStarted` | `final bool isStarted` | Whether `start` was called and `kill` has not run since. | | `raw` | `final Map raw` | Every key the native side sent, including ones this version does not know. | | `rawConnectionState` | `final String rawConnectionState` | The connection state as received. | | `toString` | `@override String toString()` | A string representation of this object. Some classes have a default textual representation, often paired with a static `parse` function (like `int.parse`). These classes will provide the textual representation as their string representation. Other classes have no meaningful textual representation that a program will care about. Such classes will typically override `toString` to provide useful information when inspecting the object, mainly for debugging or logging. | | `operator ==` | `@override bool operator ==(Object other)` | The equality operator. The default behavior for all `Object`s is to return true if and only if this object and `other` are the same object. Override this method to specify a different equality relation on a class. The overriding method must still be an equivalence relation. That is, it must be: - Total: It must return a boolean for all arguments. It should never throw. - Reflexive: For all objects `o`, `o == o` must be true. - Symmetric: For all objects `o1` and `o2`, `o1 == o2` and `o2 == o1` must either both be true, or both be false. - Transitive: For all objects `o1`, `o2`, and `o3`, if `o1 == o2` and `o2 == o3` are true, then `o1 == o3` must be true. The method should also be consistent over time, so whether two objects are equal should only change if at least one of the objects was modified. If a subclass overrides the equality operator, it should override the `hashCode` method as well to maintain consistency. | | `initial` | `static const KindlyWebViewState initial` | The state before `start`. | # Enums ## KindlyWebViewConnectionState `enum` ```dart enum KindlyWebViewConnectionState ``` Where the chat page is, from the state's `connectionState` field. | Member | Declaration | Description | | -------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | `none` | `none` | No chat page exists yet (before the first display, or after `kill`). | | `loading` | `loading` | The chat page is loading. | | `connected` | `connected` | The chat page is loaded. It stays loaded while the chat is hidden. | | `failed` | `failed` | The chat page failed to load. | | `unsupported` | `unsupported` | This device's web view cannot run the chat. | | `disconnected` | `disconnected` | The chat page was torn down. | | `unknown` | `unknown` | A value this version of the package does not know. The raw value is in `KindlyWebViewState.rawConnectionState`. | | `fromRaw` | `static KindlyWebViewConnectionState fromRaw(String raw)` | The enum value for `raw`, or `unknown`. | | `values` | `static const List values` | A constant List of the values in this enum, in order of their declaration. | ## KindlyWebViewErrorCode `enum` ```dart enum KindlyWebViewErrorCode ``` The error codes the native plugin code reports, from `shared/wrapper-protocol.json`. | Member | Declaration | Description | | ----------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | `invalidArgument` | `invalidArgument('INVALID_ARGUMENT')` | An argument was refused. The message names the argument, never its value. | | `notStarted` | `notStarted('NOT_STARTED')` | `start` has not been called, or `kill` ran since. | | `noActivity` | `noActivity('NO_ACTIVITY')` | Android only: there was no context to show the chat from. | | `chatNotReady` | `chatNotReady('CHAT_NOT_READY')` | The call needs a loaded chat page. Display the chat first. | | `unsupported` | `unsupported('UNSUPPORTED')` | The device, or this platform, cannot run the chat. | | `nativeError` | `nativeError('NATIVE_ERROR')` | The native SDK failed the call. | | `unknown` | `unknown('')` | A code this version of the package does not know. The raw value is in `KindlyWebViewException.code`. | | `rawValue` | `final String rawValue` | The code as it travels over the channel, for example `NOT_STARTED`. | | `fromRaw` | `static KindlyWebViewErrorCode fromRaw(String raw)` | The enum value for `raw`, or `unknown`. | | `values` | `static const List values` | A constant List of the values in this enum, in order of their declaration. | ## KindlyWebViewEventType `enum` ```dart enum KindlyWebViewEventType ``` The widget event types (the web `kindly:*` event names). | Member | Declaration | Description | | ------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | `load` | `load('kindly:load')` | `kindly:load`: the widget loaded its settings. | | `message` | `message('kindly:message')` | `kindly:message`: a message was added to the chat. | | `buttonClick` | `buttonClick('kindly:buttonclick')` | `kindly:buttonclick`: the user tapped a button. | | `ui` | `ui('kindly:ui')` | `kindly:ui`: a UI action, see `KindlyWebViewUiAction`. | | `globalIcon` | `globalIcon('kindly:globalicon')` | `kindly:globalicon`: the user tapped a global icon. | | `state` | `state('kindly:state')` | `kindly:state`: the SDK state changed. | | `unknown` | `unknown('')` | A type this version of the package does not know. The raw name is in `KindlyWebViewEvent.rawType`. | | `rawValue` | `final String rawValue` | The web event name, for example `kindly:ui`. | | `fromRaw` | `static KindlyWebViewEventType fromRaw(String raw)` | The enum value for `raw`, or `unknown`. | | `values` | `static const List values` | A constant List of the values in this enum, in order of their declaration. | ## KindlyWebViewUiAction `enum` ```dart enum KindlyWebViewUiAction ``` The actions a `kindly:ui` event reports, from the detail's `type` field. | Member | Declaration | Description | | ---------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | `openChatBubble` | `openChatBubble('open-chatbubble')` | The chat opened. | | `closeChatBubble` | `closeChatBubble('close-chatbubble')` | The chat was minimised or closed. | | `endChat` | `endChat('end-chat')` | The conversation ended. | | `restartChat` | `restartChat('restart-chat')` | The conversation restarted. | | `downloadChat` | `downloadChat('download-chat')` | The user downloaded the conversation. | | `deleteChat` | `deleteChat('delete-chat')` | The user deleted the conversation. | | `changeLanguage` | `changeLanguage('change-language')` | The user changed the chat language. | | `showFeedback` | `showFeedback('show-feedback')` | The widget showed a feedback form. | | `submitFeedback` | `submitFeedback('submit-feedback')` | The user submitted feedback. | | `dismissFeedback` | `dismissFeedback('dismiss-feedback')` | The user dismissed the feedback form. | | `welcomePageStartChat` | `welcomePageStartChat('welcome-page-start-chat')` | The user started the chat from the widget's welcome page. | | `unknown` | `unknown('')` | An action this version of the package does not know. The raw value is in `KindlyWebViewEvent.rawUiAction`. | | `rawValue` | `final String rawValue` | The action as the widget names it, for example `open-chatbubble`. | | `fromRaw` | `static KindlyWebViewUiAction fromRaw(String raw)` | The enum value for `raw`, or `unknown`. | | `values` | `static const List values` | A constant List of the values in this enum, in order of their declaration. | # Typedefs ## KindlyWebViewAuthCredentialsCallback `typedef` ```dart typedef KindlyWebViewAuthCredentialsCallback = Future Function(String chatId) ``` Returns full credentials for the chat `chatId`, or `null` to keep the chat anonymous. Same timing and failure rules as `KindlyWebViewAuthTokenCallback`. ## KindlyWebViewAuthTokenCallback `typedef` ```dart typedef KindlyWebViewAuthTokenCallback = Future Function(String chatId) ``` Returns a token for the chat `chatId`, or `null` to keep the chat anonymous. The SDK calls it after the chat connects, when `KindlyWebViewSDK.authenticate` runs, and before the previous token expires. Throwing, or taking longer than `KindlyWebViewSDK.authCallbackTimeout`, counts as `null`. ## KindlyWebViewLinkCallback `typedef` ```dart typedef KindlyWebViewLinkCallback = FutureOr Function(String url) ``` Decides a link the user tapped in the chat. Return `true` to let the SDK open it outside the app, or `false` to handle it yourself. Throwing, or taking longer than `KindlyWebViewSDK.linkCallbackTimeout`, counts as `true`.