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

# Conversations & History

> Manage conversations, load message history, and navigate paginated results with the Chatbase Android SDK.

## Starting and Continuing Conversations

**1. Send a message**

Send a message to start a new conversation. The SDK creates one automatically if no `conversationId` is provided.

```kotlin theme={null}
val response = client.sendMessage("Hello!")
```

**2. Get the conversation ID**

The conversation ID is returned in the response metadata:

```kotlin theme={null}
val conversationId = response.metadata.conversationId
```

**3. Continue the conversation**

Pass the `conversationId` to subsequent calls:

```kotlin theme={null}
val followUp = client.sendMessage(
    message = "Tell me more",
    conversationId = conversationId
)
```

> [!TIP]
>
> The SDK automatically tracks the current conversation ID. After your first `sendMessage`, subsequent calls without an explicit `conversationId` reuse the same conversation:
>
> ```kotlin theme={null}
> client.sendMessage("First message")             // starts a new conversation
> client.sendMessage("Follow-up")                 // continues the same conversation
> println(client.currentConversationId)            // "conv_abc123"
> ```

## newConversation

`interface ChatbaseClient` — **Package:** `com.chatbase.sdk`

```kotlin theme={null}
fun newConversation()
```

Clear the current conversation ID so the next `sendMessage` starts a new conversation.

```kotlin theme={null}
client.newConversation()
client.sendMessage("Brand new conversation!")
```

## listConversations

```kotlin theme={null}
suspend fun listConversations(
    cursor: String? = null,
    limit: Int? = null
): Page<Conversation>
```

Retrieve a paginated list of conversations.

**cursor** `String?`

Opaque cursor from a previous response. Omit to start from the beginning.

**limit** `Int?`

Number of items per page, between 1 and 100. Defaults to 20.

```kotlin theme={null}
val page = client.listConversations(limit = 20)

page.data.forEach { conversation ->
    println("${conversation.id} — ${conversation.title}")
    println("  Status: ${conversation.status}")
}

println("Total: ${page.total}")
println("Has more: ${page.hasMore}")
```

### Conversation

`data class Conversation` — **Package:** `com.chatbase.sdk.model`

```kotlin theme={null}
data class Conversation(
    val id: String,
    val title: String?,
    val createdAt: Long,
    val updatedAt: Long,
    val userId: String?,
    val status: ConversationStatus
)
```

**id** `String` *required*

Unique conversation ID.

**title** `String?`

Auto-generated or server-assigned title.

**createdAt** `Long` *required*

Creation timestamp (Unix epoch seconds).

**updatedAt** `Long` *required*

Timestamp of the last message (Unix epoch seconds).

**userId** `String?`

The identified user who owns this conversation, or `null` for anonymous (device-scoped) conversations.

**status** `ConversationStatus` *required*

`ONGOING`, `ENDED`, or `TAKEN_OVER`.

## listMessages

```kotlin theme={null}
suspend fun listMessages(
    conversationId: String,
    cursor: String? = null,
    limit: Int? = null
): Page<Message>
```

Retrieve messages in a conversation.

**conversationId** `String` *required*

The conversation to fetch messages from.

**cursor** `String?`

Opaque cursor from a previous response. Omit to start from the newest messages.

**limit** `Int?`

Number of items per page, between 1 and 100. Defaults to 20.

> [!NOTE]
>
> Messages are returned in **reverse chronological order** — the first page contains the most recent messages. Within each page, messages are ordered oldest to newest.

```kotlin theme={null}
val page = client.listMessages(conversationId, limit = 50)

page.data.forEach { message ->
    val role = if (message.role == Role.USER) "You" else "Agent"
    val text = message.parts
        .filterIsInstance<Part.Text>()
        .joinToString("") { it.text }
    println("$role: $text")
}
```

### Message

`data class Message` — **Package:** `com.chatbase.sdk.model`

```kotlin theme={null}
data class Message(
    val id: String,
    val role: Role,
    val parts: List<Part>,
    val createdAt: Long?,
    val feedback: Feedback?,
    val metadata: MessageMetadata?
)
```

**id** `String` *required*

Unique message ID.

**role** `Role` *required*

`USER` or `ASSISTANT`.

**parts** `List\<Part\>` *required*

Message content parts (text, tool calls, tool results).

**createdAt** `Long?`

Creation timestamp (Unix epoch seconds). Absent on some older messages.

**feedback** `Feedback?`

`POSITIVE`, `NEGATIVE`, or `null`.

**metadata** `MessageMetadata?`

**properties**

**score** `Double?`

Confidence/relevance score.

## Pagination

`data class Page<T>` — **Package:** `com.chatbase.sdk.model`

All list methods return a `Page<T>` with built-in pagination support.

```kotlin theme={null}
data class Page<T>(
    val data: List<T>,
    val cursor: String?,
    val hasMore: Boolean,
    val total: Int
)
```

**data** `List\<T\>` *required*

Items on this page.

**cursor** `String?`

Cursor for the next page. `null` if no more pages.

**hasMore** `Boolean` *required*

Whether more pages exist.

**total** `Int` *required*

Total item count across all pages.

```kotlin theme={null}
val canLoadMore: Boolean
```

`true` if `hasMore` is true and `cursor` is non-null.

```kotlin theme={null}
suspend fun loadMore(): Page<T>?
```

Load the next page. Returns a new `Page` with the older items prepended to the existing `data`, so you always have the full accumulated list. Returns `null` if there are no more pages.

### Paginating Through All Results

```kotlin theme={null}
var page = client.listConversations(limit = 20)

while (true) {
    page.data.forEach { conversation ->
        println(conversation.title)
    }

    if (!page.canLoadMore) break
    page = page.loadMore() ?: break
}
```

## Related

> **[Streaming](https://chatbase.co/docs/android-sdk/streaming.md)**
>
> Send messages and stream responses

> **[User Identity](https://chatbase.co/docs/android-sdk/user-identity.md)**
>
> Scope conversations to users


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.