chat and common

no.kindly.chatsdk.chat

AuthTokenCallback

typealias, deprecated: Use KindlyAuthTokenProvider with KindlySDK.start(authTokenProvider = ...) instead. The provider is a suspend function, so no CoroutineScope or Deferred management is needed.

typealias AuthTokenCallback = (chatId: String) -> Deferred<String>

Callback for providing an authentication token to the SDK. The SDK calls this with the current chatId; return a Deferred that resolves to a valid JWT token string.

AuthTokenRequest

class

class AuthTokenRequest(val chatId: String, val reason: AuthTokenRequest.Reason)

Member	Declaration	Description
AuthTokenRequest	constructor(chatId: String, reason: AuthTokenRequest.Reason)
chatId	val chatId: String
reason	val reason: AuthTokenRequest.Reason

AuthTokenRequest.Reason

enum

enum Reason : Enum<AuthTokenRequest.Reason>

Member	Declaration	Description
INITIAL_CONNECT	INITIAL_CONNECT
EXPIRED	EXPIRED
entries	val entries: EnumEntries<AuthTokenRequest.Reason>	Returns a representation of an immutable list of all enum entries, in the order they're declared. This method may be used to iterate over the enum entries.
valueOf	fun valueOf(value: String): AuthTokenRequest.Reason	Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.) Throws - kotlin.IllegalArgumentException: if this enum type has no constant with the specified name
values	fun values(): Array<AuthTokenRequest.Reason>	Returns an array containing the constants of this enum type, in the order they're declared. This method may be used to iterate over the constants.

BehaviorType

enum

enum BehaviorType : Enum<BehaviorType>

Behavior type enum for the Kindly Chat SDK. Determines how the chat interface is displayed to users.

NOTE: WebView behavior temporarily disabled due to Google Play Store policy concerns. See .techrules for restoration instructions.

Member	Declaration	Description
NATIVE	NATIVE	Native Android UI behavior. Uses native Android components and navigation.
entries	val entries: EnumEntries<BehaviorType>	Returns a representation of an immutable list of all enum entries, in the order they're declared. This method may be used to iterate over the enum entries.
valueOf	fun valueOf(value: String): BehaviorType	Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.) Throws - kotlin.IllegalArgumentException: if this enum type has no constant with the specified name
values	fun values(): Array<BehaviorType>	Returns an array containing the constants of this enum type, in the order they're declared. This method may be used to iterate over the constants.

ChatKindlySDK

class

open class ChatKindlySDK(application: Application, botKey: String, languageCode: String = "en", behaviorType: BehaviorType = BehaviorType.NATIVE, authTokenCallback: AuthTokenCallback? = null, authTokenProvider: KindlyAuthTokenProvider? = null, authCredentialsProvider: KindlyAuthCredentialsProvider? = null, market: String) : EntryPoint

Main implementation of the Kindly Chat SDK. Use the companion object methods (e.g., KindlySDK.start(), KindlySDK.launchChat()) to interact with the SDK.

Parameters

application: The application context.

botKey: The bot key for the Kindly Chat API.

languageCode: The language code to use (default is "en").

behaviorType: The behavior type for the SDK. Currently only BehaviorType.NATIVE is supported.

