Conversations & History

Starting and Continuing Conversations

Send a message

Send a message with no conversationId to start a new conversation. The server creates one.

let response = try await client.send("Hello!")

Keep the conversation ID

let conversationId = response.conversationId

You can also read it afterwards as client.currentConversationId.

Continue the conversation

Pass the ID to the next call:

let followUp = try await client.send(
    "Tell me more",
    conversationId: conversationId
)

Passing conversationId: nil always starts a new conversation. It does not fall back to currentConversationId. Pass the ID yourself, or use ConversationState, which keeps it for you.

// Wrong: two separate conversations
_ = try await client.send("My name is Alice.")
_ = try await client.send("What is my name?")

// Right: one conversation
let first = try await client.send("My name is Alice.")
_ = try await client.send("What is my name?", conversationId: first.conversationId)

newConversation

public func newConversation()

Clears currentConversationId. Use it if you track the current conversation through the client rather than your own state.

client.newConversation()
_ = try await client.send("Brand new conversation!")

ConversationState has its own clear(), which also empties the message list. Use that in UI code.

listConversations

public func listConversations(
    cursor: String? = nil,
    limit: Int? = nil
) async throws -> PaginatedResponse<Conversation>

Lists the current user’s (or device’s) conversations, newest first.

String?

A cursor from an earlier page. Leave it out to start at the beginning. Prefer loadMore() over passing cursors yourself.

Int?

How many per page, from 1 to 100. The server uses 20 if you leave it out.

let page = try await client.listConversations(limit: 20)

for conversation in page.data {
    print("\(conversation.id): \(conversation.title ?? "Untitled")")
    print("  Status: \(conversation.status)")
    print("  Updated: \(conversation.updatedAt.formatted())")
}

print("Total: \(page.total)")
print("Has more: \(page.hasMore)")

Only conversations created through the mobile SDKs are listed. Widget, API, and integration conversations are left out. Which ones you get depends on identity: the signed-in user’s conversations if there is one, otherwise the device’s. See User Identity.

See Conversation for the full type.

listMessages

public func listMessages(
    conversationId: String,
    cursor: String? = nil,
    limit: Int? = nil
) async throws -> PaginatedResponse<Message>

Loads the messages in a conversation.

String

required

The conversation to load messages from.

String?

A cursor from an earlier page. Leave it out to start with the newest messages.

Int?

How many per page, from 1 to 100. The server uses 20 if you leave it out.

Pages go backwards in time. The first page holds the newest messages, and each loadMore() gets older ones. Inside a page, messages run oldest to newest, so you can add a page to a chat view as it is. When you load an older page, add it to the top.

let page = try await client.listMessages(conversationId, limit: 50)

for message in page.data {
    let who = message.sender == .user ? "You" : "Agent"
    print("\(who): \(message.text)")
}

Each Message has both a plain text value (all the text joined together) and a parts list, so you can show tool activity inline with the conversation:

for part in message.parts {
    switch part {
    case .text(let text):
        renderBubble(text)
    case .toolCall(_, let toolName, let input):
        renderToolCard(toolName, input: input)
    case .toolResult(_, _, let output):
        attachToolOutput(output)
    }
}

Messages with no parts are skipped, so a page can hold fewer items than limit even when hasMore is true. Base your “load more” button on hasMore, never on data.count.

See Message for the full type.

PaginatedResponse

public struct PaginatedResponse<T: Sendable>: Sendable {
    public let data: [T]
    public let hasMore: Bool
    public let total: Int

    public func loadMore() async throws -> PaginatedResponse<T>?
}

[T]

required

The items on this page.

Bool

required

Whether there are more pages.

Int

required

How many items there are in total.

loadMore

public func loadMore() async throws -> PaginatedResponse<T>?

Gets the next page, or nil when hasMore is false. The page keeps its own cursor, so you have nothing to pass along.

loadMore() returns only the next page’s items. It does not build up a full list. Add next.data to your own array yourself, at the top or bottom depending on the list.

var page = try await client.listConversations(limit: 20)
var all = page.data

while let next = try await page.loadMore() {
    all.append(contentsOf: next.data)
    page = next
}

print("Loaded \(all.count) of \(page.total)")

The limit you passed the first time is reused for every later page, so page sizes stay the same.

ConversationListState and ConversationState build up the list for you, and skip messages you already have. Use them unless you need something custom.

Infinite scroll in SwiftUI

struct ConversationList: View {
    @State var state: ConversationListState

    var body: some View {
        List {
            ForEach(state.conversations) { conversation in
                ConversationRow(conversation)
            }

            if state.hasMore {
                ProgressView()
                    .task { await state.loadMore() }
            }
        }
        .task { await state.load() }
    }
}

Conversation Status

A conversation that has ended, or that a person has taken over, cannot take new messages. Sending to one fails with 403 CHAT_CONVERSATION_NOT_ONGOING. Check before showing a text field:

if conversation.status == .ongoing {
    showComposer()
} else {
    showReadOnlyBanner()
}

Status	What it means
`.ongoing`	Active, and takes new messages.
`.ended`	Closed. Start a new conversation.
`.takenOver`	A person took over from the dashboard.

Conversation & Pagination

The full type reference

SwiftUI

Ready-made state for lists and history

Streaming

Send messages and stream replies

User Identity

Tie conversations to users

Getting Started

Reference

Conversations & History

Starting and Continuing Conversations

newConversation

listConversations

listMessages

PaginatedResponse

loadMore

Infinite scroll in SwiftUI

Conversation Status

Conversation & Pagination

SwiftUI

Streaming

User Identity

​Starting and Continuing Conversations

​newConversation

​listConversations

​listMessages

​PaginatedResponse

​loadMore

​Infinite scroll in SwiftUI

​Conversation Status

​Related

Conversation & Pagination

SwiftUI

Streaming

User Identity

Starting and Continuing Conversations

newConversation

listConversations

listMessages

PaginatedResponse

loadMore

Infinite scroll in SwiftUI

Conversation Status

Related