Chat SDK for iOS and Android

Put your Deskwoot live chat into your own iOS or Android app as a native screen. Your team and your AI bot answer it in Deskwoot, like the chat on your website.

On this page

What the SDK is

The SDK puts the chat of your website inbox into your app as a native screen. It is drawn with UIKit on iOS and with Android's own views on Android, not loaded as a web page; only the text of a help article shows in a system web view. Visitors write to your team and your AI bot, search your help center and read the replies right in your app.

It is the same chat as on your website. It reads the same inbox settings (brand color, texts, team, AI bot, help center) and shows the look you picked for the inbox: Plain, Welcome or Direct. It speaks the 10 visitor languages of the website chat.

Conversations from the app land in that inbox, where your team answers them as usual.

Requirements

PlatformRuns onBuilds with
iOSiOS 15 or later, iPhone and iPadXcode 15 or later (Swift 5.9)
AndroidAndroid 5.0 (API 21) or latercompileSdk 34 or later, Android Gradle Plugin 8 or later, Kotlin 1.9 or later, or Java. Apps built with Views and apps built with Jetpack Compose both work.

You also need a Deskwoot inbox of the type Live Chat (the website chat). The SDK uses its widget token.

Install

iOS: in Xcode choose File → Add Package Dependencies, enter https://github.com/Deskwoot/deskwoot-ios and add the Deskwoot library to your app target. Or add the package to your Package.swift:

iOS (Swift)
dependencies: [
    .package(url: "https://github.com/Deskwoot/deskwoot-ios", from: "1.0.0"),
],
targets: [
    .target(
        name: "YourApp",
        dependencies: [.product(name: "Deskwoot", package: "deskwoot-ios")]
    ),
]

Android: the SDK is on Maven Central. Add it to your app module's build.gradle.kts:

Android (Kotlin)
dependencies {
    implementation("com.deskwoot:deskwoot-android:1.0.0")
}

The iOS package ships as source and builds with your Xcode. The Android library works from Kotlin and from Java.

Set up

The SDK needs the widget token of a Live Chat inbox. In Deskwoot, open Settings → Inboxes → your inbox → Chat in your iOS and Android app: the token is at the top, ready to copy.

Call setup once with that token, as early as you like: in application(_:didFinishLaunchingWithOptions:) on iOS, in Application.onCreate on Android. It does no disk or network work on the main thread, and a second call with the same token does nothing.

iOS (Swift)
import Deskwoot
import UIKit

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        Deskwoot.setup(widgetToken: "YOUR_WIDGET_TOKEN")
        return true
    }
}
Android (Kotlin)
import android.app.Application
import com.deskwoot.sdk.Deskwoot

class App : Application() {
    override fun onCreate() {
        super.onCreate()
        Deskwoot.setup(this, "YOUR_WIDGET_TOKEN")
    }
}

On iOS, call the SDK from the main thread (a call from another thread is logged and runs on the main thread a moment later). On Android, every call works from any thread.

One widgetToken = one inbox. With your website's token, the app's chats land in the same inbox as your website chats. With the token of a second live chat inbox, you keep them apart.

Open the chat

Open the chat from your own help button. Every call works right after setup, also before the inbox's settings have loaded.

iOSAndroidWhat opens
present()present(activity)The start page.
presentConversation()presentConversation(activity)The visitor's newest running conversation, or a new one.
presentNewConversation(text:)presentNewConversation(activity, text)A new conversation with your text in the message field. The visitor can edit it and sends it themselves; the SDK sends nothing for them.
presentHelpCenter()presentHelpCenter(activity)The help center, or the start page when the inbox has none.
dismiss()dismiss()Closes the chat if it is open.

On iOS the chat opens as a sheet over your app's top screen; pass from: to choose the screen. On Android it opens as its own Activity; pass the Activity you call from, so the chat stays in your app's task and takes its light or dark mode from it.