Member	Declaration	Description
ChatKindlySDK	constructor(application: Application, botKey: String, languageCode: String = "en", behaviorType: BehaviorType = BehaviorType.NATIVE, authTokenCallback: AuthTokenCallback? = null, authTokenProvider: KindlyAuthTokenProvider? = null, authCredentialsProvider: KindlyAuthCredentialsProvider? = null, market: String)	Parameters - application: The application context. - botKey: The bot key for the Kindly Chat API. - languageCode: The language code to use (default is "en"). - behaviorType: The behavior type for the SDK. Currently only BehaviorType.NATIVE is supported.
config	open lateinit override var config: KindlySDKConfig	The SDK configuration for permissions and theme settings.
enableCrashReporting	open override var enableCrashReporting: Boolean	Whether the SDK should send crash reports via Sentry. Defaults to true.
events	open override val events: Flow<KindlyEvent>	Unified event flow for all Kindly events (matches web API pattern) Subscribe to this to receive all events: load, message, buttonClick, ui, globalIcon, state
handoverCallback	var handoverCallback: () -> Unit
inputFieldHidden	val inputFieldHidden: Flow<Boolean>	Flow that emits input field visibility changes Subscribe to this to get real-time updates when input field should be hidden or shown
interface	open override var interface: KindlySDKInteraction?	Optional delegate for receiving button press and link interception callbacks.
onKindlyInterfaceSet	var onKindlyInterfaceSet: (kindlyInterface: KindlySDKInteraction?) -> Unit?
openChatOnNotificationTap	open override var openChatOnNotificationTap: Boolean	Whether tapping a Kindly notification opens the chat. Defaults to true. A tap that reaches the SDK before start (the notification launched the app, or the process had been killed) is remembered and the chat opens at the end of start; a tap older than a minute is dropped. With false the tap opens your launcher activity with KindlyNotificationIntent extras and nothing else.
state	open override val state: Flow<KindlyEventState>	Unified state flow that emits state change events Subscribe to this to get real-time updates of: isChatDisplayed, isConnected, isStarted, isSocketConnected
verboseLogging	open override var verboseLogging: Boolean	Whether verbose logging is enabled. Defaults to false.
authenticate	open override fun authenticate(): Deferred<Unit>	Re-authenticates the live chat, asking the configured provider for fresh credentials. For the case the SDK cannot detect on its own: the user signed in, or switched account, while the chat was already open. The SDK refreshes on expiry by itself, so this is only needed when the identity changed rather than the token. The chat, its history and its socket are all kept — this re-binds the identity in place and does not restart anything. Returns - A Deferred that completes once the backend has accepted the new credentials, and completes exceptionally if the provider failed or the backend refused them.
callHandover	open override fun callHandover(handoverListener: CallbackHandover)	Handovers the call from the chatBot. Parameters - handoverListener: - CallbackHandover object to handle the handover.
clearCustomTheme	open override fun clearCustomTheme()	Clears any custom theme that has been set and reverts to the default theme.
clearNewContext	open override fun clearNewContext()	Clears the current context of the chat.
clearTriggerDialog	open override fun clearTriggerDialog()	Clears any pending trigger dialogue request.
close	open override fun close()	Closes the chat. Always dispatches the UI work to the main thread — the public KindlySDK.close() is callable from any thread, and the internal endChat() invokes this from the chatManager.disconnect(...) callback which currently runs on the Promise's Dispatchers.Default (background) queue. Activity.finish() must be called on the UI thread; calling from background risks CalledFromWrongThreadException or silent misbehavior depending on what's currently happening on the main looper.
deauthenticate	open override fun deauthenticate(): Deferred<Unit>	Signs the user out of the chat without ending it. Unbinds the identity on the backend and forgets the stored credentials. The chat carries on anonymously with its history intact — use endChat instead when the conversation itself should end. Safe to call when the chat is already anonymous; it completes immediately. The local credentials are cleared even when the backend call fails, so a sign-out is never left half done, but the result still completes exceptionally so the host knows the backend did not hear about it. Returns - A Deferred that completes once the identity has been unbound.
displayChat	open override fun displayChat(context: Context)	Displays the chat UI. This should only be called after the connection is established. Parameters - context: - android context class Context.
endChat	open override fun endChat(): Deferred<Unit>	Ends the chat session and disconnects from the server. This acts as a disconnect - the SDK remains initialized and can be reconnected by calling launchChat() again without needing to call start(). Use kill() if you want to completely terminate the SDK.
handleNotification	open override fun handleNotification(remoteMessage: RemoteMessage)	Handles an incoming Firebase push notification. Call this from your FirebaseMessagingService.
handleUrl	open override fun handleUrl(context: Context, uri: Uri): Boolean	Handles a Kindly URL scheme deep link. Supported format: kindly://chat/dialogue/ Parameters - context: Android context for launching the chat UI if needed - uri: The URI to handle Returns - true if the URL was handled, false otherwise
isInputFieldHidden	fun isInputFieldHidden(): Boolean	Gets the current input field visibility state. Returns - true if input field is currently hidden, false if visible
isKindlyNotification	open override fun isKindlyNotification(remoteMessage: RemoteMessage): Boolean	Checks if a notification is from Kindly. This function is used to determine if an incoming notification should be handled by the Kindly SDK. Parameters - remoteMessage: The message received from Firebase. Returns - Boolean indicating whether the notification is from Kindly.
kill	open override fun kill(): Deferred<Unit>	Completely kills the SDK and clears all state. After calling this method, start() must be called again before using any other SDK functions. This is more destructive than endChat() which only disconnects the chat session.
launchChat	open override fun launchChat(context: Context, triggerDialogueId: String? = null)	Opens the chat bot after connecting to the Kindly service. Parameters - context: - android context class Context. - triggerDialogueId: - Optional ID of a dialogue to trigger after connection.
saveNotificationToken	open override fun saveNotificationToken(token: String)	Saves the Firebase Cloud Messaging token for push notifications.
sendMessage	open override fun sendMessage(message: String, newContext: Map<String, String>? = null): Deferred<MessageChat>	Send a message on behalf of the user, programmatically. Routes through the same chokepoint as the chat input: optimistic local render, POST /message, and id reconciliation on response. The bubble appears immediately — do not display the message yourself in addition.
setCustomTheme	open override fun setCustomTheme(background: Color? = null, botMessageBackground: Color? = null, botMessageText: Color? = null, buttonBackground: Color? = null, buttonOutline: Color? = null, buttonText: Color? = null, chatLogElements: Color? = null, headerBackground: Color? = null, headerText: Color? = null, inputBackground: Color? = null, inputText: Color? = null, userMessageBackground: Color? = null, userMessageText: Color? = null, maintenanceHeaderBackground: Color? = null)	Sets a custom theme using individual color parameters. Only specified colors (non-null) will override the default theme. Parameters - background: Background color of the chat interface. - botMessageBackground: Background color for bot message bubbles. - botMessageText: Text color for bot messages. - buttonBackground: Background color for buttons. - buttonOutline: Outline color for buttons. - buttonText: Text color for buttons. - chatLogElements: Color for chat log elements like timestamps. - headerBackground: Background color for the header. - headerText: Text color for the header. - inputBackground: Background color for the input field. - inputText: Text color for the input field. - userMessageBackground: Background color for user message bubbles. - userMessageText: Text color for user messages.
setCustomTheme	open override fun setCustomTheme(theme: KindlyThemeColors)	Sets a custom theme for the chat UI. Parameters - theme: The custom theme to be applied.
setInputFieldHidden	fun setInputFieldHidden(hidden: Boolean)	Manually controls input field visibility. This will override any automatic visibility settings from messages or global settings. Parameters - hidden: true to hide the input field, false to show it
setLanguage	open override fun setLanguage(languageCode: String)	Updates the language for the current SDK session. This will be used for all subsequent chat connections and UI elements.
setNewContext	open override fun setNewContext(context: Map<String, String>)	Sets a new context for the chat. Parameters - context: - Map of strings where the key is the context name and the value is the context value.
setNotificationToken	fun setNotificationToken(token: String)
start	open override fun start(application: Application, botKey: String, languageCode: String = "en", market: String, authTokenProvider: KindlyAuthTokenProvider? = null, authTokenCallback: AuthTokenCallback? = null, authCredentialsProvider: KindlyAuthCredentialsProvider? = null)	Initializes the Kindly Chat SDK. This is the first method that should be called before using any other SDK functions. The SDK will automatically use NATIVE behavior for optimal performance and compliance. Parameters - application: The application context - botKey: The bot key for the Kindly Chat API - languageCode: The language code to use (default is "en") - market: Required market slug for the "Markets" feature (different UI/greeting/responses per location). You must pass the market configured for the bot. The SDK loads that market's settings (/settings/{botKey}/{market}.json) and tells /connect which market was picked. If the market's settings can't be loaded the chat won't load — there is no fallback to another market and no per-bot default settings. Find your market slugs in the Kindly platform (Settings → General → Details & markets). - authTokenProvider: Optional suspend-based token provider for authenticated chat. The SDK calls KindlyAuthTokenProvider.fetchToken with an AuthTokenRequest (chatId + reason: INITIAL_CONNECT or EXPIRED) from its own coroutine whenever it needs a JWT. Fetches are capped by a 15s SDK-side timeout and tokens that arrive already expired are discarded. Preferred over authTokenCallback. - authTokenCallback: Deprecated Deferred-based auth callback, kept for backward compatibility and adapted internally to a provider. Ignored when authTokenProvider is also set. Use authTokenProvider instead. - authCredentialsProvider: Optional provider for full KindlyAuthCredentials rather than a bare token. Use this when your identity provider issues more than a single JWT — a companion access token, an issuer the backend has to verify against, or an opaque token whose expiry only you know. Takes precedence over both authTokenProvider and authTokenCallback when more than one is set.
triggerDialogue	open override fun triggerDialogue(id: String)	Triggers a dialog for the provided id. Parameters - id: - dialog id - displayChat: - boolean to display the chat - context: - android context class Context.

