Classes

public static var shared: KindlyChatClient!

The shared singleton instance of the Kindly Chat SDK. Available after calling start().

public static var config: KindlySDKConfig

The SDK configuration for permissions, auth callbacks, and form settings.

public static var connectionState: ChatConnectionState

The current connection state of the SDK.

public static var inputFieldHidden: Bool

Whether the input field is currently hidden

public static var delegate: KindlyChatClientDelegate!

A static delegate that gets or sets the delegate of the shared instance of KindlyChatClient.

public init(config: CoreSDKConfig, behaviorType: BehaviorTypeEnum)

Initialize Kindly Chat SDK. In most cases, you will only want to have one instance of KindlyChatClient. Our "Getting started" guide covers this topic and gives you instructions on how to configure the SDK. Parameters - config: API keys and other configuration of type KindlySDKConfig.

static var events: AnyPublisher<KindlyEvent, Never>

Unified event publisher for all Kindly events (matches web API pattern) Subscribe to this to receive all events: load, message, buttonClick, ui, state

static var state: AnyPublisher<KindlyEventState, Never>

Unified state publisher that emits state change events Subscribe to this to get real-time updates of: isChatDisplayed, isConnected, isStarted, isSocketConnected

static var notificationDelegate: NotificationDelegate

The shared notification delegate for handling Kindly push notifications. Assign this to UNUserNotificationCenter.current().delegate to let the SDK process incoming notifications.

static var verboseLogging: Bool

The current state of the SDK.

static func setCustomTheme(_ theme: Theme)

Sets a custom theme for the chat. Parameters - theme: The theme to be applied to the chat. This theme will override any theme retrieved from Kindly's settings.

static func setCustomTheme( background: UIColor? = nil, botMessageBackground: UIColor? = nil, botMessageText: UIColor? = nil, buttonBackground: UIColor? = nil, buttonOutline: UIColor? = nil, buttonSelectedBackground: UIColor? = nil, buttonText: UIColor? = nil, defaultShadow: UIColor? = nil, inputBackground: UIColor? = nil, inputCursor: UIColor? = nil, inputText: UIColor? = nil, navBarBackground: UIColor? = nil, navBarText: UIColor? = nil, userMessageBackground: UIColor? = nil, userMessageText: UIColor? = nil )

Sets a custom theme for the chat using the CustomTheme struct. Parameters - background: Background color for 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. - buttonSelectedBackground: Background color for selected buttons. - buttonText: Text color for buttons. - defaultShadow: Default shadow color. - inputBackground: Background color for the input field. - inputCursor: Color for the input cursor. - inputText: Text color for the input field. - navBarBackground: Background color for the navigation bar. - navBarText: Text color for the navigation bar. - userMessageBackground: Background color for user message bubbles. - userMessageText: Text color for user messages.

static func clearCustomTheme()

Clears any custom theme that has been set and reverts to the API theme or default theme.

static var openChatOnNotificationTap: Bool

Whether tapping a Kindly notification opens the chat. Defaults to true. When the tap arrives before start() (the notification launched the app) the SDK remembers it and opens the chat once start() has been called and the app is active. A tap older than a minute is dropped.

static var notificationMode: KindlyNotificationMode

How Kindly push notifications reach this app. Defaults to KindlyNotificationMode.automatic. The SDK tells the backend when it registers for push, and the backend sends a visible, decrypted-on-device alert only to an app that can decrypt it. With .automatic the SDK detects that by itself: it looks for a Notification Service Extension in your app that is built on the Kindly SDK. Set .alert or .silent to override. A change applies from the next token registration, which happens every time the chat connects.

static var enableCrashReporting: Bool

Whether the SDK should send crash reports via Sentry. Defaults to true.

class func start(botKey: String, languageCode: String = "en", market: String, authTokenCallback: AuthTokenCallback? = nil)

