Android SDK

Requirements#

• minSdk 24 (Android 7.0), compileSdk / targetSdk 35.
• Kotlin 2.x and Jetpack Compose (the SDK ships Compose UI).
• JVM target 17.

The SDK pulls its own transitive dependencies (Coroutines, kotlinx.serialization, OkHttp, Coil, Compose) and declares the INTERNET permission in its manifest — nothing to add by hand.

Installation#

The library is published to Maven Central as ai.respondo:respondo-sdk. Make sure mavenCentral() is in your repositories (it is by default in a new Android project), then add the dependency by coordinate.

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
    }
}

dependencies {
    implementation("ai.respondo:respondo-sdk:0.1.0")
}

Initialize#

Call Respondo.init once, mount RespondoChatHost() once in your Compose tree, and open the chat from your own button.

import ai.respondo.sdk.Respondo
import ai.respondo.sdk.RespondoConfig
import ai.respondo.sdk.ui.RespondoChatHost

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        Respondo.init(
            context = this,
            config = RespondoConfig(
                agentId = "<agent-uuid>",   // from the dashboard
                channelId = "<channel-uuid>", // optional
                // baseUrl omitted -> https://api.respondo.ai
            ),
        )

        setContent {
            MaterialTheme {
                Box(modifier = Modifier.fillMaxSize()) {
                    Button(onClick = { Respondo.open() }) { Text("Support") }
                    RespondoChatHost() // SDK shows the sheet when chat state is OPEN
                }
            }
        }
    }
}

All calls go through the Respondo singleton. They are idempotent, safe from any thread, and calls made before init finishes are buffered and replayed.

Identify users#

By default every visitor is anonymous. On first launch the SDK generates a stable visitor_id and keeps it in local storage, 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.

import ai.respondo.sdk.RespondoIdentity

// 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: drop the push token, revoke the session, start a fresh anonymous visitor.
Respondo.clearPushToken()
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 & callbacks#

Read state reactively as StateFlow (great for Compose) or imperatively via RespondoListener (great for an app-icon badge).

// Reactive: unread count as a StateFlow.
val unread by Respondo.unreadCount.collectAsState()

// Imperative: listener for badges and analytics.
Respondo.setListener(object : RespondoListener {
    override fun onUnreadChanged(count: Int) { updateAppIconBadge(count) }
    override fun onUrlRequested(url: String): Boolean = tryOpenInternally(url)
})

Next steps#

Set up Push notifications for offline operator replies and Identity verification for signed-in users. The full API surface, the Fragment wrapper for XML hosts, and troubleshooting are covered in the Android SDK getting-started guide; the SDK sources are public on GitHub.