ChatKindlySDK.Companion

object

object Companion : EntryPoint

Member	Declaration	Description
config	open override var config: KindlySDKConfig	The SDK configuration for permissions and theme settings.
enableCrashReporting	open override var enableCrashReporting: Boolean	Whether the SDK should send crash reports via Sentry. Defaults to true.
events	open override val events: Flow<KindlyEvent>	Unified event flow for all Kindly events (matches web API pattern) Subscribe to this to receive all events: load, message, buttonClick, ui, globalIcon, state
inputFieldHidden	val inputFieldHidden: Flow<Boolean>	Flow that emits input field visibility changes Subscribe to this to get real-time updates when input field should be hidden or shown
interface	open override var interface: KindlySDKInteraction?	Optional delegate for receiving button press and link interception callbacks.
isInitialized	val isInitialized: Boolean	True when the SDK has been fully started (start() completed) and its dependencies are initialized in THIS process. Returns false after low-memory process death until the host calls start() again. no.kindly.chatsdk.chat.presentation.ChatSDKActivity gates chat composition on this so an OS-driven restore (or external launch) of the exported Activity finishes gracefully instead of crashing on uninitialized process-global singletons (SDK-380). Safe to read at any time — never throws.
openChatOnNotificationTap	open override var openChatOnNotificationTap: Boolean	Whether tapping a Kindly notification opens the chat. Defaults to true. A tap that reaches the SDK before start (the notification launched the app, or the process had been killed) is remembered and the chat opens at the end of start; a tap older than a minute is dropped. With false the tap opens your launcher activity with KindlyNotificationIntent extras and nothing else.
shared	lateinit var shared: ChatKindlySDK
state	open override val state: Flow<KindlyEventState>	Unified state flow that emits state change events Subscribe to this to get real-time updates of: isChatDisplayed, isConnected, isStarted, isSocketConnected
verboseLogging	open override var verboseLogging: Boolean	Whether verbose logging is enabled. Defaults to false.
_clearSettingsOverrides	@RestrictTo(value = [RestrictTo.Scope.TESTS]) fun _clearSettingsOverrides()	Clear any previously set settings overrides.
_overrideSettings	@RestrictTo(value = [RestrictTo.Scope.TESTS]) fun _overrideSettings(overrides: Map<String, Any>)	Override parts of the settings response for testing purposes. Pass a map following the same JSON hierarchy as the settings response. The overrides are deep-merged with the server response — only the keys you provide are replaced. Can be called before or after start(): - Before start: overrides are stored and applied when settings are fetched. - After start (settings already loaded): overrides are applied immediately.
_setVerboseLogs	@RestrictTo(value = [RestrictTo.Scope.TESTS]) fun _setVerboseLogs(enabled: Boolean)	Force the logger into "show everything" mode at runtime, surfacing every log level (including VERBOSE) on production builds. Equivalent to building with WHERE_AM_I = LOCAL, but scoped to logging only — does not affect API endpoints, Pusher key, Sentry, or anything else that reads Session.whereAmI. Useful for diagnosing customer issues without shipping a debug-tier build. Can be called before or after start. The flag persists for the SDK's lifetime; pass false to revert. Usage (from host app): kotlin KindlySDK._setVerboseLogs(true) KindlySDK.start(application, botKey = "...")
authenticate	open override fun authenticate(): Deferred<Unit>	Re-authenticates the live chat, asking the configured provider for fresh credentials. For the case the SDK cannot detect on its own: the user signed in, or switched account, while the chat was already open. The SDK refreshes on expiry by itself, so this is only needed when the identity changed rather than the token. The chat, its history and its socket are all kept — this re-binds the identity in place and does not restart anything. Returns - A Deferred that completes once the backend has accepted the new credentials, and completes exceptionally if the provider failed or the backend refused them.
callHandover	open override fun callHandover(handoverListener: CallbackHandover)	Handovers the call from the chatBot. Parameters - handoverListener: - CallbackHandover object to handle the handover.
clearCustomTheme	open override fun clearCustomTheme()	Clears any custom theme that has been set and reverts to the default theme.
clearNewContext	open override fun clearNewContext()	Clears the current context of the chat.
clearTriggerDialog	open override fun clearTriggerDialog()	Clearing trigger dialog param call
close	open override fun close()	Closes the chat.
deauthenticate	open override fun deauthenticate(): Deferred<Unit>	Signs the user out of the chat without ending it. Unbinds the identity on the backend and forgets the stored credentials. The chat carries on anonymously with its history intact — use endChat instead when the conversation itself should end. Safe to call when the chat is already anonymous; it completes immediately. The local credentials are cleared even when the backend call fails, so a sign-out is never left half done, but the result still completes exceptionally so the host knows the backend did not hear about it. Returns - A Deferred that completes once the identity has been unbound.
displayChat	open override fun displayChat(context: Context)	Displays the chat UI. This method is kept for backward compatibility but it's recommended to use launchChat() instead which handles connection logic.
endChat	open override fun endChat(): Deferred<Unit>	Ends the chat session and disconnects from the server. This acts as a disconnect - the SDK remains initialized and can be reconnected by calling launchChat() again without needing to call start(). Use kill() if you want to completely terminate the SDK.
handleNotification	open override fun handleNotification(remoteMessage: RemoteMessage)	Handles an incoming Firebase push notification. Call this from your FirebaseMessagingService.
handleUrl	open override fun handleUrl(context: Context, uri: Uri): Boolean	Handles a Kindly URL scheme deep link. Supported format: kindly://chat/dialogue/ Parameters - context: Android context for launching the chat UI if needed - uri: The URI to handle Returns - true if the URL was handled, false otherwise
isInputFieldHidden	fun isInputFieldHidden(): Boolean	Gets the current input field visibility state. Returns - true if input field is currently hidden, false if visible
isKindlyNotification	open override fun isKindlyNotification(remoteMessage: RemoteMessage): Boolean	Checks if a notification is from Kindly. This function is used to determine if an incoming notification should be handled by the Kindly SDK. It's particularly useful when integrated with other notification handling systems. A pure check on the message data, so it works before start() too (a process FCM started to deliver a push). Parameters - remoteMessage: The message received from Firebase. Returns - Boolean indicating whether the notification is from Kindly.
kill	open override fun kill(): Deferred<Unit>	Completely kills the SDK and clears all state. After calling this method, start() must be called again before using any other SDK functions. This is more destructive than endChat() which only disconnects the chat session.
launchChat	open override fun launchChat(context: Context, triggerDialogueId: String? = null)	Opens the chat bot after connecting to the Kindly service. Parameters - context: - android context class Context. - triggerDialogueId: - Optional ID of a dialogue to trigger after connection.
saveNotificationToken	open override fun saveNotificationToken(token: String)	Saves the Firebase Cloud Messaging token for push notifications.
sendMessage	open override fun sendMessage(message: String, newContext: Map<String, String>? = null): Deferred<MessageChat>	Send a message on behalf of the user, programmatically.
setCustomTheme	open override fun setCustomTheme(background: Color? = null, botMessageBackground: Color? = null, botMessageText: Color? = null, buttonBackground: Color? = null, buttonOutline: Color? = null, buttonText: Color? = null, chatLogElements: Color? = null, headerBackground: Color? = null, headerText: Color? = null, inputBackground: Color? = null, inputText: Color? = null, userMessageBackground: Color? = null, userMessageText: Color? = null, maintenanceHeaderBackground: Color? = null)	Sets a custom theme using individual color parameters. Only specified colors (non-null) will override the default theme.
setCustomTheme	open override fun setCustomTheme(theme: KindlyThemeColors)	Sets a custom theme for the chat UI. Parameters - theme: The custom theme to be applied.
setInputFieldHidden	fun setInputFieldHidden(hidden: Boolean)	Manually controls input field visibility. This will override any automatic visibility settings from messages or global settings. Parameters - hidden: true to hide the input field, false to show it
setLanguage	open override fun setLanguage(languageCode: String)	Updates the language for the current SDK session. This will be used for all subsequent chat connections and UI elements.
setNewContext	open override fun setNewContext(context: Map<String, String>)	Sets a new context for the chat. Parameters - context: - Map of strings where the key is the context name and the value is the context value.
start	open override fun start(application: Application, botKey: String, languageCode: String = "en", market: String, authTokenProvider: KindlyAuthTokenProvider? = null, authTokenCallback: AuthTokenCallback? = null, authCredentialsProvider: KindlyAuthCredentialsProvider? = null)	Initializes the chat SDK with the provided application, chatBotKey, and codeLanguage. The SDK will automatically use NATIVE behavior for optimal performance and compliance. Parameters - application: - base class for maintaining global application state. - botKey: - chatBot key - languageCode: - code language - market: - required market slug (see EntryPoint.start). - authTokenProvider: - suspend-based token provider for authenticated chat. Preferred. - authTokenCallback: - deprecated Deferred-based auth callback; adapted internally to a provider. Ignored when authTokenProvider is also set.
triggerDialogue	open override fun triggerDialogue(id: String)	Triggers a dialog for the provided id. Parameters - id: - dialog id - displayChat: - boolean to display the chat - context: - android context class Context.