iOS (Swift)
// For example behind your "Help" button
Deskwoot.present()                       // the start page
Deskwoot.present(from: self)             // the same, over this screen
Deskwoot.presentConversation()
Deskwoot.presentNewConversation(text: "I have a question about order 1042")
Deskwoot.presentHelpCenter()
Deskwoot.dismiss()
Android (Kotlin)
// In an Activity, for example behind your "Help" button
Deskwoot.present(this)                   // the start page
Deskwoot.presentConversation(this)
Deskwoot.presentNewConversation(this, "I have a question about order 1042")
Deskwoot.presentHelpCenter(this)
Deskwoot.dismiss()

The launcher button

setLauncherVisible(true) shows the round chat button of the website widget over your app's content: in your brand color, on the side set for the inbox, with a badge for unread replies. A tap opens the chat. It is hidden by default, because most apps open the chat from their own button.

A reply while the chat is closed

When a reply arrives while your app is open and the chat is closed, a small card slides up at the bottom of your app with the writer's picture, their name and 2 lines of the reply. A tap opens that conversation. The card needs no permission and never shows over the chat itself. It is on by default; inAppNotificationsEnabled = false turns it off.

iOS (Swift)
Deskwoot.setLauncherVisible(true)            // show the round chat button
Deskwoot.inAppNotificationsEnabled = false   // no card for new replies
Android (Kotlin)
Deskwoot.setLauncherVisible(true)            // show the round chat button
Deskwoot.inAppNotificationsEnabled = false   // no card for new replies

Signed in users

Without identify, a visitor chats anonymously and the conversation stays on that phone. When your user is signed in, identify them: their conversations then follow them to every device and to your website chat on the same inbox, and your team sees who they are.

Deskwoot trusts a user only with identifierHash: the HMAC SHA256 of identifier with your inbox's signing secret, as hex. Your server computes it and hands it to the app. It is the same signature as on the website, with the optional email, name and signed attributes: Identity verification on the widget page.

iOS (Swift)
// After your own sign in, with the hash from your server
Deskwoot.identify(DeskwootUser(
    identifier: user.id,
    identifierHash: hashFromYourServer,
    email: user.email,   // optional
    name: user.name      // optional
))

// When the user signs out of your app
Deskwoot.logout()
Android (Kotlin)
// After your own sign in, with the hash from your server
Deskwoot.identify(
    DeskwootUser(
        identifier = user.id,
        identifierHash = hashFromYourServer,
        email = user.email,   // optional
        name = user.name,     // optional
    ),
)

// When the user signs out of your app
Deskwoot.logout()

Call identify at every start of your app as soon as it knows its user, and again after a sign in. On Android, when your app has the user and the hash stored, call it in Application.onCreate right after setup: Android can start your app for a tap on a notification without opening any of your screens. Call logout() when the user signs out, also at a start where your app finds their session gone, and only then: the SDK deletes what it kept about the visitor, also the chat of one who never signed in, and the next chat starts as a new anonymous visitor.

Never put the signing secret into your app. Anyone who unpacks the app could read it and chat as any of your users.

Unread count

unreadCount is the number of replies the visitor has not read yet, across their conversations, for example for a badge on your help button. Read it once for the first value: unreadCountDidChange on iOS and an UnreadCountListener on Android report only changes.

iOS (Swift)
let count = Deskwoot.unreadCount

NotificationCenter.default.addObserver(
    forName: Deskwoot.unreadCountDidChange, object: nil, queue: .main
) { note in
    let count = note.userInfo?["count"] as? Int ?? 0
    // show count on your help button
}
Android (Kotlin)
val count = Deskwoot.unreadCount

val listener = UnreadCountListener { count ->
    badge.text = count.toString()
}
Deskwoot.addUnreadCountListener(listener)
// when the screen goes away
Deskwoot.removeUnreadCountListener(listener)

Language and theme

The chat speaks the inbox's fixed language when it has one. Otherwise it follows your app: on iOS the language your app runs in, on Android the phone's language or the one the user picked for your app. Set language to a language tag such as "de" or "pt-BR" to choose it yourself in place of the app's; it holds for as long as the app runs and is never stored. A language the chat does not know becomes English.

