iOS SDK reference

Every public declaration of the iOS SDK, GraineInApp 0.10.3, and of its optional WebRTC package for calls, GraineInAppRTC, read from their source and grouped by what you are doing: installing it, saying who the customer is, the chat, the voice bar, several agents, screen context and actions, calls in both directions, booking, the scheduled-calls list, design and going live. Every entry starts with what it is for, then its signature, its parameters, what it returns, the errors it can raise and an example; each type sits with the use case that returns or takes it, field by field, with what to expect. A value newer than the SDK — a status, a source, an error code — never crashes it: it arrives as unknown, carrying its word. The Objective-C interface is the appendix. The same API across every platform, topic by topic, is the SDK reference; installing and setting up is iOS.

Requirements, install, permissions and initialisation

Install — Swift Package Manager (primary)

Use it to add the SDK with Xcode or a Package.swift — the primary way to install it.

Xcode → File → Add Package Dependencies… → https://github.com/GraineAI/inapp-ios, version 0.10.3 or later, and add the GraineInApp library to your app target. In a Package.swift:

Package.swift

dependencies: [
    .package(url: "https://github.com/GraineAI/inapp-ios", from: "0.10.3"),
],
targets: [
    .target(name: "AcmeApp", dependencies: [.product(name: "GraineInApp", package: "inapp-ios")]),
]

Install — CocoaPods

Use it when your app already manages its dependencies with CocoaPods.

CocoaPods — Podfile

platform :ios, '15.0'
target 'AcmeApp' do
  use_frameworks!
  pod 'GraineInApp', '~> 0.10'
  # or straight from the tag:
  # pod 'GraineInApp', :git => 'https://github.com/GraineAI/inapp-ios.git', :tag => '0.9.0'
end

The pod builds exactly what the Swift package builds (the same sources, iOS 15, Swift 5.9) and carries the privacy manifest in its own resource bundle, GraineInApp_Privacy.

Add WebRTC calls (optional)

Add it so the native calls — the customer calling your agent, and your agent ringing the customer — carry their audio over WebRTC and hold up on a weak or changing network.

Package.swift

dependencies: [
    .package(url: "https://github.com/GraineAI/inapp-ios", from: "0.10.3"),
    .package(url: "https://github.com/GraineAI/inapp-ios-rtc", from: "0.10.3"),   // the same version as GraineInApp
],
targets: [
    .target(name: "AcmeApp", dependencies: [
        .product(name: "GraineInApp", package: "inapp-ios"),
        .product(name: "GraineInAppRTC", package: "inapp-ios-rtc"),
    ]),
]

In Xcode: File → Add Package Dependencies… → https://github.com/GraineAI/inapp-ios-rtc, the same version as GraineInApp, and add the GraineInAppRTC library to the same target as GraineInApp. With CocoaPods, beside pod 'GraineInApp':

CocoaPods — Podfile

pod 'GraineInApp', '~> 0.10'
pod 'GraineInAppRTC', :git => 'https://github.com/GraineAI/inapp-ios-rtc.git', :tag => '0.10.3'   # the same version as GraineInApp, from its repository

Nothing else changes: no code, no Info.plist entry, no capability and no permission beyond the calls' own (Permissions and capabilities). The calls find the module by themselves. A build that strips code nothing references can make sure of it at launch:

import GraineInAppRTC
 
GraineRTC.install()   // optional: only for a build that strips code nothing references

• What it is. A separate package, so GraineInApp keeps no dependencies and an app that does not add it never downloads it. It carries a prebuilt WebRTC library (Google's WebRTC, BSD 3-Clause, its symbols renamed so it never clashes with another copy in the app). Its licences are in the package's THIRD-PARTY-NOTICES.md: include them in your app's open-source notices. If another package in your app pins the same WebRTC build at a different version, the two cannot be resolved together: leave the module out (the calls stay on the WebSocket) or align the versions.
• Size. About 12 MB more installed on an arm64 iPhone, and about 6 MB more to download.
• Privacy. It ships its own privacy manifest (with CocoaPods, in the GraineInAppRTC_Privacy bundle): the system boot time (reason 35F9.1), to time the call's steps; no tracking and no tracking domains.
• Which calls. Both directions of the native calls (GraineCalls): a call the customer places with startCall, and a call Graine rang — a booked call or "Ring now" — that the customer answers. The voice bar's in-app call (GraineVoice) is not affected; GraineConfig.transport chooses its audio.
• Choosing. GraineCallsConfig.callTransport: .auto (the default) uses WebRTC when the module is in the app and the dashboard allows it, else the WebSocket; .websocket always the WebSocket; .webrtc WebRTC wherever it can carry the call. See GraineCallTransport.
• The dashboard's switch. The agent's In-app call audio setting (agent → Calls & scheduling): WebRTC (recommended) or Standard. Standard moves every install's calls back to the WebSocket, whatever the app chose, from each app's next start — no app release. The app reads it as GraineHostedCallsSettings.audioTransport.
• What the customer notices. The same ring, the same call screen, the same "Connecting…". On a weak or changing network the agent's voice holds up instead of stalling and catching up (a jitter buffer, loss concealment and the platform's echo canceller). The call is prepared at the tap — or while a ring is showing — so it connects as fast as before. Over WebRTC the agent's voice arrives at telephone bandwidth today: steadier through a weak network, narrower than the WebSocket's on a perfect one.
• When WebRTC cannot carry a call. A network that blocks it, a server that turns it down, or no answer within the time allowed (about 12 seconds in all), before any audio flows: the call continues on the WebSocket inside the same call — no second ring, no new call screen, no error; "Connecting…" shows a moment longer — and GraineCalls.transportFallbackReason says why. A call the agent cannot take at all (no credit left, the agent switched off) ends with that reason, exactly as without the module. Once audio flows a call never moves: a network drop is retried once, then the call ends as dropped.

Permissions and capabilities

Read it to add what the agent and calls need to the app target before you submit the app.

XML — Info.plist

<key>NSMicrophoneUsageDescription</key>
<string>Lets you talk to the assistant in the app and on calls.</string>
<key>UIBackgroundModes</key>
<array>
    <string>audio</string>
    <string>voip</string>
</array>

Nothing else: no notification permission (VoIP pushes and CallKit need none), no Bluetooth usage description, no remote-notification background mode — and the WebRTC package adds nothing to this list. The SDK ships a privacy manifest declaring the required-reason APIs it calls — system boot time (reason 35F9.1, for timing) and UserDefaults (reason CA92.1) — and no tracking and no tracking domains; Xcode adds it to your app's privacy report. What your app collects through the agent, the customer's voice included, goes in your App Privacy details.

What the SDK configures in CallKit

Read it to know how a call looks and behaves on the system's call screen, and which of your settings change it.

• Every VoIP push is reported to CallKit at once. iOS requires it and stops delivering VoIP pushes to an app that does not. The SDK reports every one — even one it cannot use, or one that arrives during a live call (that one is ended at once and reported missed; the live call is untouched). Send VoIP pushes only for calls. An app with its own PKPushRegistry hands the payload to reportIncomingCall(payload:completion:) instead.
• On the lock screen the ring is the system's incoming-call screen (a banner while the phone is in use), with your call name, icon and ringtone. Answered there, the call connects; the system call screen stays on the lock screen for the call, and your app shows GraineCallView when it is opened. Do Not Disturb, a Focus or the block list can stop a ring; it is then reported missed.
• The microphone: for a call the customer places, the SDK asks before placing it. For a ring, the customer answers first; the SDK reports answered, iOS asks while the call connects, and a refusal — or no answer within 60 seconds — ends it failed. Ask during onboarding so a call answered on the lock screen already has it.
• Apple does not allow CallKit in apps on the App Store in China: leave calls off there.