EntryPoint

interface

interface EntryPoint

Public interface defining the Kindly Chat SDK API. Use ChatKindlySDK (aliased as KindlySDK) to access the implementation.

Member	Declaration	Description
config	abstract var config: KindlySDKConfig	The SDK configuration for permissions and theme settings.
enableCrashReporting	abstract var enableCrashReporting: Boolean	Whether the SDK should send crash reports via Sentry. Defaults to true.
events	abstract val events: Flow<KindlyEvent>	Unified event flow for all Kindly events (matches web API pattern) Subscribe to this to receive all events: load, message, buttonClick, ui, state
interface	abstract var interface: KindlySDKInteraction?	Optional delegate for receiving button press and link interception callbacks.
openChatOnNotificationTap	abstract var openChatOnNotificationTap: Boolean	Whether tapping a Kindly notification opens the chat. Defaults to true. A tap that reaches the SDK before start (the notification launched the app, or the process had been killed) is remembered and the chat opens at the end of start; a tap older than a minute is dropped. With false the tap opens your launcher activity with KindlyNotificationIntent extras and nothing else.
state	abstract val state: Flow<KindlyEventState>	Unified state flow that emits state change events Subscribe to this to get real-time updates of: isChatDisplayed, isConnected, isStarted, isSocketConnected
verboseLogging	abstract var verboseLogging: Boolean	Whether verbose logging is enabled. Defaults to false.
authenticate	abstract fun authenticate(): Deferred<Unit>	Re-authenticates the live chat, asking the configured provider for fresh credentials. For the case the SDK cannot detect on its own: the user signed in, or switched account, while the chat was already open. The SDK refreshes on expiry by itself, so this is only needed when the identity changed rather than the token. The chat, its history and its socket are all kept — this re-binds the identity in place and does not restart anything. Returns - A Deferred that completes once the backend has accepted the new credentials, and completes exceptionally if the provider failed or the backend refused them.
callHandover	abstract fun callHandover(handoverListener: CallbackHandover)	Initiates a handover to a human agent. The listener is called when the handover is ready.
clearCustomTheme	abstract fun clearCustomTheme()	Clears any custom theme that has been set and reverts to the default theme.
clearNewContext	abstract fun clearNewContext()	Clears any previously set context.
clearTriggerDialog	abstract fun clearTriggerDialog()	Clears any pending trigger dialogue request.
close	abstract fun close()	Dismisses the chat UI without ending the session.
deauthenticate	abstract fun deauthenticate(): Deferred<Unit>	Signs the user out of the chat without ending it. Unbinds the identity on the backend and forgets the stored credentials. The chat carries on anonymously with its history intact — use endChat instead when the conversation itself should end. Safe to call when the chat is already anonymous; it completes immediately. The local credentials are cleared even when the backend call fails, so a sign-out is never left half done, but the result still completes exceptionally so the host knows the backend did not hear about it. Returns - A Deferred that completes once the identity has been unbound.
displayChat	abstract fun displayChat(context: Context)	Displays the chat UI directly. NOTE: This method is kept for backward compatibility. It's recommended to use launchChat() instead which ensures proper connection before displaying the UI. Parameters - context: Android context for launching the UI
endChat	abstract fun endChat(): Deferred<Unit>	Ends the active chat session, clears messages and token, and dismisses the UI. Returns - A Deferred that completes once the session has fully disconnected and the UI has been dismissed (or after a short failsafe timeout if disconnect hangs). Awaiting the result is optional — callers that don't need to observe completion can ignore it (parity with iOS endChat() returning a promise).
handleNotification	abstract fun handleNotification(remoteMessage: RemoteMessage)	Handles an incoming Firebase push notification. Call this from your FirebaseMessagingService.
handleUrl	abstract fun handleUrl(context: Context, uri: Uri): Boolean	Handles a Kindly URL scheme deep link. Supported format: kindly://chat/dialogue/ Parameters - context: Android context for launching the chat UI if needed - uri: The URI to handle Returns - true if the URL was handled, false otherwise
isKindlyNotification	abstract fun isKindlyNotification(remoteMessage: RemoteMessage): Boolean	Returns true if the given push notification originated from the Kindly service.
kill	abstract fun kill(): Deferred<Unit>	Completely kills the SDK and clears all state. After calling this method, start() must be called again before using any other SDK functions. This is more destructive than endChat() which only disconnects the chat session. Returns - A Deferred that completes once teardown has finished. Awaiting the result is optional (parity with iOS kill() returning a promise).
launchChat	abstract fun launchChat(context: Context, triggerDialogueId: String? = null)	Opens the chat bot after connecting to the Kindly service. This method handles both the connection to the Kindly service and displaying the UI. It's the recommended way to launch the chat experience. Parameters - context: Android context for launching the UI - triggerDialogueId: Optional ID of a dialogue to trigger after connection
saveNotificationToken	abstract fun saveNotificationToken(token: String)	Saves the Firebase Cloud Messaging token for push notifications.
sendMessage	abstract fun sendMessage(message: String, newContext: Map<String, String>? = null): Deferred<MessageChat>	Send a message on behalf of the user, programmatically. Lets the host app drive the conversation as if the user typed and tapped send. The SDK renders the bubble locally with a temporary id and reconciles it with the server-assigned id when the POST response returns — do not also display the message yourself, and do not add it to any external chat log you maintain. Behaviour: - Trims whitespace; an empty/whitespace-only message completes exceptionally with KindlySDKError.InvalidData. - Completes exceptionally with KindlySDKError.ChatNotConnected if called before the chat is connected. Observe KindlySDK.state for isConnected first. - Per-call newContext overrides any context previously staged via setNewContext. Parameters - message: The message text to send. Whitespace is trimmed. - newContext: Optional per-call context attached to this message only. Returns - A Deferred that completes with the reconciled MessageChat (carrying the server-assigned id and timestamp), or completes exceptionally on failure.
setCustomTheme	abstract fun setCustomTheme(background: Color? = null, botMessageBackground: Color? = null, botMessageText: Color? = null, buttonBackground: Color? = null, buttonOutline: Color? = null, buttonText: Color? = null, chatLogElements: Color? = null, headerBackground: Color? = null, headerText: Color? = null, inputBackground: Color? = null, inputText: Color? = null, userMessageBackground: Color? = null, userMessageText: Color? = null, maintenanceHeaderBackground: Color? = null)	Sets a custom theme using individual color parameters. Only specified colors (non-null) will override the default theme. Parameters - background: Background color of the chat interface. - botMessageBackground: Background color for bot message bubbles. - botMessageText: Text color for bot messages. - buttonBackground: Background color for buttons. - buttonOutline: Outline color for buttons. - buttonText: Text color for buttons. - chatLogElements: Color for chat log elements like timestamps. - headerBackground: Background color for the header. - headerText: Text color for the header. - inputBackground: Background color for the input field. - inputText: Text color for the input field. - userMessageBackground: Background color for user message bubbles. - userMessageText: Text color for user messages.
setCustomTheme	abstract fun setCustomTheme(theme: KindlyThemeColors)	Sets a custom theme for the chat UI. Parameters - theme: The custom theme to be applied.
setLanguage	abstract fun setLanguage(languageCode: String)	Updates the language for the current SDK session. This will be used for all subsequent chat connections and UI elements. Parameters - languageCode: The language code to use (e.g., "en", "lt", "sv")
setNewContext	abstract fun setNewContext(context: Map<String, String>)	Sets context key-value pairs that will be attached to the next message or button click request.
start	abstract fun start(application: Application, botKey: String, languageCode: String = "en", market: String, authTokenProvider: KindlyAuthTokenProvider? = null, authTokenCallback: AuthTokenCallback? = null, authCredentialsProvider: KindlyAuthCredentialsProvider? = null)	Initializes the Kindly Chat SDK. This is the first method that should be called before using any other SDK functions. The SDK will automatically use NATIVE behavior for optimal performance and compliance. Parameters - application: The application context - botKey: The bot key for the Kindly Chat API - languageCode: The language code to use (default is "en") - market: Required market slug for the "Markets" feature (different UI/greeting/responses per location). You must pass the market configured for the bot. The SDK loads that market's settings (/settings/{botKey}/{market}.json) and tells /connect which market was picked. If the market's settings can't be loaded the chat won't load — there is no fallback to another market and no per-bot default settings. Find your market slugs in the Kindly platform (Settings → General → Details & markets). - authTokenProvider: Optional suspend-based token provider for authenticated chat. The SDK calls KindlyAuthTokenProvider.fetchToken with an AuthTokenRequest (chatId + reason: INITIAL_CONNECT or EXPIRED) from its own coroutine whenever it needs a JWT. Fetches are capped by a 15s SDK-side timeout and tokens that arrive already expired are discarded. Preferred over authTokenCallback. - authTokenCallback: Deprecated Deferred-based auth callback, kept for backward compatibility and adapted internally to a provider. Ignored when authTokenProvider is also set. Use authTokenProvider instead. - authCredentialsProvider: Optional provider for full KindlyAuthCredentials rather than a bare token. Use this when your identity provider issues more than a single JWT — a companion access token, an issuer the backend has to verify against, or an opaque token whose expiry only you know. Takes precedence over both authTokenProvider and authTokenCallback when more than one is set.
triggerDialogue	abstract fun triggerDialogue(id: String)	Triggers a specific dialogue by its ID. The SDK must be connected.