Start the Kindly Chat SDK. The SDK will automatically use .native behavior for optimal performance and compliance. - botKey: The bot key for the bot you want to connect to. - languageCode: The language code for the chat. Defaults to "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). - authTokenCallback: A callback function that will be called when the authentication token is available.

class func start( botKey: String, languageCode: String = "en", market: String, authCredentialsCallback: @escaping AuthCredentialsCallback )

Starts the SDK with full authentication credentials rather than a bare token. Use this overload 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. Everything else behaves exactly like the token overload. - botKey: The bot key for the bot you want to connect to. - languageCode: The language code for the chat. Defaults to "en". - market: Required market slug — see the token overload. - authCredentialsCallback: Called with the current chatId and a Promise you fulfil with a KindlyAuthCredentials.

class func displayChat(languageCode: String? = nil, triggerDialogueId: String? = nil)

This function is used to display the chat interface. It first checks if there is a key window available, and if there is a root view controller. If both conditions are met, it creates a new instance of KindlyChatNavigationController. Parameters - languageCode: Optional language code to use for this chat session. If provided, it will override the language set during SDK start. - triggerDialogueId: Optional dialogue ID to trigger after connection.

func displayChat(languageCode: String? = nil, triggerDialogueId: String? = nil)

This function is used to display the chat interface. It first checks if there is a key window available, and if there is a root view controller. If both conditions are met, it creates a new instance of KindlyChatNavigationController. Parameters - languageCode: Optional language code to use for this chat session. If provided, it will override the language set during SDK start. - triggerDialogueId: Optional dialogue ID to trigger after connection.

class func setLanguage(_ languageCode: String) -> Promise<Void>

Update the language for the current SDK session. This will be used for all subsequent chat connections. Parameters - languageCode: The language code to use (e.g., "en", "lt", "sv") Returns - Promise that resolves when language change is complete

class func setNewContext(_ context: [String: String])

Set the current context that will be set in the next message or click request Parameters - context: context to be set

func setNewContext(_ context: [String: String])

Set the current context that will be set in the next message or click request Parameters - context: context to be set

class func clearNewContext()

Clear the currently set context

func clearNewContext()

Clear the currently set context

@discardableResult class func sendMessage(_ text: String, newContext: [String: String]? = nil) -> Promise<ExternalChatMessage>

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 string rejects with KindlySDKError.invalidData. - Rejects with KindlySDKError.chatNotConnected if called before the chat is connected. Use KindlySDK.state to observe isConnected before calling. - Per-call newContext overrides any context previously staged via setNewContext(_:). Parameters - text: The message text to send. Whitespace is trimmed. - newContext: Optional per-call context attached to this message only. Returns - A Promise<ExternalChatMessage> that resolves with the reconciled message (carrying the server-assigned id and timestamp), or rejects with the underlying error.

class func setAPNSDeviceToken(_ deviceToken: Data)

Sets the device token. Parameters - deviceToken: The device token to be set. It is of type Data.

class func setAPNSDeviceToken(_ deviceToken: String)

Sets the device token. Parameters - deviceToken: The device token to be set. It is of type String.

@discardableResult class func saveAuthToken(_ token: String) -> Bool

Saves the authentication token in the Keychain. Parameters - token: The authentication token to be saved.

@discardableResult class func saveAuthCredentials(_ credentials: KindlyAuthCredentials) -> Bool

Saves full authentication credentials in the Keychain. The direct equivalent of saveAuthToken(_:) for integrations whose identity provider issues more than a single JWT. The SDK uses these until they expire or the backend rejects them, then falls back to the callback given at start(...) if there is one. Parameters - credentials: The credentials to store. Returns - false if start() has not been called yet, or the Keychain refused the write.

@discardableResult class func authenticate() -> Promise<Void>

Re-authenticates the live chat, asking the host callback 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 promise that fulfils once the backend has accepted the new credentials, and rejects if the callback failed or the backend refused them.

