iOS SDK

Requirements#

• iOS 15.0+ (finer sheet detents on iOS 16+, with a system fallback below).
• Swift 5.9+.
• Zero third-party dependencies — only Foundation, Swift Concurrency, SwiftUI, and UIKit.

You depend on the RespondoSDK product, which re-exports the cross-platform RespondoCore.

Installation#

Add the package with Swift Package Manager. In Xcode: File → Add Package Dependencies… and enter https://github.com/respondo-app/sdk-ios, or declare it in your own Package.swift, then depend on the RespondoSDK product.

dependencies: [
    .package(url: "https://github.com/respondo-app/sdk-ios", from: "0.1.0")
],
targets: [
    .target(
        name: "MyApp",
        dependencies: [
            .product(name: "RespondoSDK", package: "sdk-ios")
        ]
    )
]

Then import it in code:

import RespondoSDK

Initialize#

Initialize once at launch, then call Respondo.open() anywhere. The lifecycle method is initialize (the word init is reserved by the language).

import SwiftUI
import RespondoSDK

@main
struct MyApp: App {
    init() {
        Respondo.initialize(
            RespondoConfig(
                agentId: "<agent-uuid>",
                channelId: "<channel-uuid>"
                // baseUrl nil -> https://api.respondo.ai
            )
        )
    }

    var body: some Scene {
        WindowGroup {
            Button("Support") { Respondo.open() }
        }
    }
}

The Respondo facade is thread-safe. Calls made right after initialize are queued and applied once the async init completes.

Identify users#

By default every visitor is anonymous. On first launch the SDK generates a stable visitor_id and keeps it in the keychain, so a returning user finds their conversation again. There is no API key to embed — each conversation is protected by a per-conversation session token the backend mints and slides forward on every message, so an anonymous visitor never has to re-authenticate.

Call identify once your user is signed in. This attaches their real identity so their history follows them across devices and reinstalls, and their name and email show up next to the conversation in your inbox instead of an anonymous visitor.

The userHash is a signature your backend computes from the agent's identity_secret — HMAC-SHA256(secret, userId) (or the email when there is no userId), encoded as lowercase hex. The secret proves the identity is genuine, so it must live only on your backend and is never shipped in the app. See the Identity verification page for the full formula and server-side examples.

// The userHash comes from your backend (HMAC-SHA256 over the userId) —
// never compute it in the app.
Respondo.identify(
    RespondoIdentity(
        userId: session.userId,
        email: session.email,
        name: session.fullName,
        userHash: session.respondoUserHash
    )
)

// On logout: revoke the session and start a fresh anonymous visitor.
Respondo.reset()

If the hash is missing or wrong, nothing throws: the backend silently keeps the visitor anonymous, the chat keeps working, and you simply lose the cross-device link until a valid hash is supplied. Verification only runs when the agent has an identity_secret set — leave it empty during development and userId / email are accepted as-is.

Observables & delegate#

Read state as synchronous getters, reactive AsyncStreams, or through a RespondoDelegate. Streams and delegate callbacks arrive on the main actor.

// Reactive stream of unread counts.
Task {
    for await count in Respondo.unreadCountStream {
        updateBadge(count)
    }
}

// Delegate for badges and deep-link fallbacks.
final class SupportCoordinator: RespondoDelegate {
    init() { Respondo.delegate = self }
    func respondoUnreadChanged(_ count: Int) {
        UIApplication.shared.applicationIconBadgeNumber = count
    }
}

Next steps#

Wire up Push notifications and Identity verification. The UIKit wrapper RespondoChatViewController, the full delegate surface, and troubleshooting are covered in the iOS SDK getting-started guide; the SDK sources are public on GitHub.