KindlyAuthCredentials

data class

data class KindlyAuthCredentials(val idToken: String? = null, val accessToken: String? = null, val issuer: String? = null, val expiresAt: Long? = null)

The credentials the host app hands the SDK to authenticate a chat.

The Kindly platform verifies an authenticated chat in one of three ways, and this single type covers all of them — which is why nothing here is named after any one of them:

Kindly JWT — a JWT your own backend signs. Only idToken is read; accessToken is ignored by this strategy.

Identity provider (JWKS) — a JWT minted by your identity provider. Set accessToken as well when the provider hands you a separate access token; the backend then verifies the pair together and forwards the access token to your webhooks rather than the id token.

Introspection — an opaque bearer token. Put it in idToken and set issuer so the backend knows which provider to introspect it against.

Every field is optional, but at least one of idToken / accessToken must be set - whichever is present becomes the Authorization: Bearer (see bearerToken). A single-JWT integration can keep returning a plain String from KindlyAuthTokenProvider and never touch this type at all.

Member	Declaration	Description
KindlyAuthCredentials	constructor(idToken: String? = null, accessToken: String? = null, issuer: String? = null, expiresAt: Long? = null)
accessToken	val accessToken: String?
bearerToken	val bearerToken: String?	The token actually sent as Authorization: Bearer, or null when neither field was set. Authorization is mandatory on the backend's auth route, so whichever token the host has goes there — idToken first, falling back to accessToken. A provider that returns only an access token is a normal, supported case: the backend verifies it by whichever strategy the bot is configured for, exactly as it did before dual-token support existed.
companionAccessToken	val companionAccessToken: String?	The access token in its companion role — the value that will be sent as X-Access-Token, or null when no companion header will be sent. Exposed so a host can see what the SDK will actually do rather than re-deriving the rule. It is null in two cases that are easy to get wrong: when the access token is itself the bearer (no id token was supplied), and when it merely duplicates the id token. The backend verifies the companion against the id token's at_hash and rejects a mismatched pair outright, so sending a duplicate would fail an auth that would otherwise have succeeded.
expiresAt	val expiresAt: Long?
hasToken	val hasToken: Boolean	true when these credentials carry something usable.
idToken	val idToken: String?
issuer	val issuer: String?