Initialise

Use it as the starting point: configure the agent at launch, and mount the bar and the call screen once.

iOS · Swift — AcmeApp.swift

import SwiftUI
import GraineInApp
 
@main
struct AcmeApp: App {
    @UIApplicationDelegateAdaptor(AppDelegate.self) private var appDelegate
    var body: some Scene { WindowGroup { RootView() } }
}
 
final class AppDelegate: NSObject, UIApplicationDelegate {
    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {
        let graine = GraineInApp.configure(GraineConfig(
            baseUrl: "https://www.graine.ai",
            publishableKey: "pk_live_…",          // Agent → Embed & Widgets → Install
            appVersion: "2.4.0"
        ))
        graine.calls.configure(GraineCallsConfig(displayName: "Asha from Acme"))
        graine.calls.enableVoIPPushes()           // every launch: iOS hands over a VoIP push only once this has run
        return true
    }
}
 
struct RootView: View {
    @ObservedObject private var calls = GraineInApp.shared.calls
    var body: some View {
        AppContent()
            .overlay(GraineAgentBar())            // the bar: voice, chat and components, in your design
            .fullScreenCover(isPresented: .constant(calls.showsCallScreen)) {
                GraineCallView()                  // the call while your app is open
            }
    }
}

The bar mounts the voice engine in the key window the first time it appears (autoAttach), so a call carries on as the customer moves through your app. UIKit apps host the SwiftUI views in a UIHostingController, or use GraineChatViewController; without the bar, mount the engine with GraineInApp.shared.voice.attach().

Install and the first answer

Configure the agent once, at launch, and know when its settings from the dashboard have arrived. The agent starts loading its settings the moment configure runs; every request waits for them.

GraineInApp.configure

Call it once at launch to set up an agent; everything else goes through the instance it returns.

@discardableResult static func configure(_ config: GraineConfig, name: String = "default") -> GraineInApp

Configures an agent. Call it once, at launch (App.init or application(_:didFinishLaunchingWithOptions:)). Without a name it is the default agent — the one shared returns and every view draws unless handed another; an app with several agents configures each under its own name and publishable key. The name is trimmed, and an empty name is the default. Calling it again with a name that is already configured gives back that same agent, untouched. A new agent takes on who is signed in, the memory choice and the current screen, and starts loading its settings from Graine.

Returns — GraineInApp: the agent's instance. Keep it, or reach it later as GraineInApp.shared (the default agent) or GraineInApp.named(_:).

Errors — none.

let graine = GraineInApp.configure(GraineConfig(baseUrl: "https://www.graine.ai", publishableKey: "pk_live_…"))

GraineConfig (constructor)

Use it to build the configuration you pass to configure.

init(baseUrl: String, publishableKey: String, variables: [String: Any] = [:], transport: GraineTransport? = nil, appVersion: String? = nil, endOnBackground: Bool = true, timing: Timing = Timing(), debug: Bool = false, friction: GraineFrictionConfig? = nil, fonts: [String: String] = [:], captureTaps: Bool = true, chatSize: GraineChatSize? = nil)

Builds a configuration.

Returns — a new GraineConfig.

Errors — none.

let config = GraineConfig(baseUrl: "https://www.graine.ai", publishableKey: "pk_live_…",
                          appVersion: "2.4.0", debug: true)

GraineConfig.Timing (constructor)

Use it only for a very slow network, to give the engine page that carries the in-app call longer to load.

init(stallMs: Int = 15_000, bootMs: Int = 15_000, hardCapMs: Int = 120_000, retryDelaysMs: [Int] = [1_000, 2_000, 4_000, 8_000, 15_000, 15_000], endWatchdogMs: Int = 4_000, slowConnectMs: Int = 4_000)

Builds the load timing for the engine page that carries the in-app call, in milliseconds — for a very slow network. Most apps keep the defaults.

Returns — a new GraineConfig.Timing.

Errors — none.

let config = GraineConfig(baseUrl: "https://www.graine.ai", publishableKey: "pk_live_…",
                          timing: GraineConfig.Timing(stallMs: 25_000, bootMs: 25_000))

GraineInApp.session

Read it to know whether the agent's settings from the dashboard have arrived, and what they say.

var session: GraineSessionConfig? { get }

The agent's settings, loaded once per launch, starting the moment configure runs; nil until they arrive. Every request to Graine made before then waits for them, so you never have to. GraineListener.onSessionReady tells you when they arrive — the moment to read bookingAvailable, schedulingRules, theme and checkActions(). If they cannot be loaded, onError says why and the next request tries again. Readiness of the voice engine is separate: GraineVoice.ready and GraineVoice.connectivity.

Parameters — none.

Returns — GraineSessionConfig? — its fields: GraineSessionConfig. Example value: nil before the settings load.

Errors — none.

if let session = GraineInApp.shared.session {
    print("Agent \(session.agentId), memory: \(session.memoryEnabled ?? false)")
}

GraineInApp

Use it as the SDK's entry point: one instance per configured agent, reached as GraineInApp.shared or GraineInApp.named(_:).

The SDK's entry point: one instance per configured agent, made by GraineInApp.configure(_:name:) at launch and reached as GraineInApp.shared (the default agent) or GraineInApp.named(_:). Its methods may be called from any thread; voice, calls and chat are main-thread objects, and listeners are called on the main thread.

What to expect — The SDK's entry point, configured once at launch; everything else goes through it, or through the agent you name. A request to Graine made before the agent's settings have loaded waits for them.

Its functions: configure, named, addListener, removeListener, identify, setMemory, forgetMemory, memories, setVariables, currentVariables, setScreen, updateField, removeField, clearScreen, track, tap, noteInteraction, configureFriction, answerComponent, reopenComponent, registerAction, checkActions, scheduleCall, scheduledCalls, cancelScheduledCall, presentBooking — each with its parameters, response, errors and an example.

GraineConfig

Read it to see every option the SDK takes at launch and what each one changes.

Everything the SDK needs up front, passed to GraineInApp.configure(_:name:) and kept as GraineInApp.config. A value type; only baseUrl and publishableKey are required.

What to expect — Made once, at launch, before anything else. Optional fields have the defaults shown; nothing in it is sent to Graine except what the descriptions say.

Its functions: init — each with its parameters, response, errors and an example.

GraineConfig.Timing

Read it to tune how patiently the engine page loads on a poor network.

Load timing for the engine page that carries the in-app call, in milliseconds, set as GraineConfig.timing. Most apps keep the defaults.

What to expect — Made once, at launch, before anything else. Optional fields have the defaults shown; nothing in it is sent to Graine except what the descriptions say.

Its functions: init — each with its parameters, response, errors and an example.

GraineSessionConfig (constructor)

Use it to build agent settings by hand for SwiftUI previews and tests, without the network.

