Android SDK (Kotlin)

The Orbit Android SDK embeds Orbit’s end-user-facing surfaces into a native Android app: in-app chat (the same omnichannel conversation/inbox the web widget and iOS SDK use), owned in-app messages and content cards, and video rooms. It ships as a single Gradle module with three clients — OrbitChatClient, OrbitInAppClient, and OrbitVideoRoomClient — and targets Android API 21+ (Kotlin, coroutines, kotlinx.serialization, OkHttp). This is a client SDK: it authenticates only with a publishable key (dv_live_pk_…), because it ships inside a distributed app binary. It intentionally does not wrap the server-side management resources (messaging, voice, contacts, campaigns, verify) — those require a secret key and belong in your backend, via the Node SDK or the REST API. See Client / mobile SDKs (different scope, by design) on the SDK index.

Pre-publish — source-only. The Android SDK is not yet on Maven Central — the Gradle dependency line below fails today. Until first publish, vendor the source from the monorepo (packages/sdk-android/) and include it as a Gradle project dependency.

Scope map: what the SDK covers, and what it deliberately does not

The three clients cover end-user surfaces — the things the person holding the phone sees. Everything a tenant’s operator configures runs through your backend with a secret key, and none of that ships in the app binary.

Surface	In the Android SDK	In your backend (Node SDK / REST API)
Chat	`OrbitChatClient` — the visitor-side conversation: history, optimistic send, real-time inbound stream, attachments	Conversation routing rules, agent assignment, transcripts, message suppression
In-app messaging	`OrbitInAppClient` — the per-visitor feed, impression/click/dismiss reporting	Building the campaign, targeting the audience, checkout-free content cards
Video	`OrbitVideoRoomClient` — joining a room, publish toggles, breakout rooms, captions	Minting the join token (`POST /api/v1/video/rooms/:id/join`), room creation, recordings
Management resources	— (not covered, by design)	Messaging, voice, contacts, campaigns, verify, billing, numbers, webhooks

Integration planning rule: if the call belongs to a visitor (read the feed, send a chat message, join a room), it belongs in the app; if it belongs to the tenant (create the room, author the campaign, send the outbound message), it belongs in your backend.

Installation (Gradle)

// app/build.gradle.kts
dependencies {
    implementation("io.devotel:orbit-chat-sdk:0.1.0")
}

Version compatibility

The module’s build contract is fixed by its own Gradle configuration — match your app against these floors:

Constraint	Value
Minimum Android API	API 21 (Android 5.0)
Compile SDK	34
Kotlin	2.0.21 (Kotlin plugin + `kotlinx-serialization` plugin)
JVM target	17 (source and target compatibility)
Coroutines	`kotlinx-coroutines-android` 1.8.1
Serialization	`kotlinx-serialization-json` 1.6.3
HTTP	OkHttp 4.12.0

AGP 8.5.0 builds the library. All network methods are suspend, so call them from a coroutine (for example lifecycleScope / viewModelScope); the video client additionally needs a Main-dispatcher engine callback surface.

Headless chat client (OrbitChatClient)

The client ships zero UI — it owns the conversation lifecycle, history, optimistic send, and the real-time inbound stream; your Activity, Fragment, or Compose screen renders it. All network methods are suspend functions.

import io.orbit.devotel.chat.OrbitChatClient
import io.orbit.devotel.chat.OrbitChatConfig
import io.orbit.devotel.chat.SharedPreferencesStorage

val chat = OrbitChatClient(
    OrbitChatConfig(
        publicKey = "dv_live_pk_…",                    // publishable key ONLY — never a secret key
        storage = SharedPreferencesStorage(context),   // persist across launches
        appInfo = "acme-android/2.3.1",
    )
)

chat.onMessage { message -> println("agent: ${message.body}") }
chat.onMessages { all -> render(all) }
chat.onTyping { isTyping -> setTyping(isTyping) }
chat.onConnection { status -> println("status: $status") }

chat.connect()
chat.sendMessage("Hi, I need help with my order")