KindlyAuthCredentialsProvider

fun interface

fun interface KindlyAuthCredentialsProvider

Supplies full authentication credentials to the SDK.

Use this instead of KindlyAuthTokenProvider when your identity provider issues more than a single JWT — a companion access token, an issuer the backend has to verify against, or an opaque token whose expiry only you know.

Same contract as KindlyAuthTokenProvider otherwise: the SDK calls it from its own coroutine, bounds the call at 15 seconds, and discards credentials that arrive already expired. Throw to signal failure.

Member	Declaration	Description
fetchCredentials	abstract suspend fun fetchCredentials(request: AuthTokenRequest): KindlyAuthCredentials

KindlyAuthTokenProvider

fun interface

fun interface KindlyAuthTokenProvider

Member	Declaration	Description
fetchToken	abstract suspend fun fetchToken(request: AuthTokenRequest): String

KindlyNotificationIntent

object

object KindlyNotificationIntent

Extras the SDK attaches to the intent that reaches your launcher activity when the user taps a Kindly banner while the SDK is not started (the tap launched the app, or the process had been killed).

The SDK opens the chat by itself once you call start() (see KindlySDK.openChatOnNotificationTap); use read in onCreate and onNewIntent only if you want to route the tap yourself. Treat the values as hints from an intent, not as authenticated data.