init(agentId: String, webcallAgentId: String, appearance: [String: Any] = [:], variables: [String: Any] = [:], pageVersion: String? = nil, declaredActions: Set<String> = [], friction: [String: Any]? = nil, design: GraineDesign? = nil, wsHost: String? = nil, identity: GraineIdentitySettings? = nil, memoryEnabled: Bool? = nil, calls: GraineHostedCallsSettings? = nil)

Builds settings by hand — for previews and tests; the SDK makes the real ones.

Returns — a new GraineSessionConfig.

Errors — none.

let preview = GraineSessionConfig(agentId: "agent_1", webcallAgentId: "agent_1", memoryEnabled: true,
                                  calls: nil)   // no ringing, no booking

GraineSessionConfig

Read it to see what the dashboard says about the agent, once its settings have loaded.

The agent's settings from the dashboard, fetched once per launch: GraineInApp.session and GraineListener.onSessionReady(_:). Missing fields are empty, never a crash.

What to expect — The agent's settings from the dashboard, loaded once per launch; null / nil until then. A setting an older server does not send means its default: the user_id trait, 2 devices per user, booking off. Missing fields are empty, never a crash.

Its functions: init — each with its parameters, response, errors and an example.

Identity, memory and conversations that continue

Say who the customer is, let them choose whether they are remembered, show and forget what the agent remembers, and continue — or restart — the conversation they had.

GraineInApp.identify

Call it whenever the signed-in customer changes, so memory, bookings and the calls Graine rings follow the right person.

func identify(_ traits: [String: Any?]?, memory: Bool? = nil)

Who is signed in, for every configured agent. The trait the agent's Identity setting names (user_id unless the dashboard says email, phone or a custom trait) identifies the customer for memory and for the calls Graine rings: its value travels only with the requests that start a conversation, never as a prompt variable. Every other trait becomes a prompt variable, masked on the device; nested objects and arrays are dropped. A placeholder value ("guest", "null", a masked "[EMAIL]") is no identity, and those conversations are anonymous. memory: false means this customer's conversations are neither remembered nor recalled; nil keeps their last choice (true until they make one). The identity is fixed per conversation: a change applies to the next one. identify(nil) signs out: the device stops being that customer's, Graine is told, and later conversations are anonymous. When a different customer signs in, or the customer signs out, the chat transcript on screen is cleared.

Returns — nothing; it returns when done.

Errors — none.

GraineInApp.shared.identify(["user_id": user.id, "name": user.firstName, "plan": user.plan], memory: user.allowsMemory)
// on sign-out, and before another customer signs in
GraineInApp.shared.identify(nil)

GraineInApp.setMemory

Call it when the customer turns being remembered on or off in your app's settings.

func setMemory(_ enabled: Bool)

Whether the current customer's conversations are remembered, for every agent — the same as calling identify again with memory: enabled. Kept on the device for that customer; applies to the next conversation.

Returns — nothing; it returns when done.

Errors — none.

GraineInApp.shared.setMemory(true)

GraineInApp.memoryChoice

Read it to show the current state of a "Remember my conversations" switch.

var memoryChoice: Bool { get }

The current customer's memory choice: true until they turn it off with setMemory(false) or identify(_:memory: false). Kept on the device for each customer, so the next customer who signs in on the same phone has their own. When false, nothing is recalled or stored for them.

Parameters — none.

Returns — Bool. Example value: true.

Errors — none.

rememberSwitch.isOn = GraineInApp.shared.memoryChoice

GraineInApp.installId

Read it to tell your support team which install a customer is using.

var installId: String { get }

This install's id: a UUID made on first launch and kept in the Keychain (this device only), so it survives reinstalls. The same for every agent. Graine counts a customer's devices by it (Devices per user); the agent never sees it. If the Keychain cannot keep it, that launch uses a new one.

Parameters — none.

Returns — String. Example value: "9b2e7c4a-1f3d-4e8a-b6c5-0d7f2a9e4b13".

Errors — none.

supportInfo["install"] = GraineInApp.shared.installId

GraineInApp.memories

Call it to show the customer what the agent remembers about them.

func memories() async throws -> [GraineMemory]

What the agent remembers about the signed-in customer, newest first, at most 100, already redacted — to show people what is kept about them. Waits for the agent's settings first, and throws identity_required before sending anything when nobody is identified ("Nobody is identified: call identify() with the customer's identifier first.").

Parameters — none.

Returns — [GraineMemory] — its fields: GraineMemory. Example value: [GraineMemory(id: "m_41", text: "Prefers a call after 6 pm", createdAt: 2026-10-02 09:14:00 +0000, updatedAt: 2026-10-12 17:40:00 +0000)].

Errors — GraineServiceError: identity_required, device_limit, rate_limited, network, unavailable, invalid_key, origin_refused

let memories = try await GraineInApp.shared.memories()

GraineInApp.forgetMemory

Call it when the customer asks the agent to forget them.

@discardableResult func forgetMemory() async throws -> Int

Deletes everything this agent's memory holds about the signed-in customer. Waits for the agent's settings first. Throws identity_required before sending anything when nobody is identified, and device_limit from a device that is not one of the customer's. Returns how many memories were deleted (0 when Graine does not say). The kept conversation goes too, and the chat on screen clears — only when it succeeds; a refusal leaves both as they were.

Parameters — none.

Returns — Int. Example value: 3.

Errors — GraineServiceError: identity_required, device_limit, rate_limited, network, unavailable, invalid_key, origin_refused

let deleted = try await GraineInApp.shared.forgetMemory()   // 3

GraineChat.newConversation

Call it when the customer wants a fresh start instead of continuing the earlier conversation.

func newConversation() async throws

Starts a fresh thread: the chat hangs up, Graine lets go of the conversation it kept for this agent and customer, the chat on screen clears and — when the customer was in the chat — a fresh chat opens with the welcome and the starters. Memories are untouched. With nobody identified only the screen clears. On a refusal the chat is as it was, connected again. While GraineChatView shows an earlier conversation, its header offers this.

Parameters — none.

Returns — nothing; it returns when done.

Errors — GraineServiceError: device_limit, rate_limited, network, unavailable, invalid_key, origin_refused — the chat is then as it was, connected again.

try await GraineInApp.shared.chat.newConversation()

GraineMemory (constructor)

Use it to build sample memories for previews and tests of a "what we remember" screen.

init(id: String, text: String, createdAt: Date? = nil, updatedAt: Date? = nil)

Builds a memory by hand — for previews and tests of a screen that lists what is remembered; memories() makes the real ones.

Returns — a new GraineMemory.

Errors — none.

let preview = GraineMemory(id: "m_41", text: "Prefers a call after 6 pm", createdAt: Date())

GraineMemory

Read it to show one thing the agent remembers about the customer.

One thing the agent remembers about the signed-in customer, already redacted — returned by GraineInApp.memories(), to show people what is kept about them beside forgetMemory(). A value type.

What to expect — From memories(): newest first, at most 100, already redacted. Only for the identified customer, from one of their devices. The dates are null when Graine did not say; they are moments in UTC — show them in the device's time zone.

Its functions: init — each with its parameters, response, errors and an example.

GraineIdentitySettings (constructor)

Use it to build identity settings for previews and tests.

init(field: String = "user_id", devicesPerUser: Int = 2)

Builds a setting; a field that is not a valid trait name becomes user_id, and devicesPerUser is held to 1–5.

