Flutter

The public API of the Flutter, generated from release 1.0.1

Classes

KindlyWebViewAuthCredentials

class

@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<String, Object?> 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

@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<String, Object?> 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<String, Object?> 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

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

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<KindlyWebViewEvent> 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<KindlyWebViewState> 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<void> authenticate()	Authenticates the chat again with the auth callback given to start, for example after the user signed in.
clearDelegate	static Future<void> clearDelegate()	Removes the link delegate set with setDelegate.
clearNewContext	static Future<void> clearNewContext()	Clears the context set with setNewContext.
closeChat	static Future<void> closeChat()	Dismisses the chat screen. The conversation stays live in the background.
currentState	static Future<KindlyWebViewState> currentState()	The current SDK state, without subscribing to state.
deauthenticate	static Future<void> deauthenticate()	Signs the user out of the chat without ending it; the chat goes on anonymously.
displayChat	static Future<void> 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<void> endChat()	Ends the conversation; the next displayChat starts a new one.
isSupported	static Future<bool> 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<void> 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<void> launchChat({ String? languageCode, String? triggerDialogueId, })	The same as displayChat. Kept for parity with the native Android API.
sendMessage	static Future<void> sendMessage( String message, { Map<String, String>? 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<void> setCrashReporting(bool enabled)	Turns crash reporting to Kindly on or off. Applied at the next start.
setDelegate	static Future<void> 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<void> setNewContext(Map<String, String> context)	Attaches context to the next message or button click. Throws an ArgumentError when a key is __proto__, constructor or prototype.
setVerboseLogging	static Future<void> setVerboseLogging(bool enabled)	Turns the native SDK's debug logging on or off. Logs never contain chat content, tokens or URLs.
start	static Future<void> 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<void> 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

@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<String, Object?> raw = const <String, Object?>{}, })	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<String, Object?> 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 Objects 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

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<KindlyWebViewConnectionState> values	A constant List of the values in this enum, in order of their declaration.

KindlyWebViewErrorCode

enum

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<KindlyWebViewErrorCode> values	A constant List of the values in this enum, in order of their declaration.

KindlyWebViewEventType

enum

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<KindlyWebViewEventType> values	A constant List of the values in this enum, in order of their declaration.

KindlyWebViewUiAction

enum

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<KindlyWebViewUiAction> values	A constant List of the values in this enum, in order of their declaration.

Typedefs

KindlyWebViewAuthCredentialsCallback

typedef

typedef KindlyWebViewAuthCredentialsCallback = Future<KindlyWebViewAuthCredentials?> 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

typedef KindlyWebViewAuthTokenCallback = Future<String?> 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

typedef KindlyWebViewLinkCallback = FutureOr<bool> 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.