@discardableResult class func deauthenticate() -> Promise<Void>

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 fulfils immediately. The local credentials are cleared even when the backend call fails, so a sign-out is never left half done, but the promise still rejects so the host knows the backend did not hear about it. Returns - A promise that fulfils once the identity has been unbound.

@discardableResult func saveAuthToken(_ token: String) -> Bool

Saves the authentication token in the Keychain. Parameters - token: The authentication token to be saved.

@discardableResult func saveAuthCredentials(_ credentials: KindlyAuthCredentials) -> Bool

Saves full authentication credentials in the Keychain. Replaces whatever was stored before, including the previous access token, issuer and expiries — a partial overwrite would leave the SDK sending one credential's access token alongside another's id token.

class func closeChat()

This function is used to close the chat by dismissing the kindlyChatNavigationController.

func closeChat()

This function is used to close the chat by dismissing the kindlyChatNavigationController. Always dispatches to the main thread — the public KindlySDK.closeChat() is callable from any thread, and the internal endChat() invokes this from the disconnect() onComplete callback which runs on the .promises background queue (Promise.then's default). UIKit dismiss(animated:) must be called on main; calling from background triggers Main Thread Checker warnings (and rare race-conditions in older iOS).

class func endChat() -> Promise<Void>

Ends the active chat session. Messages, token and current connection will be cleared. This will call the "user left" API in Kindly Chat. Note Please note that the Chat UI will be dismissed after using this function.

class func kill() -> Promise<Void>

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.

func endChat() -> Promise<Void>

Ends the active chat session. Messages, token and current connection will be cleared. This will call the "user left" API in Kindly Chat. Note Please note that the Chat UI will be dismissed after using this function.

class func notificationReceived(_ userInfo: [AnyHashable: Any])

Handles a received notification from the didReceiveRemoteNotification path (silent pushes). The SDK decrypts it, asks KindlyChatClientDelegate.shouldHandleNotification, and posts a local banner unless the user is on the chat screen. For a visible push delivered while the app is in the foreground use notificationWillPresent(_:completionHandler:) instead, which can also decide what iOS presents. Parameters - userInfo: The user information dictionary that contains data related to the notification.

class func notificationReceived(_ notification: UNNotification)

Handles the received notification. Parameters - notification: The notification that was received.

class func notificationWillPresent(_ notification: UNNotification, completionHandler: @escaping (UNNotificationPresentationOptions) -> Void)

Decides what iOS should present for a notification delivered while the app is in the foreground. Call it from your own UNUserNotificationCenterDelegate.willPresent and pass the completion handler through. The SDK returns banner and sound for notifications that are not Kindly's, and for Kindly notifications applies its display rule: nothing while the user is on the chat screen, the decrypted content when the Notification Service Extension already rewrote it, and its own decrypted banner in place of the placeholder when there is no extension. Parameters - notification: The notification handed to willPresent. - completionHandler: The completion handler handed to willPresent.

class func notificationResponseReceived(_ response: UNNotificationResponse)

Handles the received notification response (the user tapped the notification). Opens the chat when openChatOnNotificationTap is on and the notification is Kindly's. Parameters - response: The notification response that was received.

class func isKindlyNotification(_ userInfo: [AnyHashable: Any]) -> Bool

Checks if the notification is from Kindly. Works before start(), so it can route a tap that launched the app. Parameters - userInfo: The user information dictionary from the notification. Returns - A boolean indicating whether the notification is from Kindly.

class func triggerDialogue(id: String)

Triggers a specific dialogue by its ID. The SDK must be connected before calling this method. Parameters - id: The dialogue ID to trigger.

@discardableResult class func handleURL(_ url: URL) -> Bool

Handles a Kindly deep link URL. Supported format: kindly://chat/dialogue/{id} Parameters - url: The URL to handle. Returns - true if the URL was recognized and handled, false otherwise.

static func _forceConnectionState(_ state: ChatConnectionState)