Conversations & History

Starting and Continuing Conversations

Send a message

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

val response = client.sendMessage("Hello!")

Get the conversation ID

The conversation ID is returned in the response metadata:

val conversationId = response.metadata.conversationId

Continue the conversation

Pass the conversationId to subsequent calls:

val followUp = client.sendMessage(
    message = "Tell me more",
    conversationId = conversationId
)

The SDK automatically tracks the current conversation ID. After your first sendMessage, subsequent calls without an explicit conversationId reuse the same conversation:

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

fun newConversation()

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

client.newConversation()
client.sendMessage("Brand new conversation!")

listConversations

suspend fun listConversations(
    cursor: String? = null,
    limit: Int? = null
): Page<Conversation>

Retrieve a paginated list of conversations.

String?

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

Int?

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

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

data class Conversation(
    val id: String,
    val title: String?,
    val createdAt: Long,
    val updatedAt: Long,
    val userId: String?,
    val status: ConversationStatus
)

String

required

Unique conversation ID.

String?

Auto-generated or server-assigned title.

Long

required

Creation timestamp (Unix epoch seconds).

Long

required

Timestamp of the last message (Unix epoch seconds).

String?

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

ConversationStatus

required

ONGOING, ENDED, or TAKEN_OVER.

listMessages

suspend fun listMessages(
    conversationId: String,
    cursor: String? = null,
    limit: Int? = null
): Page<Message>

Retrieve messages in a conversation.

String

required

The conversation to fetch messages from.

String?

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

Int?

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

Messages are returned in reverse chronological order — the first page contains the most recent messages. Within each page, messages are ordered oldest to newest.

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

data class Message(
    val id: String,
    val role: Role,
    val parts: List<Part>,
    val createdAt: Long?,
    val feedback: Feedback?,
    val metadata: MessageMetadata?
)

String

required

Unique message ID.

Role

required

USER or ASSISTANT.

List<Part>

required

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

Long?

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

Feedback?

POSITIVE, NEGATIVE, or null.

MessageMetadata?

Show properties

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.

data class Page<T>(
    val data: List<T>,
    val cursor: String?,
    val hasMore: Boolean,
    val total: Int
)

List<T>

required

Items on this page.

String?

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

Boolean

required

Whether more pages exist.

Int

required

Total item count across all pages.

val canLoadMore: Boolean

true if hasMore is true and cursor is non-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

var page = client.listConversations(limit = 20)

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

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

Streaming

Send messages and stream responses

User Identity

Scope conversations to users

Getting Started

Reference

Conversations & History

Starting and Continuing Conversations

newConversation

listConversations

Conversation

listMessages

Message

Paginating Through All Results

Streaming

User Identity

​Starting and Continuing Conversations

​newConversation

​listConversations

​Conversation

​listMessages

​Message

​Pagination

​Paginating Through All Results

​Related

Streaming

User Identity

Starting and Continuing Conversations

newConversation

listConversations

Conversation

listMessages

Message

Pagination

Paginating Through All Results

Related