Returns — a new GraineIdentitySettings.

Errors — none.

let settings = GraineIdentitySettings(field: "email", devicesPerUser: 3)

GraineIdentitySettings

Read it to learn which trait identifies the customer, and how many devices they may use.

The agent's Identity setting: which trait passed to identify names the customer, and how many devices they may use. In GraineSessionConfig.identity.

What to expect — The agent's settings from the dashboard, loaded once per launch; null / nil until then. A setting an older server does not send means its default: the user_id trait, 2 devices per user, booking off. Missing fields are empty, never a crash.

Its functions: init — each with its parameters, response, errors and an example.

Chat

The typed conversation: open it, send, follow its state, and draw it — with the SDK's own chat screen or your own.

GraineChat.open

Call it when the customer opens your chat screen, so the conversation connects.

func open(size: GraineChatSize? = nil)

Puts the customer in the chat, connecting and keeping the connection up. A mounted GraineAgentBar moves to the chat (where the agent offers one) and draws it at size until close(); nil follows GraineConfig.chatSize, then the dashboard's. Ends any in-app call and closes other agents' chats. A dropped connection is made again 1, 2, 4, 8, 15 and 15 seconds apart, then the status is offline until the customer sends something or you call retry().

Returns — nothing; it returns when done.

Errors — none.

GraineInApp.shared.chat.open(size: .full)

GraineChat.close

Call it when the customer leaves the chat, so it hangs up.

func close()

The customer has gone: the chat disconnects and remains disconnected. What was said stays on screen.

Parameters — none.

Returns — nothing; it returns when done.

Errors — none.

GraineInApp.shared.chat.close()

GraineChat.send

Call it to send what the customer typed.

func send(_ text: String)

Sends a message. It is shown at once and sent now, or as soon as the chat is connected (opening and connecting it if needed). Empty text is ignored. Up to 20 messages wait while the chat is down; older ones are marked failed.

Returns — nothing; it returns when done.

Errors — none.

GraineInApp.shared.chat.send("Where is my order?")

GraineChat.retry

Call it from a "Try again" control when messages could not be sent.

func retry()

Connects now, and sends what could not be sent.

Parameters — none.

Returns — nothing; it returns when done.

Errors — none.

GraineInApp.shared.chat.retry()

GraineChat.clear

Call it to empty the chat on screen — a new topic, a tidy screen — while the conversation goes on.

func clear()

Empties the chat on screen: its turns and the typing bubble go. Only the screen. The conversation goes on — connected stays connected — a message still waiting for the connection is still sent, and nothing Graine keeps is touched: the conversation that continues comes back with the next history, and the agent's memories stay. newConversation() starts over; forgetMemory() forgets. Safe from any thread (it hops to the main thread).

Parameters — none.

Returns — nothing; it returns when done.

Errors — none.

GraineInApp.shared.chat.clear()   // the chat stays connected; only what is on screen goes

GraineChatView (constructor)

Use it to show the whole chat, drawn in your agent's design, in a SwiftUI app.

init(graine: GraineInApp? = nil, accent: Color? = nil, onClose: (() -> Void)? = nil)

The chat as a SwiftUI screen, drawn in the agent's design. It connects when it appears and hangs up when it goes; it draws nothing before an agent is configured.

Returns — a new GraineChatView.

Errors — none.

.sheet(isPresented: $chatOpen) {
    GraineChatView(onClose: { chatOpen = false })
}

GraineChatViewController (constructor)

Use it to show the chat in a UIKit app.

init(graine: GraineInApp? = nil)

The chat screen for UIKit, drawn in the agent's design. Presented, it is a page sheet with a close control; pushed, the navigation bar's back button closes it.

Returns — a new GraineChatViewController.

Errors — none.

present(GraineChatViewController(graine: GraineInApp.named("support")), animated: true)

GraineChatRows.build

Call it to lay out a chat of your own exactly as the SDK's chat window draws it.

static func build(_ turns: [GraineChatTurn], now: Date = Date(), calendar: Calendar = .current) -> [GraineChatRow]

The rows a chat window draws for turns, in order: a bubble for each chat message (.turn); one row for a run of an earlier call's voice turns on one day (.voice — that a call happened and when, never what was said); and a day line (.day — Today, Yesterday or a date) before the first row when it is not from today, and wherever the device's day changes between rows. A conversation all from today is exactly its bubbles. GraineChatView and the bar's chat window draw these same rows. Rebuild whenever turns changes; each row's id stays the same as the conversation grows.

Returns — [GraineChatRow] — its cases: GraineChatRow. Example value: [.day(…yesterday…), .voice(…), .day(…today…), .turn(…), .turn(…)] for an earlier call yesterday and two messages today.

Errors — none.

struct MyChat: View {
    @ObservedObject var chat = GraineInApp.shared.chat
    var body: some View {
        List(GraineChatRows.build(chat.turns)) { row in
            switch row {
            case .day(let line): Text(GraineChatRows.dayLabel(line)).font(.caption)
            case .voice(let call): Text(GraineChatRows.callLabel(call)).accessibilityLabel(GraineChatRows.callSpoken(call))
            case .turn(let turn): Text(turn.text)
            }
        }
    }
}

GraineChatRows.dayLabel

Call it for the words of a day line, in the device's language.

static func dayLabel(_ line: GraineChatDayLine, now: Date = Date(), calendar: Calendar = .current, locale: Locale = .current) -> String

"Today", "Yesterday", else the date in the device's words ("Tue 14 Oct"), with the year when it is not this year's.

Returns — String. Example value: "Tue 14 Oct".

Errors — none.

for case .day(let line) in GraineChatRows.build(GraineInApp.shared.chat.turns) {
    print(GraineChatRows.dayLabel(line))   // "Today", "Yesterday" or "Tue 14 Oct"
}

GraineChatRows.callLabel

Call it for the words of an earlier call's row.

static func callLabel(_ line: GraineChatCallLine, calendar: Calendar = .current, locale: Locale = .current) -> String

"Voice call · 6:05 PM": the time of the call's first turn, in the device's short time.

Returns — String. Example value: "Voice call · 6:05 PM".

Errors — none.

for case .voice(let call) in GraineChatRows.build(GraineInApp.shared.chat.turns) {
    print(GraineChatRows.callLabel(call))   // "Voice call · 6:05 PM"
}

GraineChatRows.callSpoken

Call it for what VoiceOver should say for an earlier call's row.

static func callSpoken(_ line: GraineChatCallLine, calendar: Calendar = .current, locale: Locale = .current) -> String

"Voice call at 6:05 PM" — the row's accessibility label.

Returns — String. Example value: "Voice call at 6:05 PM".

Errors — none.

for case .voice(let call) in GraineChatRows.build(GraineInApp.shared.chat.turns) {
    print(GraineChatRows.callSpoken(call))   // "Voice call at 6:05 PM"
}

GraineChatRows.clock

Call it to write a message's time the way the chat window does.

static func clock(_ date: Date, calendar: Calendar = .current, locale: Locale = .current) -> String

A time in the device's short words — "6:05 PM", or "18:05" where the device keeps a 24-hour clock. For a message's time where the design shows timestamps (GraineChatTokens.showTimestamps).

Returns — String. Example value: "6:05 PM".

Errors — none.

if let last = GraineInApp.shared.chat.turns.last {
    print(GraineChatRows.clock(last.at))   // "6:05 PM"
}

