SwiftUI

Why Use These?

Building a chat list by hand means handling placeholder bubbles, tool cards, empty slots between tool calls, paging through history, and error recovery. The SDK ships two classes that do all of that for you:

Type	Use it for
`ConversationState`	One chat screen: messages, streaming, tools, history, retry.
`ConversationListState`	A list of past conversations, with paging.

Both update on the main thread and work with @Observable, so SwiftUI redraws when they change. Keep them in @State, in a view model, or in the environment, whichever your app already does.

ConversationState

@MainActor @Observable final class ConversationState

init

public init(client: ChatbaseClient, conversationId: String? = nil)

ChatbaseClient

required

The client to send through. Register your tools on it first.

String?

Reopen an existing conversation. Leave it out for a new one.

A complete chat screen

import SwiftUI
import ChatbaseSDK

struct ChatScreen: View {
    @State private var state: ConversationState
    @State private var input = ""

    init(client: ChatbaseClient) {
        _state = State(initialValue: ConversationState(client: client))
    }

    var body: some View {
        VStack(spacing: 0) {
            ScrollViewReader { proxy in
                List {
                    if state.hasMoreHistory {
                        ProgressView()
                            .frame(maxWidth: .infinity)
                            .task { await state.loadMoreHistory() }
                    }

                    ForEach(state.messages) { message in
                        MessageRow(message: message) {
                            Task { await state.retry(messageId: $0) }
                        }
                        .id(message.id)
                    }
                }
                .onChange(of: state.messages.count) {
                    withAnimation { proxy.scrollTo(state.messages.last?.id) }
                }
            }

            Composer(text: $input, isSending: state.isSending) {
                let text = input
                input = ""
                Task { await state.sendMessage(text) }
            }
        }
        .alert(
            "Something went wrong",
            isPresented: .init(
                get: { state.error != nil },
                set: { if !$0 { state.clearError() } }
            )
        ) {
            Button("OK") { state.clearError() }
        } message: {
            Text(state.error?.localizedDescription ?? "")
        }
    }
}

Notice what you did not have to write: no placeholder handling, no joining text chunks together, no tool loop tracking.

Showing a message

struct MessageRow: View {
    let message: ConversationState.UiMessage
    let onRetry: (String) -> Void

    var body: some View {
        switch message.kind {
        case .text(let text):
            TextBubble(text: text, isUser: message.sender == .user)
                .opacity(message.isStreaming && text.isEmpty ? 0.5 : 1)
                .overlay(alignment: .trailing) {
                    if message.isError, let id = message.messageId {
                        Button("Retry") { onRetry(id) }
                    }
                }

        case .toolCall(let card):
            ToolCard(
                name: card.toolName,
                status: card.status,
                output: card.output
            )
        }
    }
}

What you can read

Property	Type	Description
`messages`	`[UiMessage]`	The messages to show, oldest first.
`isSending`	`Bool`	A message or retry is in progress. Disable the text field.
`isLoadingHistory`	`Bool`	A page of history is loading.
`hasMoreHistory`	`Bool`	There are older messages to load.
`conversationId`	`String?`	Tracked for you after the first message.
`error`	`Error?`	The last error. Clear it with `clearError()`.

You cannot set these directly. Use the methods below.

sendMessage

public func sendMessage(_ text: String) async

Adds the user’s message, streams the reply into a new bubble, runs the tools, and tidies up at the end. It never throws. Errors go into error, and the failed bubble is marked with isError.

Task { await state.sendMessage(text) }

Empty text is ignored, and so is a call made while isSending is true, so you do not have to guard the button yourself (though disabling it is nicer). The conversation ID is taken from the first reply and reused after that.

retry

public func retry(messageId: String) async

Asks the agent to answer again. That message and everything after it are removed from messages, then the new reply streams in.

Button("Regenerate") {
    Task { await state.retry(messageId: id) }
}

Pass the server’s ID from UiMessage.messageId, not UiMessage.id. The call is ignored if a message is already being sent, if there is no conversation yet, or if that ID is not in the list.

loadHistory

public func loadHistory(conversationId: String, limit: Int = 20) async

Replaces messages with the newest page of an existing conversation and switches to it. Use it when opening a conversation from a list:

.task { await state.loadHistory(conversationId: conversation.id) }

loadMoreHistory

public func loadMoreHistory() async

Loads the next page of older messages and adds them to the top, skipping any you already have. Does nothing when hasMoreHistory is false or a load is already running.

clear

public func clear()

Resets everything: messages, conversation ID, history, and error. Call it when the user signs out, together with client.logout(), or when starting a new chat:

Button("New chat") { state.clear() }

clearError and setConversationId

public func clearError()
public func setConversationId(_ id: String?)

clearError() dismisses the last error. setConversationId(_:) points the state at a conversation without loading its messages, which is useful if you already have them from somewhere else.

UiMessage

struct ConversationState.UiMessage: Identifiable, Sendable One row on screen. A single message from the server can become several UiMessage values, one per part, so text and tool cards appear in the order the agent made them.

public struct UiMessage: Identifiable, Sendable {
    public enum Kind: Sendable {
        case text(String)
        case toolCall(ToolCallCard)
    }