The chat knows the 10 visitor languages of the website chat: English, German (with the du or Sie the inbox uses), Spanish, French, Brazilian Portuguese, Arabic (right to left), Hindi, Italian, Japanese and Simplified Chinese. Every text and every screen reader label is in that one language.

Colors come from the inbox's brand color, in a light and a dark variant. By default the chat follows your app: light or dark like the screen it opens over. theme sets it to system (the default), light, dark or inbox (the inbox's own setting, as on the website).

iOS (Swift)
Deskwoot.language = "de"   // nil: the inbox's language, else your app's
Deskwoot.theme = .system   // .system (default), .light, .dark or .inbox
Android (Kotlin)
Deskwoot.language = "de"                 // null: the inbox's language, else your app's
Deskwoot.theme = Deskwoot.Theme.SYSTEM   // SYSTEM (default), LIGHT, DARK or INBOX

Text uses the system font and grows with the phone's text size. On Android, if your app keeps only some languages (localeFilters), the chat can only use those.

Push notifications

Without push, a reply reaches the visitor while your app is open: in the unread count, on the card and on the launcher badge. With push, it also reaches them while the app is closed. The SDK never talks to Apple or Google itself and brings no Firebase: your app gets its device token the way it already does and hands it to the SDK. It never asks for the notification permission either; your app does that when it suits.

In Deskwoot

  1. Open Settings → Inboxes → your inbox → Chat in your iOS and Android app for the inbox whose token your app uses.
  2. For iOS: create an APNs auth key in your Apple developer account under Keys. Paste it into APNs auth key (.p8) or upload the file, then enter its Key ID, your Team ID and your app's Bundle ID.
  3. For Android: in Firebase, open Project settings, then Service accounts, and generate a new private key. Paste that file into Service account JSON or upload it.
  4. Click Save under each block. Deskwoot checks the key with Apple or with Google before it keeps it, and the block then says Connected.

In your iOS app

Turn on the Push Notifications capability of your app target. Ask for permission and register with Apple as your app does for its own notifications, then hand the device token to setPushToken on every start. In your notification center delegate, let the SDK take its own notifications:

iOS (Swift)
import Deskwoot
import UIKit
import UserNotifications

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        Deskwoot.setup(widgetToken: "YOUR_WIDGET_TOKEN")
        UNUserNotificationCenter.current().delegate = self
        // Ask for permission when it suits your app, then:
        application.registerForRemoteNotifications()
        return true
    }

    func application(
        _ application: UIApplication,
        didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
    ) {
        Deskwoot.setPushToken(deviceToken)
    }
}

// The system calls both on the main thread. Written this way they
// compile in the Swift 5 and the Swift 6 language mode.
extension AppDelegate: UNUserNotificationCenterDelegate {
    // A notification while your app is in front
    nonisolated func userNotificationCenter(
        _ center: UNUserNotificationCenter,
        willPresent notification: UNNotification,
        withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void
    ) {
        MainActor.assumeIsolated {
            if let options = Deskwoot.presentationOptions(for: notification) {
                completionHandler(options)
            } else {
                completionHandler([.banner, .list, .sound])   // one of your own
            }
        }
    }

    // A tap on a notification
    nonisolated func userNotificationCenter(
        _ center: UNUserNotificationCenter,
        didReceive response: UNNotificationResponse,
        withCompletionHandler completionHandler: @escaping () -> Void
    ) {
        MainActor.assumeIsolated {
            if !Deskwoot.handleNotificationResponse(response) {
                // one of your own: handle it here
            }
            completionHandler()
        }
    }
}

presentationOptions(for:) answers nil for a notification that is not Deskwoot's. For one of Deskwoot's it shows no banner while the visitor looks at that conversation. handleNotificationResponse opens the conversation and answers true; for your own notifications it answers false. isDeskwootNotification(_:) tells the two apart anywhere else. The SDK works out by itself whether a token belongs to Apple's sandbox or to production.