GraineChatRows.offersStarters

Call it to know whether the brand's starters belong above your composer.

static func offersStarters(_ turns: [GraineChatTurn]) -> Bool

True while the conversation is new: the customer has not said anything, and no earlier conversation is on screen (no restored turn). The SDK's chat window shows the brand's starters (GraineChatTokens.suggestions) only then.

Returns — Bool. Example value: true in a new chat.

Errors — none.

if GraineChatRows.offersStarters(GraineInApp.shared.chat.turns),
   let starters = GraineInApp.shared.theme?.chat?.suggestions {
    print(starters)   // offer them above your composer
}

GraineChatRows.offersNewConversation

Call it to know whether your own "New conversation" control belongs on screen.

static func offersNewConversation(_ turns: [GraineChatTurn]) -> Bool

True while an earlier conversation is on screen — a restored turn, when the customer came back and the conversation continues. GraineChatView's header offers New conversation only then (and only where the design keeps it, GraineChatTokens.newConversation).

Returns — Bool. Example value: false in a new chat.

Errors — none.

let offerFreshStart = GraineChatRows.offersNewConversation(GraineInApp.shared.chat.turns)
// show your own "New conversation" control while it is true; its tap calls chat.newConversation()

GraineChat

Use it to drive and draw the typed conversation: GraineInApp.shared.chat.

The typed conversation with an agent, on its own connection: GraineInApp.shared.chat, an ObservableObject to read on the main thread (its methods may be called from any thread and hop there). One conversation runs at a time across every agent: opening the chat ends any in-app call, starting a call closes it, a native call holds it down until it is over, and with endOnBackground it hangs up in the background and comes back with the app.

What to expect — The agent's typed conversation. It connects while the customer is in the chat (open) and hangs up when they leave (close); a message typed while it is not connected is shown at once and sent when it is. Its state changes as the conversation moves: draw from it. Opening the chat ends a call the bar holds.

Its functions: open, close, send, retry, clear, newConversation, refreshUpcomingCalls, cancelUpcomingCall — each with its parameters, response, errors and an example. To draw the conversation in a chat of your own, GraineChatRows lays turns out the way the SDK's chat window does.

GraineChatSize

Use it to choose how big the chat window opens.

public enum GraineChatSize: String, CaseIterable, Sendable — how big the chat window opens. The dashboard's Window size chooses; GraineConfig.chatSize overrides it for the app, and chat.open(size:) for one open. Raw values are the design's words.

What to expect — Which size wins: the size passed to the open call, then the app's chatSize, then the agent's Window size in the Garage, else compact. An open's size lasts until the chat closes. On a phone, large is a sheet over about 92% of the screen and full the whole screen inside the safe areas; on a tablet or computer both open a panel 420 wide and up to 760 tall. A word from a newer design that the SDK does not know is passed over.

GraineChatTurn

Read it to draw one message of the chat.

One message in GraineChat.turns, made by the SDK. Each agent reply is its own turn.

What to expect — One per message, oldest first. The agent's turn updates in place (same id) while live, then stops. A customer's message typed while the chat is not connected is sending (React Native: pending) and goes as soon as it is; failed means every reconnect was spent — the next message or a retry sends it. Restored turns arrive once when the chat opens, for an identified customer on an agent with memory on, on one of their devices: at most 50, oldest first, delivered, never live, with their original times; the welcome is not sent then. Consecutive voice turns show as one "Voice call · time" row (GraineChatRows lays a conversation out that way for a chat of your own). The list empties on sign-out, when another customer signs in, after a successful forgetMemory(), on newConversation() and on clear() (the screen only: the conversation goes on).

GraineChatTurn.Delivery

Read it to show whether a customer's message is sending, sent or failed.

Where a customer's chat message is. Raw values are the wire words.

What to expect — Only on the customer's messages (the agent's are sent, or null): sending → sent; failed once every reconnect was spent.

GraineChatChannel

Read it to tell a typed message from one said on a call.

