Structures

CoreSDKConfig

struct

public struct CoreSDKConfig: Loggable

Setup the Kindly SDK with your configuration.

Parameters

botKey: The key for your application. See the Kindly API docs for more.

environment: Select the ServerEnvironment the API should target. Default value is production.

CustomTheme

struct

public struct CustomTheme: Theme

A custom theme for the Kindly Chat UI. Only non-nil colors override the default or API theme. Pass an instance to KindlySDK.setCustomTheme(_:) to apply.

Member	Declaration	Description
background	public var background: UIColor?
botMessageBackground	public var botMessageBackground: UIColor?
botMessageText	public var botMessageText: UIColor?
buttonBackground	public var buttonBackground: UIColor?
buttonOutline	public var buttonOutline: UIColor?
buttonText	public var buttonText: UIColor?
chatLogElements	public var chatLogElements: UIColor?
navBarBackground	public var navBarBackground: UIColor?
navBarText	public var navBarText: UIColor?
inputBackground	public var inputBackground: UIColor?
inputText	public var inputText: UIColor?
userMessageBackground	public var userMessageBackground: UIColor?
userMessageText	public var userMessageText: UIColor?
buttonSelectedBackground	public var buttonSelectedBackground: UIColor?
defaultShadow	public var defaultShadow: UIColor?
inputCursor	public var inputCursor: UIColor?
maintenanceHeaderBackground	public var maintenanceHeaderBackground: UIColor?
init(background:botMessageBackground:botMessageText:buttonBackground:buttonOutline:buttonText:chatLogElements:navBarBackground:navBarText:inputBackground:inputText:userMessageBackground:userMessageText:buttonSelectedBackground:defaultShadow:inputCursor:maintenanceHeaderBackground:)	public init( // API-defined colors background: UIColor? = nil, botMessageBackground: UIColor? = nil, botMessageText: UIColor? = nil, buttonBackground: UIColor? = nil, buttonOutline: UIColor? = nil, buttonText: UIColor? = nil, chatLogElements: UIColor? = nil, navBarBackground: UIColor? = nil, navBarText: UIColor? = nil, inputBackground: UIColor? = nil, inputText: UIColor? = nil, userMessageBackground: UIColor? = nil, userMessageText: UIColor? = nil, // Manually defined colors buttonSelectedBackground: UIColor? = nil, defaultShadow: UIColor? = nil, inputCursor: UIColor? = nil, maintenanceHeaderBackground: UIColor? = nil )

ExternalChatButton

struct

public struct ExternalChatButton

A chat button passed to the delegate when a user interacts with buttons in the chat.

ExternalChatMessage

struct

public struct ExternalChatMessage: Hashable, Identifiable, Comparable

ChatMessage represents both sent and received messages.

Messages supports a variety of different content. For example images, buttons and attachments.

Member	Declaration	Description
id	public let id: String
<(_:_:)	public static func < (lhs: ExternalChatMessage, rhs: ExternalChatMessage) -> Bool
==(_:_:)	public static func == (lhs: ExternalChatMessage, rhs: ExternalChatMessage) -> Bool
hash(into:)	public func hash(into hasher: inout Hasher)
toDictionary()	public func toDictionary() -> [String: Any]	Convert to dictionary for event emission

ExternalNotification

struct

public struct ExternalNotification

A decrypted Kindly notification passed to the delegate's shouldHandleNotification(notification:).

Forwarded to the host app for every Kindly push the app process sees in plaintext (silent pushes the SDK decrypted, visible pushes decrypted by the SDK or already by the Notification Service Extension), regardless of app state or which screen is on top. Use the host callback to take over the presentation of the notification; otherwise the SDK presents it itself.

Member	Declaration	Description
id	public let id: String	Decrypted message id (from the encrypted chat_id field).
title	public let title: String	Decrypted title.
body	public let body: String	Decrypted body.
userInfo	public let userInfo: [AnyHashable: Any]	The original APNs userInfo dictionary, including aps, notification_source, and any extra fields the backend attached. Provided so the host can read fields the SDK does not surface.

KindlyAuthCredentials

struct

public struct KindlyAuthCredentials

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 AuthTokenCallback and never touch this type at all.

Member	Declaration	Description
idToken	public let idToken: String?	The OIDC id token, when your provider issues one. Optional. This is the preferred bearer, not a mandatory field — plenty of providers hand back only an access token, and an opaque introspection bearer has no id token at all. What the SDK actually requires is that at least one of idToken / accessToken is set; see bearerToken.
accessToken	public let accessToken: String?	The access token, when your provider issues one. Its role depends on what else is set. Alongside an idToken it is the dual-token companion and is sent as X-Access-Token. On its own it becomes the bearer — see bearerToken. The Kindly JWT strategy ignores the companion form.
issuer	public let issuer: String?	The identity provider this credential came from. Sent as X-Auth-Issuer. Required when the bot has more than one provider configured, and when idToken is opaque — the backend cannot read an iss claim out of a token it cannot decode, so without this it has no way to pick a provider.
expiresAt	public let expiresAt: Date?	When these credentials stop being valid, if you know. Worth supplying when idToken is opaque: the SDK reads exp out of a JWT itself, but an opaque token tells it nothing, and credentials with no known expiry are treated as non-expiring and never proactively refreshed. This is a hint, not an override. The SDK refreshes on whichever comes first out of this, the exp claim it can read, and the expiry the backend reports.
init(idToken:accessToken:issuer:expiresAt:)	public init( idToken: String? = nil, accessToken: String? = nil, issuer: String? = nil, expiresAt: Date? = nil )	Set at least one of idToken / accessToken. Credentials carrying neither cannot authenticate anything — the SDK reports them as an empty result from your callback and the chat stays anonymous. Parameters - idToken: The OIDC id token, if your provider issues one. - accessToken: The access token, if your provider issues one. - issuer: The provider's issuer. Required for opaque tokens and multi-provider bots. - expiresAt: When the credentials expire, if known.
init(idToken:accessToken:issuer:expiresAtUnixSeconds:)	public init( idToken: String? = nil, accessToken: String? = nil, issuer: String? = nil, expiresAtUnixSeconds: Int? )	Convenience for providers that report expiry the way OAuth does — Unix seconds. Parameters - expiresAtUnixSeconds: Expiry as seconds since 1970, exactly as an exp claim or an introspection response carries it.
bearerToken	var bearerToken: String?	The token actually sent as Authorization: Bearer, or nil 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.
hasToken	var hasToken: Bool	true when these credentials carry something usable.
companionAccessToken	var companionAccessToken: String?	The access token in its companion role — the value that will be sent as X-Access-Token, or nil 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 nil 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.

KindlyEvent

struct

public struct KindlyEvent

Main event structure emitted by the Kindly SDK

Member	Declaration	Description
type	public let type: KindlyEventType	The type of event
detail	public let detail: KindlyEventDetail	The event details
timestamp	public let timestamp: Date	Timestamp when the event was emitted
init(type:detail:)	public init(type: KindlyEventType, detail: KindlyEventDetail)

KindlyEventAttachment

struct

public struct KindlyEventAttachment

Attachment data for events

Member	Declaration	Description
id	public let id: String	Attachment ID
name	public let name: String	Attachment name
format	public let format: String	Attachment format
status	public let status: String	Attachment status
sender	public let sender: String	Attachment sender
storagePath	public let storagePath: String	Storage path
init(id:name:format:status:sender:storagePath:)	public init( id: String, name: String, format: String, status: String, sender: String, storagePath: String )

KindlyEventButton

struct

public struct KindlyEventButton

Button data for events

Member	Declaration	Description
id	public let id: String?	Button ID
type	public let type: String	Button type
label	public let label: String	Button label text
value	public let value: String?	Button value
index	public let index: Int?	Button index
hasBeenSelected	public let hasBeenSelected: Bool	Whether the button has been selected
context	public let context: [String: Any]?	Button context data
init(id:type:label:value:index:hasBeenSelected:context:)	public init( id: String? = nil, type: String, label: String, value: String? = nil, index: Int? = nil, hasBeenSelected: Bool = false, context: [String: Any]? = nil )

KindlyEventGlobalIcon

struct

public struct KindlyEventGlobalIcon

Global icon action data for events

Member	Declaration	Description
type	public let type: String	Action type
source	public let source: String	Action source
value	public let value: [String: Any]?	Additional value data
init(type:source:value:)	public init(type: String, source: String = "user", value: [String: Any]? = nil)

KindlyEventImage

struct

public struct KindlyEventImage

Image data for events

Member	Declaration	Description
url	public let url: String	Image URL
altText	public let altText: String?	Alt text for accessibility
id	public let id: String?	Image ID
init(url:altText:id:)	public init(url: String, altText: String? = nil, id: String? = nil)

KindlyEventLanguage

struct

public struct KindlyEventLanguage

Language data for events

Member	Declaration	Description
code	public let code: String	Language code (e.g., "en", "es")
name	public let name: String	Language name (e.g., "English", "Spanish")
isDefault	public let isDefault: Bool	Whether this is the default language
init(code:name:isDefault:)	public init(code: String, name: String, isDefault: Bool = false)

KindlyEventMessage

struct

public struct KindlyEventMessage

Message data for events

Member	Declaration	Description
id	public let id: String	Message ID
chatId	public let chatId: String?	The chat/session ID this message belongs to (server chat_id)
text	public let text: String?	Message text content
sender	public let sender: KindlyEventMessageSender	Message sender type
created	public let created: Date?	Message creation timestamp
isFromUser	public let isFromUser: Bool	Whether the message is from the user
exchangeID	public let exchangeID: String?	Exchange ID if applicable
videoSource	public let videoSource: String?	Video source URL if applicable
exchangeType	public let exchangeType: KindlyEventExchangeType?	Exchange type if applicable
buttons	public let buttons: [KindlyEventButton]	Message buttons if any
images	public let images: [KindlyEventImage]	Message images if any
attachments	public let attachments: [KindlyEventAttachment]	Message attachments if any
init(id:chatId:text:sender:created:isFromUser:exchangeID:videoSource:exchangeType:buttons:images:attachments:)	public init( id: String, chatId: String? = nil, text: String? = nil, sender: KindlyEventMessageSender, created: Date? = nil, isFromUser: Bool, exchangeID: String? = nil, videoSource: String? = nil, exchangeType: KindlyEventExchangeType? = nil, buttons: [KindlyEventButton] = [], images: [KindlyEventImage] = [], attachments: [KindlyEventAttachment] = [] )

KindlyEventSettings

struct

public struct KindlyEventSettings

Settings data for load events

Member	Declaration	Description
name	public let name: String	Settings name
id	public let id: String	Settings ID
languages	public let languages: [KindlyEventLanguage]	Available languages
style	public let style: KindlyEventStyle	Style configuration
init(name:id:languages:style:)	public init(name: String, id: String, languages: [KindlyEventLanguage], style: KindlyEventStyle)

KindlyEventState

struct

public struct KindlyEventState

State data for events

Member	Declaration	Description
isChatDisplayed	public let isChatDisplayed: Bool	Whether the chat is currently displayed
isStarted	public let isStarted: Bool	Whether the SDK has been started
isSocketConnected	public let isSocketConnected: Bool	Whether the socket is connected to Pusher
isConnected	public let isConnected: Bool	Whether the SDK is fully connected (started + socket connected)
connectionState	public let connectionState: String	Current connection state as string
init(isChatDisplayed:isStarted:isSocketConnected:isConnected:connectionState:)	public init( isChatDisplayed: Bool, isStarted: Bool, isSocketConnected: Bool, isConnected: Bool, connectionState: String )

KindlyEventStyle

struct

public struct KindlyEventStyle

Style data for events

Member	Declaration	Description
background	public let background: String?	Background color in hex format
buttonBackground	public let buttonBackground: String?	Button background color in hex format
buttonText	public let buttonText: String?	Button text color in hex format
headerBackground	public let headerBackground: String?	Header background color in hex format
headerText	public let headerText: String?	Header text color in hex format
inputBackground	public let inputBackground: String?	Input background color in hex format
inputText	public let inputText: String?	Input text color in hex format
userMessageBackground	public let userMessageBackground: String?	User message background color in hex format
userMessageTextColor	public let userMessageTextColor: String?	User message text color in hex format
botMessageBackground	public let botMessageBackground: String?	Bot message background color in hex format
botMessageTextColor	public let botMessageTextColor: String?	Bot message text color in hex format
init(background:buttonBackground:buttonText:headerBackground:headerText:inputBackground:inputText:userMessageBackground:userMessageTextColor:botMessageBackground:botMessageTextColor:)	public init( background: String? = nil, buttonBackground: String? = nil, buttonText: String? = nil, headerBackground: String? = nil, headerText: String? = nil, inputBackground: String? = nil, inputText: String? = nil, userMessageBackground: String? = nil, userMessageTextColor: String? = nil, botMessageBackground: String? = nil, botMessageTextColor: String? = nil )

KindlyEventUIAction

struct

public struct KindlyEventUIAction

UI action data for events

Member	Declaration	Description
type	public let type: KindlyUIActionType	Action type
source	public let source: String	Action source (user or programmatic)
chatId	public let chatId: String	Chat ID
value	public let value: [String: Any]?	Additional value data
feedbackType	public let feedbackType: String?	Feedback type if applicable
feedbackValue	public let feedbackValue: [String: Any]?	Feedback value if applicable
languageCode	public let languageCode: String?	Language code for language change events
languageName	public let languageName: String?	Language name for language change events
previousLanguageCode	public let previousLanguageCode: String?	Previous language code for language change events
previousLanguageName	public let previousLanguageName: String?	Previous language name for language change events
nextPage	public let nextPage: String?	Next page for navigation events
init(type:source:chatId:value:feedbackType:feedbackValue:languageCode:languageName:previousLanguageCode:previousLanguageName:nextPage:)	public init( type: KindlyUIActionType, source: String = "user", chatId: String, value: [String: Any]? = nil, feedbackType: String? = nil, feedbackValue: [String: Any]? = nil, languageCode: String? = nil, languageName: String? = nil, previousLanguageCode: String? = nil, previousLanguageName: String? = nil, nextPage: String? = nil )

KindlyPushDecryption.DecryptedPayload

struct

public struct DecryptedPayload

Plaintext fields decrypted from a Kindly push payload.

Member	Declaration	Description
chatId	public let chatId: String
title	public let title: String
body	public let body: String
init(chatId:title:body:)	public init(chatId: String, title: String, body: String)

KindlySDKConfig

struct

public struct KindlySDKConfig: Loggable

Setup the Kindly SDK with your configuration.

Parameters

botKey: The key for your application. See the Kindly API docs for more.

environment: Select the ServerEnvironment the API should target. Default value is production.

Member	Declaration	Description
getAuthToken	public var getAuthToken: AuthTokenCallback?	Optional callback invoked when the SDK needs an authentication token. Set this to provide JWT-based authentication for the chat session. Ignored while getAuthCredentials is also set — that one wins.
getAuthCredentials	public var getAuthCredentials: AuthCredentialsCallback?	Optional callback invoked when the SDK needs authentication credentials. Use this instead of getAuthToken when your identity provider gives you more than a single JWT — a companion access token, an issuer to verify against, or an expiry the SDK cannot read off the token itself. Takes precedence over getAuthToken when both are set.
allowCameraAccess	public var allowCameraAccess: Bool = true	Whether the SDK is allowed to access the device camera for attachments. Defaults to true.
allowPhotoLibraryAccess	public var allowPhotoLibraryAccess: Bool = true	Whether the SDK is allowed to access the photo library for attachments. Defaults to true.
form	public var form: FormConfig = FormConfig()	Form-related configuration options.

KindlySDKConfig.FormConfig

struct

public struct FormConfig

Configuration for form behavior within the chat.

KindlyTheme

struct

public struct KindlyTheme: Theme

Default theme.

Contains fallback values.

Member	Declaration	Description
init()	public init()
background	public var background: UIColor?
botMessageBackground	public var botMessageBackground: UIColor?
botMessageText	public var botMessageText: UIColor?
buttonBackground	public var buttonBackground: UIColor?
buttonOutline	public var buttonOutline: UIColor?
buttonText	public var buttonText: UIColor?
chatLogElements	public var chatLogElements: UIColor?
navBarBackground	public var navBarBackground: UIColor?
navBarText	public var navBarText: UIColor?
inputBackground	public var inputBackground: UIColor?
inputText	public var inputText: UIColor?
userMessageBackground	public var userMessageBackground: UIColor?
userMessageText	public var userMessageText: UIColor?
buttonSelectedBackground	public var buttonSelectedBackground: UIColor?
defaultShadow	public var defaultShadow: UIColor?
inputCursor	public var inputCursor: UIColor?
maintenanceHeaderBackground	public var maintenanceHeaderBackground: UIColor?

RuntimeEnvironmentOverride

struct

public struct RuntimeEnvironmentOverride: Codable

Member	Declaration	Description
environment	public let environment: String
customConfig	public let customConfig: CustomConfig?
init(environment:customConfig:)	public init(environment: String, customConfig: CustomConfig? = nil)
productionDefaults	public static let productionDefaults = CustomConfig( apiBaseURL: "https://bot.kindly.ai", settingsBaseURL: "https://chat.kindlycdn.com", webviewBaseURL: "https://chat.kindlycdn.com/sdk", otlpURL: "https://otlp.kindly.ai/v1/metrics", pusherKey: "0d15baa2a7308d71e79d" )
developmentDefaults	public static let developmentDefaults = CustomConfig( apiBaseURL: "https://bot-dev.kindly.ai", settingsBaseURL: "https://chat-dev.kindlycdn.com", webviewBaseURL: "https://chat.kindlycdn.com/sdk", otlpURL: "https://otlp.dev.kindly.ai/v1/metrics", pusherKey: "f65c531eb076639447ac" )
customBuildtimeDefaults	public static let customBuildtimeDefaults = CustomConfig( apiBaseURL: "https://pattestwithalexy.eu.ngrok.io", settingsBaseURL: "https://chat-dev.kindlycdn.com", webviewBaseURL: "https://chat.kindlycdn.com/sdk", otlpURL: "https://otlp.dev.kindly.ai/v1/metrics", pusherKey: "9201eea9b3265d1b2f8f" )
compileTimeEnvironment	public static var compileTimeEnvironment: String
load()	public static func load() -> RuntimeEnvironmentOverride?
save(_:)	public static func save(_ override: RuntimeEnvironmentOverride) -> Bool
clear()	public static func clear()

RuntimeEnvironmentOverride.CustomConfig

struct

public struct CustomConfig: Codable

Member	Declaration	Description
apiBaseURL	public let apiBaseURL: String
settingsBaseURL	public let settingsBaseURL: String
webviewBaseURL	public let webviewBaseURL: String
otlpURL	public let otlpURL: String
pusherKey	public let pusherKey: String
init(apiBaseURL:settingsBaseURL:webviewBaseURL:otlpURL:pusherKey:)	public init( apiBaseURL: String, settingsBaseURL: String, webviewBaseURL: String, otlpURL: String, pusherKey: String )

TypingEvent

struct

public struct TypingEvent

Internal typing event that can be emitted and listened to

Member	Declaration	Description
type	public let type: TypingEventType	The type of typing event
sender	public let sender: TypingEventSender	Who is typing
duration	public let duration: TimeInterval?	Duration in seconds (only relevant for started events)
timestamp	public let timestamp: Date	Timestamp when the event was created
init(type:sender:duration:)	public init(type: TypingEventType, sender: TypingEventSender, duration: TimeInterval? = nil)