    public var id: String
    public var messageId: String?
    public var kind: Kind
    public var sender: MessageSender
    public var date: Date
    public var isStreaming: Bool
    public var isError: Bool
    public var feedback: MessageFeedback?
}

String

required

A stable ID for ForEach. Made locally for new rows, and from the server’s message for older ones.

String?

The server’s message ID, filled in once the reply finishes. Pass this to retry(messageId:).

Kind

required

.text(String) for a bubble, .toolCall(ToolCallCard) for a tool card.

MessageSender

required

.user or .agent. Tool cards are always .agent.

Date

required

When the row was made, or when the message was sent.

Bool

required

true while text is still arriving in this bubble. Use it to show a typing dot or a cursor.

Bool

required

true when the reply failed. Show a retry button.

MessageFeedback?

.positive, .negative, or nil. Set for messages loaded from history.

id and messageId are different on purpose. id exists as soon as a row appears, so SwiftUI can animate it. messageId only exists once the server has given the message an ID. Use id for ForEach and scrollTo, and messageId for retry.

ToolCallCard

struct ConversationState.ToolCallCard: Sendable

public struct ToolCallCard: Sendable {
    public enum Status: Sendable { case executing, success, failure }

    public var toolCallId: String
    public var toolName: String
    public var input: JSONValue
    public var output: JSONValue?
    public var status: Status
}

A card appears as .executing as soon as the agent asks for the tool, then becomes .success or .failure when the result arrives.

The status follows the SDK’s usual rule: a result that is an object with an error key counts as .failure, and anything else counts as .success. This is the same rule your handlers use to report a problem. See Client-Side Tools.If the whole reply fails, every card still showing .executing is switched to .failure, so no card spins forever.

struct ToolCard: View {
    let name: String
    let status: ConversationState.ToolCallCard.Status
    let output: JSONValue?

    var body: some View {
        HStack {
            switch status {
            case .executing: ProgressView()
            case .success:   Image(systemName: "checkmark.circle.fill").foregroundStyle(.green)
            case .failure:   Image(systemName: "xmark.circle.fill").foregroundStyle(.red)
            }
            Text(name).font(.footnote.monospaced())
        }
    }
}

ConversationListState

@MainActor @Observable final class ConversationListState A list of the user’s past conversations, loaded a page at a time.

public init(client: ChatbaseClient)

Property	Type	Description
`conversations`	`[Conversation]`	The conversations loaded so far, newest first.
`isLoading`	`Bool`	A page is loading.
`hasMore`	`Bool`	There are more pages.
`error`	`Error?`	The last error. Clear it with `clearError()`.

load

public func load(limit: Int = 20) async

Loads the first page and replaces conversations. Use it for the first load and for pull to refresh.

loadMore

public func loadMore() async

Adds the next page to the list. Does nothing when hasMore is false or a page is already loading.

clearError

public func clearError()

struct ConversationsScreen: View {
    @State private var state: ConversationListState

    init(client: ChatbaseClient) {
        _state = State(initialValue: ConversationListState(client: client))
    }

    var body: some View {
        List {
            ForEach(state.conversations) { conversation in
                NavigationLink(conversation.title ?? "New conversation") {
                    ChatScreen(conversationId: conversation.id)
                }
            }
            if state.hasMore {
                ProgressView()
                    .task { await state.loadMore() }
            }
        }
        .task { await state.load() }
        .refreshable { await state.load() }
    }
}

Using UIKit

Neither class is tied to SwiftUI. From UIKit you can watch them with withObservationTracking, or skip them and call client.send(_:conversationId:configure:) yourself, switching to the main thread inside the callbacks:

Task {
    do {
        let response = try await client.send(text) { cb in
            cb.onTextDelta = { chunk in
                await MainActor.run { self.appendToBubble(chunk) }
            }
        }
        await MainActor.run { self.finalize(response) }
    } catch {
        await MainActor.run { self.showError(error) }
    }
}

Streaming

The send and callback API underneath

Client-Side Tools

What fills in the tool cards

Conversations & History

The paging behind these classes

Error Handling

Turning state.error into a good message

Getting Started

Reference

Why Use These?

ConversationState

init

A complete chat screen

Showing a message

What you can read

sendMessage

retry

loadHistory

loadMoreHistory

clear

clearError and setConversationId

UiMessage

ToolCallCard

ConversationListState

load

loadMore

clearError

Using UIKit

Streaming

Client-Side Tools

Conversations & History

Error Handling

​Why Use These?

​ConversationState

​init

​A complete chat screen

​Showing a message

​What you can read

​sendMessage

​retry

​loadHistory

​loadMoreHistory

​clear

​clearError and setConversationId

​UiMessage

​ToolCallCard

​ConversationListState

​load

​loadMore

​clearError

​Using UIKit

​Related

Streaming

Client-Side Tools

Conversations & History

Error Handling

Why Use These?

ConversationState

init

A complete chat screen

Showing a message

What you can read

sendMessage

retry

loadHistory

loadMoreHistory

clear

clearError and setConversationId

UiMessage

ToolCallCard

ConversationListState

load

loadMore

clearError

Using UIKit

Related