iOS SDK Overview

Beta Release. The Chatbase iOS SDK is currently in beta (v0.1.0-beta.1). APIs may change in future releases.

Conversation methods apply exclusively to conversations created through the mobile SDKs (iOS and Android). Conversations generated through the widget, the API, or external integrations cannot be accessed using the SDK. A user identified on both platforms sees their iOS and Android SDK conversations together.

What is the Chatbase iOS SDK?

The Chatbase iOS SDK is a Swift library that lets you add Chatbase agents to your iOS or macOS app. It gives you:

Real-time streaming with async/await and per-chunk callbacks
Client-side tools that let the agent run functions on the device
User identity with JWT sign-in and an automatic device ID
Conversation management with paginated history
Ready-made SwiftUI state through ConversationState and ConversationListState
Typed errors for everything that can go wrong

Requirements:

Requirement	Minimum
iOS	17.0
macOS	14.0
Swift	6.0
Xcode	16
SwiftUI	Not required. The SDK works with UIKit or any UI framework.

Everything in the SDK lives in one module, ChatbaseSDK. A single import ChatbaseSDK gives you every type in these docs.

Installation

The SDK ships as a Swift Package.

Xcode
Package.swift

File → Add Package Dependencies…

Paste the repository URL:

https://github.com/Chatbase-co/chatbase-ios-sdk.git

Choose version 0.1.0-beta.1 (or Up to Next Minor) and add the ChatbaseSDK library to your app target.

// Package.swift
dependencies: [
    .package(
        url: "https://github.com/Chatbase-co/chatbase-ios-sdk.git",
        from: "0.1.0-beta.1"
    )
],
targets: [
    .target(
        name: "YourApp",
        dependencies: [
            .product(name: "ChatbaseSDK", package: "chatbase-ios-sdk")
        ]
    )
]

Then import it:

import ChatbaseSDK

No Info.plist changes are needed. The SDK talks to https://www.chatbase.co over HTTPS, which iOS allows by default.

Quick Start

Get your Agent ID

Go to the Chatbase Dashboard
Select your agent
Go to Settings → General
Copy the Agent ID

Enable the iOS SDK channel

In the dashboard, go to Deploy → iOS SDK and enable the channel for your agent.

If the iOS SDK channel is not enabled, every SDK request fails with a 404 AGENT_NOT_FOUND error, even when the agent ID is correct.

Create a client

import ChatbaseSDK

let client = ChatbaseClient(agentId: "YOUR_AGENT_ID")

Create the client once and keep it around, in a view model, an app-level dependency, or a @State property. A new client starts anonymous, tied to a device ID that stays the same across launches.

Send your first message

let response = try await client.send("Hello! How can you help me?") { cb in
    cb.onTextDelta = { chunk in
        // Runs for each chunk of text as it arrives
        print(chunk, terminator: "")
    }
}

print(response.message.text)
print("Conversation: \(response.conversationId)")
print("Credits used: \(response.usage.credits)")

Continue the conversation

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

For UI code, use ConversationState instead. It keeps the conversation ID for you, along with the message list.

There is no close() or cleanup call. The client shuts down its network session when it goes out of scope.

ChatbaseClient

final class ChatbaseClient The main entry point. You can call it from any task or actor.

init

public init(
    agentId: String,
    baseURL: String = "https://www.chatbase.co/api/sdk",
    configuration: URLSessionConfiguration = .default,
    maxToolLoopSteps: Int = 10
)

String

required

The Chatbase agent ID to connect to.

String

default:"https://www.chatbase.co/api/sdk"

The Chatbase API address. Leave this at its default.

URLSessionConfiguration

default:".default"

The URLSessionConfiguration used for every request. Set timeouts and caching here.

Int

default:"10"

How many times a single send or retry may run tools before giving up. Going over throws ChatError.toolLoopLimitExceeded(limit:). See Client-Side Tools.

// Custom timeouts
let config = URLSessionConfiguration.default
config.timeoutIntervalForRequest = 30
config.timeoutIntervalForResource = 300

let client = ChatbaseClient(
    agentId: "YOUR_AGENT_ID",
    configuration: config,
    maxToolLoopSteps: 20
)

timeoutIntervalForRequest measures the gap between pieces of data, not the length of the whole response. A long streaming reply will not be cut off by a 30 second timeout as long as data keeps arriving.

Properties

Property	Type	Description
`deviceId`	`String`	The device ID. Always available.
`authState`	`AuthState`	`.anonymous` or `.identified(token:)`.
`currentConversationId`	`String?`	The last conversation the client saw, or `nil`.
`currentUserId`	`String?`	The user ID the server confirmed on the last completed reply.

Methods

Method	Description
`send(_:conversationId:configure:)`	Send a message, stream the reply, run tools. See Streaming.
`retry(conversationId:messageId:configure:)`	Ask the agent to answer again. See Streaming.
`sendNonStreaming(_:conversationId:)`	Get the whole reply at once, with no streaming and no tools. See Streaming.
`tool(_:handler:)`	Register a tool the agent can run. See Client-Side Tools.
`identify(token:)`	Sign a user in with a JWT. See User Identity.
`logout()`	Go back to anonymous. See User Identity.
`newConversation()`	Clear `currentConversationId`. See Conversations.
`listConversations(cursor:limit:)`	List past conversations. See Conversations.
`listMessages(conversationId:cursor:limit:)`	Load a conversation’s messages. See Conversations.

Logging

The SDK writes to Apple’s logging system under the subsystem com.chatbase.sdk, in three categories:

Category	What it logs
`APIClient`	Each request and response: method, path, status, duration, size
`ChatService`	Stream decoding failures and tool result retries
`ConversationState`	Skipped retries and similar UI state notes

View them in Console.app, or run log stream --predicate 'subsystem == "com.chatbase.sdk"'. Message text is never logged.

Rate Limits

Chatbase allows 1,000 requests every 10 seconds per device. Going over throws an APIError.httpError with status 429. See Error Handling.

Next Steps

Streaming

Stream replies with async/await and callbacks

SwiftUI

Ready-made state for chat screens

Client-Side Tools

Let the agent run functions on the device

Conversations

Conversations, history, and pagination

User Identity

Sign users in with JWT tokens

Error Handling

Error types and how to handle them

Getting Started

Reference

What is the Chatbase iOS SDK?

Installation

Quick Start

ChatbaseClient

init

Properties

Methods

Logging

Rate Limits

Next Steps

Streaming

SwiftUI

Client-Side Tools

Conversations

User Identity

Error Handling

​What is the Chatbase iOS SDK?

​Installation

​Quick Start

​ChatbaseClient

​init

​Properties

​Methods

​Logging

​Rate Limits

​Next Steps

Streaming

SwiftUI

Client-Side Tools

Conversations

User Identity

Error Handling

What is the Chatbase iOS SDK?

Installation

Quick Start

ChatbaseClient

init

Properties

Methods

Logging

Rate Limits

Next Steps