Each on… method returns an OrbitSubscription; call .cancel() on it to stop receiving the event. Call chat.disconnect() to stop the real-time stream, and chat.close() when the client is done (it cancels the internal coroutine scope — the client cannot be reused after that). Send a file attachment (10 MB client-side guard):

val bytes = contentResolver.openInputStream(uri)!!.readBytes()
chat.sendAttachment(
    OrbitChatAttachment(
        bytes = bytes,
        name = "photo.jpg",
        mimeType = "image/jpeg",
        size = bytes.size,
    )
)

Storage adapter contract (OrbitChatStorage)

Chat persistence is an injectable three-method interface — pass it so the active conversation id survives process death and the next cold launch resumes the same conversation instead of creating a fresh one:

interface OrbitChatStorage {
    fun getString(key: String): String?
    fun putString(key: String, value: String)
    fun remove(key: String)
}

The SDK ships SharedPreferencesStorage(context) as the built-in implementation (one SharedPreferences file, MODE_PRIVATE). Any other key/value store — DataStore, an encrypted store, a Room table — satisfies the contract equally, as long as writes are durable before the client reads them back on the next launch:

class DataStoreStorage(private val context: Context) : OrbitChatStorage {
    // `blockingGet`/runBlocking-free wrapper assumed — keep reads synchronous,
    // because the interface deliberately avoids `suspend`.
    override fun getString(key: String): String? =
        dataStorePeek(key) // your synchronous read path

    override fun putString(key: String, value: String) =
        dataStorePut(key, value)

    override fun remove(key: String) = dataStoreRemove(key)
}

Two rules keep the adapter honest:

Reads must be synchronous. The interface is non-suspend on purpose, because the client consults storage on its own IO dispatcher while building the first request. A DataStore flow that only emits asynchronously will deadlock or race; bridge it (or use the shipped SharedPreferences implementation, which needs no bridge).
Omit storage and the session is process-scoped. With storage = null the client keeps the conversation for the process lifetime only — correct for a guest-checkout flow, wrong for a support inbox.

The in-app client has its own storage adapter (OrbitInAppStorage, same three-method shape minus remove) so the sticky anonymous id and the locally-dismissed surfaces survive restarts. Import io.orbit.devotel.inapp.SharedPreferencesInAppStorage for the shipped implementation. .close() is terminal — it cancels the client’s internal coroutine scope, so calls made after it throw on a cancelled scope. Order the lifecycle explicitly, and create one client per Activity/ViewModel that you then close in onDestroy / onCleared:

Step	Call	Effect
1. Construct	`OrbitChatClient(config)`	Synchronously validates the key; throws `IllegalArgumentException` on an empty key or a server-side secret key prefix
2. Subscribe	`chat.onMessage { … }`, `chat.onMessages { … }`, …	Each registration returns an `OrbitSubscription`; handlers stay hot until you call `subscription.cancel()`
3. Connect	`chat.connect()` (`suspend`)	Restores the conversation from the storage adapter if present, else creates it; starts the real-time inbound poll stream
4. Use	`chat.sendMessage(…)`, `chat.sendAttachment(…)`	Optimistically appends, then confirms; an `OrbitApiError` on failure removes the optimistic echo
5. Disconnect	`chat.disconnect()`	Stops the poll stream; the conversation survives (resume by calling `connect()` again)
6. Close	`chat.close()`	Cancels the internal scope. Terminal — the client cannot be reconnected after this

The two safe teardown shapes:

// Compose-friendly: cancel subscriptions, keep the client resumable.
override fun onStop() {
    messageSub.cancel()
    typingSub.cancel()
    chat.disconnect()
}

// Final teardown in ViewModel.onCleared() / Activity.onDestroy():
override fun onCleared() {
    chat.close()   // never call connect() after this
}

For video, the symmetry is join() → leave() on the engine-injected client: leave() disconnects the underlying VideoRoomEngine (releases camera/mic), and the client carries no own coroutine scope to close.

In-app messages and content cards (OrbitInAppClient)