Member	Declaration	Description
EXTRA_BODY	const val EXTRA_BODY: String
EXTRA_CHAT_ID	const val EXTRA_CHAT_ID: String
EXTRA_DATA	const val EXTRA_DATA: String	A Bundle of String values: the original FCM data map, including the encrypted fields.
EXTRA_IS_KINDLY_NOTIFICATION	const val EXTRA_IS_KINDLY_NOTIFICATION: String
EXTRA_TITLE	const val EXTRA_TITLE: String
isKindlyNotificationTap	fun isKindlyNotificationTap(intent: Intent?): Boolean	Whether the intent comes from a tapped Kindly banner.
read	fun read(intent: Intent?): ExternalNotification?	The decrypted notification behind a tapped banner, or null when the intent is not a Kindly tap.

KindlySDK

typealias

typealias KindlySDK = ChatKindlySDK

Convenience alias for ChatKindlySDK. Use KindlySDK to access the SDK.

KindlySDKConfig

class

class KindlySDKConfig

Configuration for the Kindly Chat SDK. Access via ChatKindlySDK.config to modify permissions, theme, and status bar behavior.

Member	Declaration	Description
KindlySDKConfig	constructor()
allowCameraAccess	var allowCameraAccess: Boolean	Whether the SDK is allowed to access the device camera for attachments. Defaults to true.
allowPhotoLibraryAccess	var allowPhotoLibraryAccess: Boolean	Whether the SDK is allowed to access the photo library for attachments. Defaults to true.
autoMatchStatusBarColor	var autoMatchStatusBarColor: Boolean	Controls whether the SDK should automatically match the status bar color to the header color. When true (default), the SDK will set the status bar color to match the header if the host app hasn't set a custom status bar color. When false, the SDK will never modify the status bar color.
forceOverrideStatusBarColor	var forceOverrideStatusBarColor: Boolean	When true, the SDK will always override the status bar color to match the header, even if the host app has set a custom status bar color. When false (default), the SDK respects the host app's custom status bar color. Note: This only works when autoMatchStatusBarColor is also true.
clearCustomTheme	fun clearCustomTheme()	Clears any custom theme that has been set and reverts to the default theme.
setCustomTheme	fun setCustomTheme(background: Color? = null, botMessageBackground: Color? = null, botMessageText: Color? = null, buttonBackground: Color? = null, buttonOutline: Color? = null, buttonText: Color? = null, chatLogElements: Color? = null, headerBackground: Color? = null, headerText: Color? = null, inputBackground: Color? = null, inputText: Color? = null, userMessageBackground: Color? = null, userMessageText: Color? = null, maintenanceHeaderBackground: Color? = null)	Sets a custom theme using individual color parameters. Only specified colors (non-null) will override the default theme. Parameters - background: Background color of the chat interface. - botMessageBackground: Background color for bot message bubbles. - botMessageText: Text color for bot messages. - buttonBackground: Background color for buttons. - buttonOutline: Outline color for buttons. - buttonText: Text color for buttons. - chatLogElements: Color for chat log elements like timestamps. - headerBackground: Background color for the header. - headerText: Text color for the header. - inputBackground: Background color for the input field. - inputText: Text color for the input field. - userMessageBackground: Background color for user message bubbles. - userMessageText: Text color for user messages.
setCustomTheme	fun setCustomTheme(theme: KindlyThemeColors)	Sets a custom theme for the chat UI. Parameters - theme: The custom theme to be applied.

