Android SDK Overview

Alpha Release. The Chatbase Android SDK is currently in alpha (v0.0.1-alpha03). APIs may change in future releases.

Conversation methods apply exclusively to conversations created through the mobile SDKs (Android and iOS). Conversations generated through the widget, the API, or external integrations cannot be accessed using the SDK. A user identified on both platforms sees their Android and iOS SDK conversations together.

What is the Chatbase Android SDK?

The Chatbase Android SDK is a Kotlin-first library that lets you integrate Chatbase agents into your Android app. It provides:

Real-time streaming with two levels of abstraction
Client-side tools that let the agent invoke local functions on the device
User identity with JWT-based authentication and automatic device ID tracking
Conversation management with cursor-based pagination
Structured error handling with typed exceptions

Requirements:

Requirement	Minimum
Android API	24 (Android 7.0)
Java	11+
Kotlin Coroutines	Required
Jetpack Compose	Not required — the SDK works with any UI framework

Installation

Kotlin DSL
Groovy

// build.gradle.kts (app module)
dependencies {
    implementation("com.chatbase:chatbase-sdk:0.0.1-alpha03")
}

// build.gradle (app module)
dependencies {
    implementation 'com.chatbase:chatbase-sdk:0.0.1-alpha03'
}

The SDK declares the INTERNET permission in its own manifest. It is merged automatically — you do not need to add it to your app’s manifest.

Quick Start

Get your Agent ID

Go to the Chatbase Dashboard
Select your agent
Go to Settings → General
Copy the Agent ID

Enable the Android SDK channel

In the dashboard, go to Deploy → Android SDK and enable the channel for your agent.

If the Android SDK channel is not enabled, every SDK request fails with a 404 AGENT_NOT_FOUND error — even when the agent ID is correct.

Create a client

import com.chatbase.sdk.Chatbase

val client = Chatbase.create(context, "YOUR_AGENT_ID")

context can be any Android Context (Activity, Application, etc.). It is only used during creation to generate the device ID.

Send your first message

import com.chatbase.sdk.model.Part

lifecycleScope.launch {
    val response = client.sendMessage("Hello! How can you help me?") {
        onTextDelta { delta ->
            // Called for each text chunk — safe to update UI
            print(delta)
        }
    }

    // Access the full response
    val text = response.parts
        .filterIsInstance<Part.Text>()
        .joinToString("") { it.text }

    println(text)
    println("Conversation: ${response.metadata.conversationId}")
}

Clean up

// In your ViewModel
override fun onCleared() {
    client.close()
}

Chatbase

object Chatbase — Package: com.chatbase.sdk The singleton factory for creating SDK clients.

create

fun create(context: Context, agentId: String): ChatbaseClient

Create a client with default settings.

Context

required

Any Android Context. Used only during creation to generate the device ID.

String

required

The Chatbase agent ID to connect to.

create (with configuration)

fun create(context: Context, block: ChatbaseConfig.Builder.() -> Unit): ChatbaseClient

Create a client with custom configuration via a DSL builder.

val client = Chatbase.create(context) {
    agentId = "YOUR_AGENT_ID"
    connectTimeoutMs = 15_000  // 15 seconds
    readTimeoutMs = 60_000     // 60 seconds
}

ChatbaseConfig

data class ChatbaseConfig — Package: com.chatbase.sdk

Property	Type	Default	Description
`agentId`	`String`	(required)	The Chatbase agent ID to connect to.
`connectTimeoutMs`	`Long`	`10_000`	Connection timeout in milliseconds.
`readTimeoutMs`	`Long`	`30_000`	Read timeout in milliseconds.

For streaming responses, the SDK uses a separate 5-minute read timeout regardless of the readTimeoutMs setting. This ensures long-running streams are not interrupted prematurely.

Rate Limits

The Chatbase API enforces a rate limit of 1,000 requests per 10 seconds per device, applied server-side. When the limit is exceeded, the SDK throws an ApiException with isRateLimited == true. See Error Handling for how to handle this.

Getting Started

Reference

Android SDK Overview

What is the Chatbase Android SDK?

Installation

Quick Start

Chatbase

create

create (with configuration)

ChatbaseConfig

Rate Limits

Next Steps

Streaming

Client-Side Tools

Conversations

Error Handling

​What is the Chatbase Android SDK?

​Installation

​Quick Start

​Chatbase

​create

​create (with configuration)

​ChatbaseConfig

​Rate Limits

​Next Steps

Streaming

Client-Side Tools

Conversations

Error Handling

What is the Chatbase Android SDK?

Installation

Quick Start

Chatbase

create

create (with configuration)

ChatbaseConfig

Rate Limits

Next Steps