Initialization

Initialize the SDK

The first step to use the Kindly SDK is to initialize it with your bot key and market slug:

KindlySDK.start(botKey: "YOUR_BOT_KEY", market: "YOUR_MARKET")

You can also specify a language code (defaults to "en" if not provided):

KindlySDK.start(botKey: "YOUR_BOT_KEY", languageCode: "en", market: "YOUR_MARKET")

You can also provide an authentication callback if your bot requires authentication:

KindlySDK.start(botKey: "YOUR_BOT_KEY", languageCode: "en", market: "YOUR_MARKET") { chatId, promise in
    // Generate JWT token
    // On success, call
    promise.fulfill("JWT_TOKEN")
    // On error
    promise.reject(ERROR)
}

Markets (per-location settings)

Bots can serve their UI, greeting, and responses per market. The market slug is required — pass the market configured for your bot:

KindlySDK.start(botKey: "YOUR_BOT_KEY", languageCode: "en", market: "eu")

The SDK loads that market's settings and tells the backend which market was picked (so greeting/responses are localized to it). 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). See the Markets guide for details.

Change Language at Runtime

You can change the language after initialization using:

KindlySDK.setLanguage("lt")  // Change to Lithuanian

This method will:

Call the language switch API

Update the cached settings

Refresh UI translations

Notify all UI components of the language change

The language setting will persist across chat sessions until explicitly changed.

Bot Switching and Reinitialization

The SDK intelligently handles bot switching and reinitialization scenarios when you call start() multiple times with different parameters.

Automatic Bot Key Switching

When you call start() with a different bot key, the SDK automatically:

Detects the change: Compares the new bot key with the current one

Performs cleanup: Calls KindlyChatClient.shared.disconnect(kickUser: false) internally to end the current session

Resets state: Clears SDK initialization flags and session data

Reinitializes: Connects to the new bot seamlessly

// First initialization
KindlySDK.start(botKey: "bot-key-1", market: "YOUR_MARKET")
KindlySDK.displayChat()

// Later, switch to different bot - automatic cleanup happens
KindlySDK.start(botKey: "bot-key-2", market: "YOUR_MARKET")  // SDK handles cleanup internally
KindlySDK.displayChat()

Connection State Handling

When the SDK is disconnected (e.g., after calling endChat()), calling start() with the same bot key will reconnect:

KindlySDK.start(botKey: "YOUR_BOT_KEY", market: "YOUR_MARKET")
KindlySDK.displayChat()

// Later, end the chat
KindlySDK.endChat()

// Reconnect with same bot key - allowed reconnection
KindlySDK.start(botKey: "YOUR_BOT_KEY", market: "YOUR_MARKET")  // Reconnects instead of skipping
KindlySDK.displayChat()

Skipping Duplicate Initialization

The SDK skips initialization only when all conditions are met:

Same bot key

Still connected (not disconnected)

KindlySDK.start(botKey: "YOUR_BOT_KEY", market: "YOUR_MARKET")
// This second call will be skipped - no changes needed
KindlySDK.start(botKey: "YOUR_BOT_KEY", market: "YOUR_MARKET")

Best Practices for Bot Switching

Option 1: Automatic Switching (Recommended)

// SDK handles cleanup automatically
KindlySDK.start(botKey: "new-bot-key", market: "YOUR_MARKET")
KindlySDK.displayChat()

Option 2: Explicit End-then-Start

// Explicit control over the lifecycle
KindlySDK.endChat().then(on: DispatchQueue.main) { _ in
    KindlySDK.start(botKey: "new-bot-key", market: "YOUR_MARKET")
    KindlySDK.displayChat()
}

Both approaches work identically - choose based on your preference for explicit vs automatic lifecycle management.

For more details on authentication, see Authentication.