no.kindly.chatsdk.chat.common

CallbackHandover

interface

interface CallbackHandover

Callback interface for handover events. Implement this and pass to ChatKindlySDK.callHandover to be notified when a handover to a human agent is ready.

Member	Declaration	Description
callHandover	abstract fun callHandover()	Called when the handover to a human agent is initiated.

colorList

property

val colorList: Map<ItemColor, Color>

Default color list

emailTo

function

fun Context.emailTo(email: String, subject: String? = null, content: String? = null)

Context extension for sending and email

Parameters

email: = email string

subject: - title of the email

content: - body for email

KindlySDKInteraction

interface

interface KindlySDKInteraction

Interface for receiving button press and link interception callbacks from the Kindly SDK. Set via ChatKindlySDK.interface to start receiving events.

Member	Declaration	Description
didPressButton	abstract fun didPressButton(chatButton: ButtonChat, chatLog: List<MessageChat>)	Called when a chat button is pressed by the user. Parameters - chatButton: The button that was pressed. - chatLog: The current chat message history.
shouldHandleLink	open fun shouldHandleLink(url: String): Boolean	Called when a link is about to be opened from within the SDK. Return true to let the SDK handle the link normally, or false to handle it yourself in the host app. Parameters - url: The URL string that is about to be opened. Returns - true if the SDK should handle the link, false if the host app will handle it.
shouldHandleNotification	open fun shouldHandleNotification(notification: ExternalNotification): Boolean	Called for every Kindly silent push the SDK receives and successfully decrypts. Fires regardless of app state (foreground/background) or active screen — the SDK does not gate this callback. Use it to run side effects (analytics, logging) or to take over the presentation of the notification yourself. Return true to let the SDK present the notification normally (subject to its display gate). Return false to handle it yourself in the host app — the SDK will then skip its own system notification. Parameters - notification: The decrypted notification (id, title, body) plus the raw data map. Returns - true if the SDK should handle it, false if the host app will handle it.

LinkHandler

object

object LinkHandler

Member	Declaration	Description
openLink	fun openLink(context: Context, url: String): Boolean

showToast

function

fun Context.showToast(@StringRes content: Int, length: Int? = null)

Context extension for showing toast

Parameters

idContent: - string resource

showToast

function

fun Context.showToast(content: String, length: Int? = null)

no.kindly.chatsdk.chat.common.extensions

isFalse

property

val Boolean?.isFalse: Boolean

isTrue

property

val Boolean?.isTrue: Boolean

no.kindly.chatsdk.chat.common.video

VideoPlatform

enum

enum VideoPlatform : Enum<VideoPlatform>

Member	Declaration	Description
YOUTUBE	YOUTUBE
VIMEO	VIMEO
MP4	MP4
UNKNOWN	UNKNOWN
entries	val entries: EnumEntries<VideoPlatform>	Returns a representation of an immutable list of all enum entries, in the order they're declared. This method may be used to iterate over the enum entries.
valueOf	fun valueOf(value: String): VideoPlatform	Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.) Throws - kotlin.IllegalArgumentException: if this enum type has no constant with the specified name
values	fun values(): Array<VideoPlatform>	Returns an array containing the constants of this enum type, in the order they're declared. This method may be used to iterate over the constants.

VideoUtils

object

object VideoUtils

Member	Declaration	Description
checkVideoPlatform	fun checkVideoPlatform(url: URL): VideoPlatform
getEmbedCode	fun getEmbedCode(iFrame: String): String
isOEmbedSupportedVideo	fun isOEmbedSupportedVideo(url: URL): Boolean
isSupportedVideo	fun isSupportedVideo(url: URL): Boolean
oEmbedURL	fun oEmbedURL(url: URL): URL?
oEmbedURL	fun oEmbedURL(videoPlatform: VideoPlatform): URL?