public enum GraineChatChannel: String, Sendable — where a message was said: typed in the chat, or spoken on a call (only an earlier conversation's turn is).

What to expect — chat for a typed message; voice for a message said on a call — only a restored turn can be voice.

GraineChatStatus

Read it to show whether the chat is connected, and offer a retry when it is not.

Where the chat's connection is: GraineChat.status.

What to expect — Idle until the customer is in the chat; connecting, then online. A dropped connection is retried six times — 1, 2, 4, 8, 15 and 15 seconds apart — showing reconnecting with the attempt; then offline until the customer sends something or the app retries. Opening the chat ends a call the bar holds; a native call holds the chat until it is over.

GraineRole

Read it to tell the agent's lines from the customer's.

Who said a line, in captions and chat turns. Raw values are the wire words.

What to expect — Who said it: the agent, or the customer (user).

GraineChatView

Use it as the SwiftUI chat screen.

The chat as a SwiftUI screen, drawn by the SDK in the brand's design: header, one bubble per reply, a typing bubble, the components the agent draws (answered in place) and the composer. It connects when it appears, hangs up when it goes, and draws nothing before an agent is configured.

What to expect — Push it or present it like any SwiftUI view; it fills the space it is given. The header offers New conversation while an earlier conversation is on screen, and the Upcoming calls card (with Book a call where bookingAvailable is true) when the design keeps it.

Its functions: init — each with its parameters, response, errors and an example.

GraineChatViewController

Use it as the UIKit chat screen.

The chat screen for a UIKit app, to present or push: present(GraineChatViewController(), animated: true). Presented, its close control dismisses it; pushed, the navigation bar's back button does and no close control is drawn.

What to expect — The same screen as GraineChatView, hosted for UIKit; it presents as a page sheet unless you change modalPresentationStyle.

Its functions: init, viewDidLoad — each with its parameters, response, errors and an example.

GraineChatRows

Use it to draw a chat of your own in the same rows as the SDK's chat window.

public enum GraineChatRows — static functions only: the rows a chat window draws for a conversation, and the words for them. What GraineChatView and the bar's chat window draw, public for an app that draws its own chat; every Graine SDK lays a conversation out in these same rows.

What to expect — Worked out on the device from the turns you pass; nothing is sent. "Today", "Yesterday" and "Voice call" are the SDK's words; dates and times are written in the device's language and time zone.

Its functions: build, dayLabel, callLabel, callSpoken, clock, offersStarters, offersNewConversation — each with its parameters, response, errors and an example.

GraineChatRow

Read it to draw one row of a chat window.

public enum GraineChatRow: Equatable, Identifiable — one row, as GraineChatRows.build(_:now:calendar:) returns them, oldest first.

What to expect — A day line before the first row when it is not from today, and wherever the day changes; one row per earlier call on a day, however many turns it had; one row per chat message. A conversation all from today has no day line.

GraineChatDayLine

Read it to draw a day line.

public struct GraineChatDayLine: Equatable, Sendable — the day a run of rows belongs to. Made by GraineChatRows.build; an app reads it, never makes one.

What to expect — Before the first row when it is not from today, and wherever the day changes between rows; a conversation all from today has none.

GraineChatDay

Read it to know which day a day line names.

public enum GraineChatDay: Equatable, Sendable — in GraineChatDayLine.day.

What to expect — Counted on the device's calendar and time zone when the rows were built: rebuilt after midnight, what was .today is .yesterday.

GraineChatCallLine

Read it to draw an earlier call as one row.

public struct GraineChatCallLine: Equatable, Sendable — an earlier call: when it began, and which turns it stands for — never their words. Made by GraineChatRows.build.

What to expect — Voice turns come only from an earlier conversation the chat restored; a run of them on one day is one call.

The voice bar

The agent talking inside your app: the bar that draws the call, the launcher, the voice engine behind them, the loader, the captions, how the audio travels and how good the connection is.

GraineAgentBar (constructor)

Use it to put the agent in your app: mount the bar once, at your root.

init(graine: GraineInApp? = nil, name: String? = nil, accent: Color? = nil, bottomInset: CGFloat = 16, draggable: Bool = true, initialOffset: CGFloat = 0, onPlacementChange: ((CGFloat) -> Void)? = nil, autoAttach: Bool = true, surface: GraineSurface? = nil, onClose: (() -> Void)? = nil)

The assistant bar, drawn in the agent's design: it fills the area it is given, draws only the bar, lets other touches through and rises above the keyboard. Nothing draws before an agent is configured.

Returns — a new GraineAgentBar (GraineAgentBar<EmptyView>; accessory makes one with content above it).

Errors — none.

AppContent()
    .overlay(GraineAgentBar(bottomInset: 64,
                            initialOffset: savedOffset,
                            onPlacementChange: { savedOffset = $0 }))

GraineAgentBar.accessory

Use it to ride a view of your own, such as a text field, above the bar.

func accessory<Content: View>(@ViewBuilder _ content: () -> Content) -> GraineAgentBar<Content>

Something that rides above the bar and moves with it, above the keyboard included — a text field, say.

Returns — GraineAgentBar<Content>: the same bar, with the content above it. Mount that instead of the plain bar.

Errors — none.

AppContent()
    .overlay(GraineAgentBar().accessory {
        TextField("Ask about your order", text: $draft)
            .textFieldStyle(.roundedBorder)
    })

GraineLauncher (constructor)

Use it for a floating button that starts the in-app call, when you do not mount the bar.

init(graine: GraineInApp? = nil, label: String? = nil, accent: Color? = nil, autoAttach: Bool = true, action: (() -> Void)? = nil)

The floating launcher in the agent's design: a tap places the in-app call, and during the call it is the end button. Nothing draws before an agent is configured.

Returns — a new GraineLauncher.

Errors — none.

AppContent()
    .overlay(alignment: .bottomTrailing) { GraineLauncher().padding(20) }

GraineVoice.attach

Call it to mount the voice engine in a window you choose.

func attach(to view: UIView)

Mounts the engine in that view — pass your key window, not a view a screen owns — and loads the page idle: nothing registered, nothing dialled, no microphone, so a later start() connects quickly. Attaching to a different view moves the engine there and ends a call that is under way.

Returns — nothing; it returns when done.

Errors — none.

if let window = UIApplication.shared.connectedScenes
    .compactMap({ ($0 as? UIWindowScene)?.keyWindow }).first {
    GraineInApp.shared.voice.attach(to: window)
}

GraineVoice.attach

Call it to mount the voice engine in the key window when you do not use the bar.

func attach()

Mounts the engine in the app's key window. Call it once a window exists — from a view's onAppear, say; with no window yet it reports through onError and does nothing.

Parameters — none.

Returns — nothing; it returns when done.

Errors — none.

GraineInApp.shared.voice.attach()

GraineVoice.detach

Call it to remove the voice engine, hanging up any call first.

func detach()

Removes the engine, hanging up first: a call never outlives its UI.

Parameters — none.

Returns — nothing; it returns when done.

Errors — none.

GraineInApp.shared.voice.detach()

GraineVoice.start

Call it from your own control to start the in-app voice call.

func start()

Places the call. Asks for the microphone first if the app does not hold it; refused, no call is placed and onMicDenied is called. A start before the page is ready is held and placed when it is. Ends any other conversation — another agent's call, every chat. Refused through onError when the engine is not attached or a native call (calls) is live.

Parameters — none.

Returns — nothing; it returns when done.

Errors — none.

GraineInApp.shared.voice.start()

GraineVoice.end

Call it from your own control to hang up the in-app call.

func end()

Hangs up. If the page does not confirm within Timing.endWatchdogMs (4 s), the call is ended locally — state, onEnded, and a reload that drops the audio. If a start was only on hold, it is just cancelled.

Parameters — none.

Returns — nothing; it returns when done.

Errors — none.

GraineInApp.shared.voice.end()

GraineVoice.setMuted

Call it from your own mute control during the in-app call.

func setMuted(_ value: Bool)

Stops (or resumes) sending the customer's voice without ending the call.

Returns — nothing; it returns when done.

Errors — none.

GraineInApp.shared.voice.setMuted(true)

GraineVoice.retry

Call it from a "Try again" control after the engine page failed to load.

func retry()

Reloads the engine page and starts its reloads over (GraineConfig.Timing.retryDelaysMs) — for a "Try again" button once connectivity is failed.

Parameters — none.

Returns — nothing; it returns when done.

Errors — none.

GraineInApp.shared.voice.retry()

GraineVoice.setCaptionsOn

Call it from your own captions (CC) button to show or hide the line being said.

func setCaptionsOn(_ on: Bool)

The captions switch, captionsOn. While it is off, GraineAgentBar does not show the line being said; on — the default — it does. The call goes on either way, and what is said is still kept in captions (clearCaptions() forgets it). The switch is this agent's and lasts while the app runs: it is on again at the next launch, so set it at launch to keep the customer's choice. A UI of your own decides from captionsOn. Safe from any thread (it hops to the main thread).

Returns — nothing; it returns when done.

Errors — none.

let voice = GraineInApp.shared.voice
voice.setCaptionsOn(!voice.captionsOn)   // your CC button

GraineVoice.clearCaptions

Call it to forget what has been said on the in-app call without ending it.

func clearCaptions()

Empties captions — what has been said this call — and the call goes on; the next line said starts the list again. A call starting clears them too. The captions switch is untouched. Safe from any thread (it hops to the main thread).

Parameters — none.

Returns — nothing; it returns when done.

Errors — none.

GraineInApp.shared.voice.clearCaptions()

GraineVoice.viewOpened

Call it when a voice UI of your own comes on screen, so a slow connect is reported while the customer is watching.

func viewOpened()

A UI of your own that shows the voice came on screen — GraineAgentBar says so by itself. While one is open, an engine page still loading is the customer's wait: after GraineConfig.Timing.slowConnectMs (4 seconds) slowConnect turns true, for your "Still connecting…". Call it in pairs with viewClosed() — from onAppear and onDisappear, or viewDidAppear(_:) and viewDidDisappear(_:). Safe from any thread (it hops to the main thread).

Parameters — none.

Returns — nothing; it returns when done.

Errors — none.

struct MyVoiceScreen: View {
    @ObservedObject var voice = GraineInApp.shared.voice
    var body: some View {
        Text(voice.slowConnect ? "Still connecting…" : "Tap to talk")
            .onAppear { voice.viewOpened() }
            .onDisappear { voice.viewClosed() }
    }
}

GraineVoice.viewClosed

Call it when the voice UI you reported with viewOpened() leaves the screen.

func viewClosed()

The UI from viewOpened() left the screen. Once no UI that shows the voice is open — yours or the bar — and no call is being placed, a page still loading is no longer anyone's wait, and slowConnect goes back to false. Safe from any thread (it hops to the main thread).

Parameters — none.

Returns — nothing; it returns when done.

Errors — none.

GraineInApp.shared.voice.viewClosed()   // paired with viewOpened(), as the screen goes

GraineLoader (constructor)

Use it to show waiting the way the agent's design does.

init(moment: String? = nil, label: String? = nil, size: CGFloat? = nil, stacked: Bool = false, graine: GraineInApp? = nil)

The dashboard's loader, with its words for the moment you name. Pair moment: "thinking" with GraineVoice.phase == .thinking.

Returns — a new GraineLoader.

Errors — none.

if GraineInApp.shared.voice.phase == .thinking {
    GraineLoader(moment: "thinking")
}

GraineLoaderText (constructor)

Use it to build loader words for previews and tests.

init(connecting: String? = nil, reconnecting: String? = nil, thinking: String? = nil, component: String? = nil)

Builds a set of words for the waiting moments — for previews and tests; the SDK reads the real ones from the dashboard (GraineLoaderLook.text).

Returns — a new GraineLoaderText.

Errors — none.

let words = GraineLoaderText(connecting: "Connecting…", thinking: "One moment…")

GraineLoaderText.forMoment

Call it to get the words for one waiting moment.

func forMoment(_ moment: String) -> String?

The words for "connecting", "reconnecting", "thinking" or "component"; nil for anything else.

Returns — String?: that moment's words, or nil for any other word or when none were set. Example value: "Thinking…".

Errors — none.

let words = GraineLoaderText(connecting: "Connecting…", thinking: "One moment…")
let line = words.forMoment("thinking")       // "One moment…"

GraineCaption (constructor)

Use it to build caption lines for previews and tests of your own call UI.

init(role: GraineRole, text: String, live: Bool)

Builds a caption line by hand — for previews and tests; the SDK makes the real ones.

Returns — a new GraineCaption.

Errors — none.

let line = GraineCaption(role: .agent, text: "Your order ships today.", live: false)

GraineTransport.from

Call it to turn a transport's wire word into a GraineTransport.

static func from(_ s: String?) -> GraineTransport

.webrtc for "rtc"; anything else is .websocket, the transport that always works.

Returns — GraineTransport. Example value: .websocket.

Errors — none.

let transport = GraineTransport.from("rtc")   // .webrtc

GraineConnectionQuality.classify

Call it to grade one connection measurement the way the SDK does.

static func classify(rttMs: Double?, jitterMs: Double?, loss: Double?) -> GraineConnectionQuality

The word for one measurement (loss as a fraction, 0.08 = 8%); the worst value wins, and unknown when all three are missing.

Returns — GraineConnectionQuality. Example value: .excellent.

Errors — none.

let quality = GraineConnectionQuality.classify(rttMs: 120, jitterMs: 12, loss: 0.01)   // .excellent

GraineConnectionQuality.classify

Call it to grade a measurement given as a map.

static func classify(sample: [String: Any]?) -> GraineConnectionQuality

The same, from a sample map {rtt, jitter, loss}; a missing, negative or non-numeric value is absent, not zero. Used by the SDK; apps rarely need it.

Returns — GraineConnectionQuality. Example value: .excellent.

Errors — none.

let quality = GraineConnectionQuality.classify(sample: ["rtt": 420, "jitter": 20, "loss": 0.01])   // .poor

GraineAgentBar

Use it as the assistant bar: the agent's voice, chat and components in one view.

What the customer sees during a conversation, drawn by the SDK in the brand's design: avatar, name and a status line that names the network's state ("Weak connection", "No connection", "Reconnecting…"), microphone, hang-up, the line being said (while GraineVoice.captionsOn), the components the agent draws, and the chat — with a switch when the dashboard offers both. A SwiftUI view: mount it once at your root as an overlay, not inside a screen; it draws only the bar, lets other touches through, can be dragged up and down, and rises above the keyboard.

What to expect — Place it in your UI; it draws in the agent's design and follows the conversation by itself.

Its functions: init, accessory — each with its parameters, response, errors and an example.

GraineSurface

Use it to choose whether the bar opens the call or the chat.

Which conversation: a call or a chat, never both at once. Passed to GraineAgentBar(surface:).

What to expect — Only a choice among what the dashboard offers (What visitors get): asking for a conversation the agent does not offer changes nothing, and nil follows the dashboard's choice of which opens first.

GraineLauncher

Use it as a ready-made launcher button.

The floating launcher button in the brand's design (56 points high; a pill is as wide as its label): a tap places the in-app call, mounting the engine first if needed, and during the call it is the end button. A SwiftUI view that draws only the button — place it yourself, for example .overlay(alignment: .bottomTrailing) { GraineLauncher().padding(20) }.

What to expect — Draws nothing until an agent is configured, then follows the agent's design (shape, glyph or logo, colours) as soon as the settings load; during a call it turns into the end button.

Its functions: init — each with its parameters, response, errors and an example.

GraineVoice

Use it to drive and draw the in-app voice call yourself: GraineInApp.shared.voice.

The in-app voice call: a page Graine hosts, in a web view the SDK owns (one invisible point big), so audio fixes reach your app without a release — reached as GraineInApp.shared.voice and driven for you by GraineAgentBar. An ObservableObject; every method belongs on the main thread, and one called from elsewhere hops there.

What to expect — The assistant bar's voice call. The bar starts and ends it by itself; these are for an app that draws its own controls. One conversation at a time: starting it closes an open chat.

Its functions: attach, detach, start, end, setMuted, setCaptionsOn, clearCaptions, viewOpened, viewClosed, answerWidget, reportEvent, retry — each with its parameters, response, errors and an example.

GrainePhase

Read it to draw what the in-app call is doing, in one word.

What the in-app call is doing, in one word, for an app that draws its own bar: GraineVoice.phase. Raw values are the wire words.

What to expect — Worked out from the call as it moves, and published with GraineVoice's other state: idle outside a call; thinking is the moment to show a loader.

GraineConnectStage

Read it to tell the customer where a call being placed is.

Where a call being placed is: GraineVoice.connectStage. Raw values are the wire words.

What to expect — How the connection is doing, reported as it changes. Draw it so the customer can tell when the network is the problem.

GraineConnectProgress

Read it only if you handle the engine page's progress reports yourself.

One progress report from the engine page: a stage, or failed. The SDK turns it into GraineVoice.connectStage and callFailed.

What to expect — How the connection is doing, reported as it changes. Draw it so the customer can tell when the network is the problem.

GraineConnectivity

Read it to know whether the engine page is there, and offer a retry when it failed.

Whether the engine page that carries the in-app call is there: GraineVoice.connectivity and onConnectivity. Raw values are the wire words.

What to expect — How the connection is doing, reported as it changes. Draw it so the customer can tell when the network is the problem.

GraineLoader

Use it as the agent's loader.

How waiting looks, drawn from the dashboard's Appearance → loader: dots, pulse, ring, bars or the brand's logo breathing, at the configured size, speed and colour, with the dashboard's words for the moment. A SwiftUI view; nothing animates while it is off screen.

What to expect — Draws nothing until an agent is configured; until the agent's settings load it draws the default dots in the default accent, then the dashboard's loader.

Its functions: init — each with its parameters, response, errors and an example.

GraineLoaderText

Read it to get the dashboard's words for each waiting moment.

The words for each waiting moment, as carried in GraineLoaderLook.text. A value type.

What to expect — Resolved from the agent's design in the Garage when the agent's settings load; before that, and from an older server, every field holds its default. A missing or malformed value falls back on its own; reading these never throws. Most apps never need them: the SDK's own views draw from them.

Its functions: init, forMoment — each with its parameters, response, errors and an example.

GraineLoaderLook

Read it only to draw a loader of your own that matches the dashboard's.

The loader in effect, as values a renderer can use. Used by the SDK's own views; apps do not need it.

What to expect — Resolved from the agent's design in the Garage when the agent's settings load; before that, and from an older server, every field holds its default. A missing or malformed value falls back on its own; reading these never throws. Most apps never need them: the SDK's own views draw from them.

GraineCaption

Read it to draw a line being said.

One caption line: in GraineVoice.captions, GraineCalls.caption and GraineCalls.transcript. A value type.

What to expect — The line being said right now, by either side; live while it is still being recognised or spoken. Replaced as the conversation moves on: draw the latest. The captions switch (GraineVoice.captionsOn) hides the bar's line, never the list: captions keeps what is said either way.

Its functions: init — each with its parameters, response, errors and an example.

GraineTransport

Read it to know how the in-app call's audio travels, or set GraineConfig.transport to force one.

How the in-app call's audio travels; raw values are the wire words. Set GraineConfig.transport only to force one, and hear what was used through onTransport. It applies to the voice bar's in-app call (GraineVoice) only: native calls (GraineCalls) carry their audio in your app's own process and choose their road with GraineCallsConfig.callTransport (GraineCallTransport).

What to expect — The SDK sends and reads these for you; they are public so a custom UI can reuse them.

Its functions: from — each with its parameters, response, errors and an example.

GraineConnectionQuality

Read it to show the customer when the network is the problem.

The connection in one word, with the same thresholds on every platform: GraineVoice.quality and onQuality. Raw values are the wire words.

What to expect — How the connection is doing, reported as it changes. Draw it so the customer can tell when the network is the problem.

Its functions: classify — each with its parameters, response, errors and an example.

Several agents in one app

More than one agent in the same app — a support agent in Help, a sales agent on Plans — each with its own publishable key, design, chat, voice bar, actions and requests. Who the customer is, the screen and the phone's calls belong to the app and are shared. Configure each with GraineInApp.configure(_:name:), and hand one to a view with its graine: parameter. One conversation runs at a time across all of them.

GraineInApp.named

Call it to reach an agent you configured under a name.

static func named(_ name: String) -> GraineInApp?

The agent configured under name (trimmed; an empty name is the default agent), or nil when no agent has that name.

Returns — GraineInApp?: the agent, or nil. Example value: nil before configure(_:name: "support").

Errors — none.

GraineInApp.named("support")?.chat.open()

GraineInApp.all

Read it to go through every agent your app configured — to sign them all in or out, say.

static var all: [String: GraineInApp] { get }

Every configured agent, keyed by the name it was configured under; the default agent is under "default". Empty before any agent is configured.

Parameters — none.

Returns — [String: GraineInApp]. Example value: ["default": <GraineInApp>, "support": <GraineInApp>].

Errors — none.

for (name, agent) in GraineInApp.all {
    print(name, agent.session?.agentId ?? "loading")
}

GraineInApp.current

Read it when your code may run before any agent is configured — it never stops the app.

static var current: GraineInApp? { get }

The default agent — or, when every agent was given a name, the first one configured. Nil before any agent is configured. The SDK's views draw this agent unless you hand them another.

Parameters — none.

Returns — GraineInApp?. Example value: nil before configure.

Errors — none.

guard let graine = GraineInApp.current else { return }   // not configured yet
graine.chat.open()

GraineInApp.shared

Use it to reach the default agent from anywhere once it is configured.

static var shared: GraineInApp { get }

The same agent as current. If no agent has been configured, it stops the app with a message saying to call configure first — so read it only after configure has run (current is the safe form).

Parameters — none.

Returns — GraineInApp.

Errors — none thrown; it stops the app when nothing is configured.

GraineInApp.shared.identify(["user_id": user.id])

GraineInApp.name

Read it to tell which agent an instance is — in a listener shared by several agents, say.

let name: String

The name this agent was configured under (trimmed); "default" for the default agent. The same name GraineCalls.agent, GraineMissedCall.agent and the bridges' agent fields carry.

Parameters — none.

Returns — String. Example value: "support".

Errors — none.

let support = GraineInApp.configure(GraineConfig(baseUrl: "https://www.graine.ai", publishableKey: "pk_live_…"), name: "support")
print(support.name)   // "support"

Screen context, actions and components

Tell the agent what the customer sees and does, let it act in your app, notice when the customer is stuck, keep identifiers on the device, and show the components the agent draws.

GraineInApp.setScreen

Call it on every meaningful screen change, so the agent knows what the customer sees.

func setScreen(_ next: GraineScreen?)

What the customer is looking at; call it on every meaningful change. Shared by every agent. An unchanged screen is not sent again, and a burst of changes goes as one update every 400 ms — the first at once. nil means no screen.

Returns — nothing; it returns when done.

Errors — none.

GraineInApp.shared.setScreen(GraineScreen(
    screen: "checkout_address", title: "Delivery address",
    journey: .init(name: "Checkout", step: 2, of: 3, next: "Payment"),
    fields: [GraineField(name: "postal_code", label: "Postal code", value: postalCode, status: .invalid, error: "We don't deliver there yet")]
))
GraineInApp.shared.updateField(GraineField(name: "postal_code", value: postalCode, status: .filled))
GraineInApp.shared.track("coupon_applied", data: ["code_length": 8])

GraineInApp.updateField

Call it as the customer edits one field, instead of describing the whole screen again.

func updateField(_ field: GraineField)

Reports one changed field, merged by name into the current screen (added when new), so a form need not describe itself again on every keystroke. Does nothing without a current screen, or for a field with an empty name.

Returns — nothing; it returns when done.

Errors — none.

GraineInApp.shared.updateField(GraineField(name: "postal_code", value: postalCode, status: .filled))

GraineInApp.removeField

Call it when a field leaves the screen.

func removeField(_ name: String)

Removes a field from the current screen. Nothing happens if it was never reported.

Returns — nothing; it returns when done.

Errors — none.

GraineInApp.shared.removeField("coupon_code")

GraineInApp.clearScreen

Call it in a screen's teardown, so the agent stops describing a screen the customer left.

func clearScreen(_ screenId: String?)

Forgets the screen only if it is still the one with that id — safe in a screen's teardown, which can run after the next screen has reported itself. nil clears whatever screen is set.

Returns — nothing; it returns when done.

Errors — none.

.onDisappear { GraineInApp.shared.clearScreen("checkout_address") }

GraineScreen (constructor)

Use it to describe what the customer is looking at.

init(screen: String, title: String? = nil, journey: Journey? = nil, fields: [GraineField] = [], error: String? = nil, data: [String: Any] = [:], availableActions: [String]? = nil)

Builds a screen description to hand to setScreen.