--- title: Enumerations, Protocols, Extensions and Type Aliases slug: sdk/ios-sdk-api-reference-enumerations-protocols-extensions-and-type-aliases createdAt: 2026-11-04T11:40:20.873Z --- # Enumerations ## BehaviorTypeEnum `enum` ```swift public enum BehaviorTypeEnum ``` | Member | Declaration | Description | | -------- | ------------- | ----------- | | `native` | `case native` | | ## ChatConnectionState `enum` ```swift public enum ChatConnectionState ``` Connection state for the Kindly Chat API. | Member | Declaration | Description | | ------------------- | ------------------------ | ------------------------------------------------ | | `none` | `case none` | No connection has been attempted. | | `connecting` | `case connecting` | The SDK is connecting to the Kindly service. | | `connected` | `case connected` | The SDK is connected and ready. | | `disconnected` | `case disconnected` | The connection was lost or intentionally closed. | | `failed` | `case failed` | The connection attempt failed. | | `conversationEnded` | `case conversationEnded` | The conversation has ended. | | `closing` | `case closing` | The connection is in the process of closing. | ## KindlyEventDetail `enum` ```swift public enum KindlyEventDetail ``` Event details that can be associated with different event types | Member | Declaration | Description | | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | | `load(settings:)` | `case load(settings: KindlyEventSettings)` | Settings loaded event | | `message(newMessage:chatLog:)` | `case message(newMessage: KindlyEventMessage, chatLog: [KindlyEventMessage])` | Message event with new message and chat log | | `buttonClick(button:buttonType:chatLog:lastMessage:)` | `case buttonClick(button: KindlyEventButton, buttonType: String, chatLog: [KindlyEventMessage], lastMessage: KindlyEventMessage)` | Button click event | | `ui(action:)` | `case ui(action: KindlyEventUIAction)` | UI action event | | `globalIcon(action:)` | `case globalIcon(action: KindlyEventGlobalIcon)` | Global icon event | | `state(state:)` | `case state(state: KindlyEventState)` | State change event | ## KindlyEventExchangeType `enum` ```swift public enum KindlyEventExchangeType: String, CaseIterable ``` Exchange types for events | Member | Declaration | Description | | ---------------- | ----------------------------------------- | ----------- | | `dialogue` | `case dialogue` | | | `fallback` | `case fallback` | | | `greeting` | `case greeting` | | | `systemDialogue` | `case systemDialogue = "system_dialogue"` | | | `userSays` | `case userSays = "user_says"` | | ## KindlyEventMessageSender `enum` ```swift public enum KindlyEventMessageSender: String, CaseIterable ``` Message sender types for events | Member | Declaration | Description | | --------- | -------------------------- | ----------- | | `agent` | `case agent = "AGENT"` | | | `bot` | `case bot = "BOT"` | | | `system` | `case system = "SYSTEM"` | | | `user` | `case user = "USER"` | | | `unknown` | `case unknown = "UNKNOWN"` | | ## KindlyEventType `enum` ```swift public enum KindlyEventType: String, CaseIterable ``` Types of events that can be emitted by the Kindly SDK | Member | Declaration | Description | | ------------- | ----------------------------------------- | --------------------- | | `load` | `case load = "kindly:load"` | Settings loaded event | | `message` | `case message = "kindly:message"` | Message event | | `buttonClick` | `case buttonClick = "kindly:buttonclick"` | Button click event | | `ui` | `case ui = "kindly:ui"` | UI action event | | `globalIcon` | `case globalIcon = "kindly:globalicon"` | Global icon event | | `state` | `case state = "kindly:state"` | State change event | ## KindlyInputType `enum` ```swift public enum KindlyInputType: String ``` Input types supported by form fields in the chat. | Member | Declaration | Description | | -------- | -------------------- | --------------------- | | `email` | `case email` | Email address input. | | `phone` | `case phone = "tel"` | Phone number input. | | `text` | `case text` | Free-form text input. | | `number` | `case number` | Numeric input. | ## KindlyLogger `enum` ```swift public enum KindlyLogger ``` Centralized logging that handles iOS version compatibility internally iOS 14+: Uses internal print overrides with full debugging info (file, line, function) iOS 13: Falls back to native Swift.print | Member | Declaration | Description | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `log(_:_:level:filename:function:line:)` | `public static func log(_ tag: String, _ message: String, level: OSLogType = .default, filename: String = #file, function: String = #function, line: Int = #line)` | Log a message with automatic iOS 14 availability handling **Parameters** - `tag`: The tag/class name for the log - `message`: The message to log - `level`: The log level (default: .default) - `filename`: Source file name (auto-captured) - `function`: Function name (auto-captured) - `line`: Line number (auto-captured) | | `prettyPrintJson(_:)` | `public static func prettyPrintJson(_ json: String) -> String` | Pretty-print a JSON string with indentation. If `json` is not valid JSON the input is returned unchanged — safe to use on any string. Mirrors Android's `Logger.prettyPrintJson(_:)`. Use at log call sites where the message body is a JSON payload you want rendered readably (e.g. socket frames, raw API responses outside the HTTPClient pipeline). Example: `swift KindlyLogger.log("SocketService", "received text:\n\(KindlyLogger.prettyPrintJson(text))") ` | ## KindlyNotificationMode `enum` ```swift public enum KindlyNotificationMode: String ``` How Kindly push notifications are delivered to the app. See `KindlySDK.notificationMode`. | Member | Declaration | Description | | ----------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `automatic` | `case automatic` | Detect it: `.alert` when the app bundles a Notification Service Extension built on the Kindly SDK (a `KindlyNotificationServiceExtension` subclass, or an extension that links Kindly and calls `KindlyPushDecryption`), `.silent` otherwise. The default. | | `alert` | `case alert` | A visible alert that your extension decrypts before it is shown. Set this if you decrypt Kindly pushes in an extension the SDK cannot detect. | | `silent` | `case silent` | A silent push the SDK decrypts inside the app, which then shows its own banner. iOS does not deliver these to an app the user has force-quit. | ## KindlyPushDecryption `enum` ```swift public enum KindlyPushDecryption ``` Decryption helper for Kindly push notification payloads. Designed for use inside a Notification Service Extension. The NSE receives an encrypted push, calls `KindlyPushDecryption.decrypt(userInfo:)`, and overwrites `bestAttemptContent.title` / `.body` with the plaintext before iOS renders the banner. Requires a shared Keychain Access Group entitlement on both the host app and the NSE target so the NSE can read the encryption key+IV that the host app's SDK stored during `/auth/notification_services` registration. | Member | Declaration | Description | | -------------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `isKindlyNotification(_:)` | `public static func isKindlyNotification(_ userInfo: [AnyHashable: Any]) -> Bool` | Whether a push payload comes from Kindly (`notification_source == "KINDLY"`). Needs no `start()`, so it is safe inside an extension and for routing a tap that launched the app. | | `isDecrypted(_:)` | `public static func isDecrypted(_ userInfo: [AnyHashable: Any]) -> Bool` | Whether the content was already rewritten to plaintext by a Notification Service Extension. | | `apply(_:to:)` | `public static func apply(_ payload: DecryptedPayload, to content: UNMutableNotificationContent)` | Writes the plaintext into the notification content and marks it as decrypted, so the SDK inside the app presents it once and never posts a duplicate. The encrypted fields stay in place untouched. | | `decrypt(userInfo:)` | `public static func decrypt(userInfo: [AnyHashable: Any]) -> DecryptedPayload?` | Attempts to decrypt a Kindly push payload. Returns `nil` if any of: - The payload isn't a Kindly notification (no `notification_source: "KINDLY"`) - The required encrypted fields (`chat_id`, `title`, `body`) are missing - The encryption key or IV is not in the keychain (host app hasn't completed `/auth/notification_services` registration yet) - Any field fails to decrypt (wrong key, malformed base64, etc.) In all failure cases the NSE should fall back to whatever placeholder content the backend included in `aps.alert` so iOS still has something to display. | ## KindlyUIActionType `enum` ```swift public enum KindlyUIActionType: String, CaseIterable ``` Types of UI actions that can be performed | Member | Declaration | Description | | ----------------- | ------------------------------------------- | ----------------- | | `openChatBubble` | `case openChatBubble = "open-chatbubble"` | Open chat bubble | | `closeChatBubble` | `case closeChatBubble = "close-chatbubble"` | Close chat bubble | | `endChat` | `case endChat = "end-chat"` | End chat | | `restartChat` | `case restartChat = "restart-chat"` | Restart chat | | `downloadChat` | `case downloadChat = "download-chat"` | Download chat | | `deleteChat` | `case deleteChat = "delete-chat"` | Delete chat | | `changeLanguage` | `case changeLanguage = "change-language"` | Change language | | `showFeedback` | `case showFeedback = "show-feedback"` | Show feedback | | `submitFeedback` | `case submitFeedback = "submit-feedback"` | Submit feedback | | `dismissFeedback` | `case dismissFeedback = "dismiss-feedback"` | Dismiss feedback | ## TypingEventSender `enum` ```swift public enum TypingEventSender ``` Who is typing | Member | Declaration | Description | | ------- | ------------ | --------------- | | `bot` | `case bot` | Bot is typing | | `agent` | `case agent` | Agent is typing | ## TypingEventType `enum` ```swift public enum TypingEventType ``` Types of typing events that can be emitted | Member | Declaration | Description | | --------- | -------------- | ---------------------- | | `started` | `case started` | Someone started typing | | `stopped` | `case stopped` | Someone stopped typing | # Protocols ## KindlyChatClientDelegate `protocol` ```swift public protocol KindlyChatClientDelegate: NSObject ``` A protocol that defines the delegate methods for the KindlyChatClient. | Member | Declaration | Description | | ----------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `didPressButton(chatButton:chatLog:)` | `func didPressButton(chatButton: ExternalChatButton, chatLog: [ExternalChatMessage])` | Called when the chat button is pressed. **Parameters** - `chatButton`: The chat button that was pressed. | | `shouldHandleLink(url:)` | `func shouldHandleLink(url: URL) -> Bool` | 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 that is about to be opened. **Returns** - `true` if the SDK should handle the link, `false` if the host app will handle it. **Default implementation** A default implementation is provided, so conforming types do not have to implement this. | | `shouldHandleNotification(notification:)` | `func shouldHandleNotification(notification: ExternalNotification) -> Bool` | Called for every Kindly push the app process sees in plaintext: a silent push the SDK decrypted, a visible push the SDK decrypted because the app has no Notification Service Extension, or a visible push the extension already decrypted. Fires regardless of app state or active screen, the SDK does not gate this callback. It does not fire inside the extension process (the app is not running there); use `KindlyNotificationServiceExtension.customize(_:payload:)` for that. 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 show nothing. **Parameters** - `notification`: The decrypted notification (id, title, body) plus the raw `userInfo`. **Returns** - `true` if the SDK should handle it, `false` if the host app will handle it. **Default implementation** A default implementation is provided, so conforming types do not have to implement this. | ## Theme `protocol` ```swift public protocol Theme ``` Protocol defining the color theme for the Kindly Chat UI. Implement this protocol to provide a fully custom theme, or use `CustomTheme` for partial overrides. | Member | Declaration | Description | | ----------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------- | | `background` | `var background: UIColor?` | Background color of the chat interface. | | `botMessageBackground` | `var botMessageBackground: UIColor?` | Background color for bot message bubbles. | | `botMessageText` | `var botMessageText: UIColor?` | Text color for bot messages. | | `buttonBackground` | `var buttonBackground: UIColor?` | Background color for buttons. | | `buttonOutline` | `var buttonOutline: UIColor?` | Outline color for buttons. | | `buttonText` | `var buttonText: UIColor?` | Text color for buttons. | | `chatLogElements` | `var chatLogElements: UIColor?` | Color for chat log elements like timestamps and dividers. | | `navBarBackground` | `var navBarBackground: UIColor?` | Background color for the navigation bar (maps to header\_background in API). | | `navBarText` | `var navBarText: UIColor?` | Text color for the navigation bar (maps to header\_text in API). | | `inputBackground` | `var inputBackground: UIColor?` | Background color for the input field. | | `inputText` | `var inputText: UIColor?` | Text color for the input field. | | `userMessageBackground` | `var userMessageBackground: UIColor?` | Background color for user message bubbles. | | `userMessageText` | `var userMessageText: UIColor?` | Text color for user messages. | | `buttonSelectedBackground` | `var buttonSelectedBackground: UIColor?` | Background color for selected/active buttons. | | `defaultShadow` | `var defaultShadow: UIColor?` | Default shadow color used throughout the UI. | | `inputCursor` | `var inputCursor: UIColor?` | Color for the text input cursor. | | `maintenanceHeaderBackground` | `var maintenanceHeaderBackground: UIColor?` | Background color for the maintenance mode header banner. | # Extensions ## DispatchQueue `extension` ```swift extension DispatchQueue ``` | Member | Declaration | Description | | ----------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `_promises` | `static var _promises: DispatchQueue?` | Backing storage for `DispatchQueue.promises`. Lazy-initialized on first read. Mutable so consumers can swap in a custom queue (e.g. main) for the SDK-wide default. | | `promises` | `static var promises: DispatchQueue` | Default dispatch queue used by `Promise.then` / `.catch` / `.always` when the caller does not pass `on:`. **Currently a background, concurrent queue at QoS `.background`** — chosen historically to keep promise plumbing off the main thread. This means any callback that touches UIKit, `@Published` properties, or other main-thread-only state must opt back in via `.then(on: .main) { … }` (or be wrapped at the call site, as `closeChat()` does). **Note** The doc comment historically said "main if a queue is not specified", but the implementation defaults to background. The comment is kept for backwards-compat reading; trust the code. | ## Notification.Name `extension` ```swift extension Notification.Name ``` | Member | Declaration | Description | | ---------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `kindlyThemeDidChange` | `static let kindlyThemeDidChange = Notification.Name("kindlyThemeDidChange")` | Posted by `ThemeManager` whenever the active theme changes (user theme set/cleared, or API theme loaded). Observers should re-apply theme-derived colors on the main thread. | # Type Aliases ## AuthCredentialsCallback `typealias` ```swift public typealias AuthCredentialsCallback = (_ chatId: String, _ promise: Promise) -> Void ``` Callback for providing full authentication credentials to the SDK. The SDK calls this with the current `chatId` and a `Promise` you fulfill with a `KindlyAuthCredentials`. Everything `AuthTokenCallback` can express, this can too — a single-JWT integration just fills in `idToken` and leaves the rest at their defaults. ## AuthTokenCallback `typealias` ```swift public typealias AuthTokenCallback = (_ chatId: String, _ promise: Promise) -> Void ``` Callback for providing an authentication token to the SDK. The SDK calls this with the current `chatId` and a `Promise` that you must fulfill with a valid JWT token string. Use `AuthCredentialsCallback` instead when your identity provider hands you more than a single JWT — a companion access token, an issuer, or an expiry the SDK cannot read off the token. ## KindlySDK `typealias` ```swift public typealias KindlySDK = KindlyChatClient ```