> ## Documentation Index
> Fetch the complete documentation index at: https://chatbase.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Android SDK Overview

> Introduction to the Chatbase Android SDK — a Kotlin-first library for building conversational AI experiences on Android.

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

<Warning>
  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.
</Warning>

## 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

<Tabs>
  <Tab title="Kotlin DSL">
    ```kotlin theme={null}
    // build.gradle.kts (app module)
    dependencies {
        implementation("com.chatbase:chatbase-sdk:0.0.1-alpha03")
    }
    ```
  </Tab>

  <Tab title="Groovy">
    ```groovy theme={null}
    // build.gradle (app module)
    dependencies {
        implementation 'com.chatbase:chatbase-sdk:0.0.1-alpha03'
    }
    ```
  </Tab>
</Tabs>

<Note>
  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.
</Note>

## Quick Start

<Steps>
  <Step title="Get your Agent ID">
    1. Go to the [Chatbase Dashboard](https://www.chatbase.co/dashboard)
    2. Select your agent
    3. Go to **Settings** → **General**
    4. Copy the **Agent ID**
  </Step>

  <Step title="Enable the Android SDK channel">
    In the dashboard, go to **Deploy** → **Android SDK** and enable the channel for your agent.

    <Warning>
      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.
    </Warning>
  </Step>

  <Step title="Create a client">
    ```kotlin theme={null}
    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.
  </Step>

  <Step title="Send your first message">
    ```kotlin theme={null}
    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}")
    }
    ```
  </Step>

  <Step title="Clean up">
    ```kotlin theme={null}
    // In your ViewModel
    override fun onCleared() {
        client.close()
    }
    ```
  </Step>
</Steps>

## Chatbase

`object Chatbase` — **Package:** `com.chatbase.sdk`

The singleton factory for creating SDK clients.

### create

```kotlin theme={null}
fun create(context: Context, agentId: String): ChatbaseClient
```

Create a client with default settings.

<ParamField body="context" type="Context" required>
  Any Android `Context`. Used only during creation to generate the device ID.
</ParamField>

<ParamField body="agentId" type="String" required>
  The Chatbase agent ID to connect to.
</ParamField>

### create (with configuration)

```kotlin theme={null}
fun create(context: Context, block: ChatbaseConfig.Builder.() -> Unit): ChatbaseClient
```

Create a client with custom configuration via a DSL builder.

```kotlin theme={null}
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.        |

<Tip>
  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.
</Tip>

## 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](/docs/android-sdk/error-handling) for how to handle this.

## Next Steps

<CardGroup cols={2}>
  <Card title="Streaming" icon="wave-pulse" href="/docs/android-sdk/streaming">
    Real-time streaming with callbacks and Kotlin Flow
  </Card>

  <Card title="Client-Side Tools" icon="bolt" href="/docs/android-sdk/client-side-tools">
    Register local tool handlers the agent can invoke
  </Card>

  <Card title="Conversations" icon="messages" href="/docs/android-sdk/conversations">
    Manage conversations, history, and pagination
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/docs/android-sdk/error-handling">
    Exception hierarchy and error handling patterns
  </Card>
</CardGroup>