In a SwiftUI app, attach this app delegate with @UIApplicationDelegateAdaptor. The SDK swizzles no methods: your app makes these calls itself.

In your Android app

Your app needs Firebase Cloud Messaging. Hand the FCM registration token to setPushToken once at start and in onNewToken, and pass Deskwoot's messages on in onMessageReceived:

Android (Kotlin)
class PushService : FirebaseMessagingService() {
    override fun onNewToken(token: String) {
        Deskwoot.setPushToken(token)
    }

    override fun onMessageReceived(message: RemoteMessage) {
        if (Deskwoot.isDeskwootPush(message.data)) {
            Deskwoot.handlePush(this, message.data)
            return
        }
        // one of your own: handle it here
    }
}

// Once at start, for example in Application.onCreate after Deskwoot.setup
FirebaseMessaging.getInstance().token.addOnSuccessListener { token ->
    Deskwoot.setPushToken(token)
}

The SDK draws the notification itself, in its own notification channel and with your app's icon (setNotificationIcon(resId) sets another). A tap opens the conversation, and nothing shows while the visitor looks at that conversation. On Android 13 and later your app asks for POST_NOTIFICATIONS when it suits; without it no notification shows.

When a push goes out

Deskwoot sends one for each reply of your team or your AI bot, never for the visitor's own messages. If the visitor was online a moment before, Deskwoot waits 12 seconds and sends nothing when they have read the reply by then. The title says who wrote, and the text shows up to 160 characters of the reply. When your user signs out, the SDK removes that visitor's notifications and takes the phone off their pushes.

What the SDK adds to your app

WhatiOSAndroid
SizeAbout 1.24 MB compressed (the app zipped, close to what the App Store delivers). Uncompressed, 2.67 MB of code and 0.17 MB of texts in 10 languages.About 0.7 MB with everything it brings: a minimal app built with R8 grows from 23 KB to 724 KB. An app that already ships Kotlin, coroutines and androidx pays less. The AAR itself is 1.7 MB.
PermissionsNone. Add NSCameraUsageDescription only if visitors may send photos taken with the camera; without it the attachment menu offers the photo library and files, which need no permission.INTERNET only. Photos come from the system photo picker and files from the system document picker; neither needs a permission. The camera goes through the system camera app, and the SDK asks for the camera permission only when your app declares it itself.
DependenciesNone outside Apple's own frameworks.kotlinx-coroutines-android, androidx.annotation, androidx.core, androidx.activity, androidx.recyclerview, with what they bring themselves (androidx lifecycle, savedstate, collection and the like), but without androidx.profileinstaller. No OkHttp, no Retrofit, no JSON or image library, no Firebase, no Compose.
In your appNothing runs before setup, and the SDK swizzles no methods.1 Activity (DeskwootActivity) and 1 FileProvider (DeskwootFileProvider), both not exported. No service and no receiver. Before setup the SDK only keeps your app's context in its FileProvider, and none of your themes or styles is changed.
At app startNo cost: setup runs every disk and network step in the background.No cost: setup runs every disk and network step in the background.

Measured for version 1.0.0. iOS: two otherwise empty apps that differ only by the SDK, Release build for iPhone (arm64); the stripped binary has 2,744,720 bytes against 73,248 bytes without the SDK. Android: a minimal app with 1 Activity.

Frequently asked questions

The short answers are here. For anything else, ask Fynn below.

Is there an SDK for React Native or Flutter?

No. Deskwoot has native SDKs for iOS (Swift) and Android (Kotlin and Java) and no package for React Native or Flutter. In an app built with them you can show the website chat in a web view with the widget's embedded mode, described on the Widget SDK page.

Does the chat work without push notifications?

Yes. While your app is open, a reply shows in the unread count, on the card at the bottom of your app and on the launcher badge. Push notifications add the replies that arrive while the app is closed.

Where do the conversations from the app show up?

In the inbox whose widget token you pass to setup. With the same token as your website, app chats and website chats share one inbox, its settings, your team and your AI bot.

Deskwoot interactive demo