Owned in-app surfaces — assembled server-side into a per-visitor feed, rendered locally, with impression / click / dismiss reported back. Dismissals persist across launches through the storage adapter.

import io.orbit.devotel.inapp.OrbitInAppClient
import io.orbit.devotel.inapp.OrbitInAppConfig
import io.orbit.devotel.inapp.InAppEventType

val inApp = OrbitInAppClient(
    OrbitInAppConfig(publicKey = "dv_live_pk_…")
)

val feed = inApp.fetchFeed()
inApp.reportEvent(InAppEventType.IMPRESSION, feed.cards.first().id)
inApp.dismiss(feed.cards.first().id)

reportEvent takes the InAppEventType enum, not a raw string — a string literal ("impression") or an alias ("page_view") sails through the call and is then rejected by the server with a 422. The closed set and the fix per language are in InAppEventType: the in-app event enum. feed.cards carries the surfaces your tenant published without-you-seeing-them fetched; report exactly one impression per rendered surface and keep dismiss(...) idempotent — the client maintains the local dismissed set (and persists it through the storage adapter when you passed one). anonymousId() exposes the sticky anon id the targeting rule matched against.

Video rooms (OrbitVideoRoomClient)

Headless and engine-injected: your backend mints the room token server-side (POST /api/v1/video/rooms/:id/join) and hands the token plus server URL to the app. Wire the client over a VideoRoomEngine backed by a WebRTC engine (for example the Orbit Media SDK for Android), so this package carries no hard WebRTC dependency.

Media-engine selection

The client implements the state and protocol; the engine implements the WebRTC bits. The VideoRoomEngine contract is deliberately small — connect, disconnect, the three publish toggles, and the local-participant accessor:

Engine	When to pick it
LiveKit (`livekit-android`)	You already run LiveKit elsewhere, or you want the upstream client with its own codecs/ICE stack and you accept the dependency footprint
Orbit Media SDK for Android	You want the engine Devotel ships and tunes against Orbit’s media backend (the recommended pairing) — same `VideoRoomEngine` surface
Custom engine	You have in-house WebRTC expertise — implement `connect / disconnect / setCameraEnabled / setMicrophoneEnabled / setScreenShareEnabled / localParticipant` and the client will drive it

Either way, the client is engine-agnostic: swap the constructor arg and the room-join / captions / breakout logic is unchanged, because the engine only moves media and the client owns all state and event fan-out.

import io.orbit.devotel.video.OrbitVideoRoomClient
import io.orbit.devotel.video.OrbitVideoRoomConfig

val room = OrbitVideoRoomClient(
    OrbitVideoRoomConfig(token = roomToken, serverUrl = roomServerUrl),
    engine = myVideoRoomEngine,
)

room.onTrackSubscribed { track, participant -> render(track, participant) }
room.onCaption { caption -> showCaption(caption) }
room.join()

val micOn = room.toggleMicrophone()
room.joinBreakout(name = "support-tier-2", token = breakoutToken)
room.leave()

joinBreakout(name, token) and returnToMainRoom(...) let you move a participant between the main room and a named breakout without rebuilding the client. The publish toggles (toggleMicrophone(), toggleCamera(), toggleScreenShare()) return the new enabled state so a toggle button can bind directly on the result.

Push token onboarding (backend)

The Android SDK ships chat, in-app, and video clients; registering the device’s FCM token for push delivery is a backend call against POST /api/v1/push/device-tokens, run with a secret key via the Node SDK or plain HTTP:

import { Devotel } from '@devotel-orbit/node';

const orbit = new Devotel({ apiKey: process.env.ORBIT_API_KEY });

const registered = await orbit.push.tokens.register({
  platform: 'android',
  token: fcmToken,
  user_id: 'user_8a1f2c',
});

No SDK in the backend? The same call over HTTP:

curl -X POST https://api.orbit.devotel.io/api/v1/push/device-tokens \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"platform": "android", "token": "<fcm-token>", "user_id": "user_8a1f2c"}'

Re-registering an existing token is an upsert — call it on every FCM token rollover and last-seen is bumped, never duplicated. Delivery-side mechanics (categories, rich media, scheduling) live in the push channel reference.

Runnable examples

The package’s examples/ directory holds self-contained end-to-end Kotlin files — each takes the publishable key from ORBIT_PUBLIC_KEY (dv_test_pk_… / dv_live_pk_…): ChatConnectSend (chat connect + send with OrbitApiError.status + retryAfterSeconds handling) and InAppFeed (/sdk/in-app/feed fetch + IMPRESSION + dismiss(surfaceId)). Swap sandbox vs live by changing the env value — no code edits. See packages/sdk-android/examples/README.md for how to load the key from local.properties via BuildConfig. FCM device tokens stay backend-only (POST /api/v1/push/device-tokens), so there is no client FCM sample to keep the distributed-binary invariant intact.

Error handling

API failures surface as a typed OrbitApiError carrying the HTTP status and the server response excerpt; a parsed Retry-After lets a 429 be throttled instead of retried in a hot loop. Construction misuse (empty key or a server-side secret key) throws IllegalArgumentException; attachment-size checks throw OrbitChatException.

import io.orbit.devotel.chat.OrbitApiError

try {
    chat.sendMessage("Where is my order?")
} catch (err: OrbitApiError) {
    when (err.status) {
        429 -> // respect the Retry-After hint before retrying
        401 -> // the publishable key is no longer valid
        else -> println("orbit error: HTTP ${err.status}")
    }
}

Troubleshooting with the status mapping

Every client in the module raises the same OrbitApiError(status, responseExcerpt, message, retryAfterSeconds) — branch on status first, and read responseExcerpt only for diagnostics (it is capped at 200 chars).

Status	Meaning	Correct handling
400 / 422	Request body failed server-side validation	Fix the payload; do not retry as-is
401	The publishable key was revoked or mistyped	Refresh the key into `OrbitChatConfig` and construct a new client
403	The key exists but lacks the surface scope	Check the tenant’s client-SDK surface enablement
404	The conversation / surface id no longer exists	Recreate by re-connecting; for in-app, refetch the feed
429	Rate-limited	Wait `err.retryAfterSeconds` (parsed delta-seconds; null when the server omitted the header) before retrying
5xx	Server-side failure	Retry with backoff; persists → surface to the user, log the excerpt

Local, pre-network failures never reach OrbitApiError — construction-time validation (empty key, or a secret-key prefix dv_live_sk_… / dv_test_sk_…) throws IllegalArgumentException, and the attachment 10 MB guard throws OrbitChatException before any bytes move. Only the publishable key (dv_live_pk_… / dv_test_pk_…) may be embedded in the app. The clients refuse a server-side secret key (dv_live_sk_… / dv_test_sk_…) at construction, because anything bundled in a distributed binary is extractable by any user. Real-time updates use header-authenticated polling, so the key never lands in a URL log.

​Android SDK (Kotlin)

​Scope map: what the SDK covers, and what it deliberately does not

​Installation (Gradle)

​Version compatibility

​Headless chat client (OrbitChatClient)

​Storage adapter contract (OrbitChatStorage)

​Lifecycle ordering: connect → subscribe → send → disconnect → close

​In-app messages and content cards (OrbitInAppClient)

​Video rooms (OrbitVideoRoomClient)

​Media-engine selection

​Push token onboarding (backend)

​Runnable examples

​Error handling

​Troubleshooting with the status mapping

Android SDK (Kotlin)

Scope map: what the SDK covers, and what it deliberately does not

Installation (Gradle)

Version compatibility

Headless chat client (OrbitChatClient)

Storage adapter contract (OrbitChatStorage)

Lifecycle ordering: connect → subscribe → send → disconnect → close

In-app messages and content cards (OrbitInAppClient)

Video rooms (OrbitVideoRoomClient)

Media-engine selection

Push token onboarding (backend)

Runnable examples

Error handling

Troubleshooting with the status mapping