Kotlin Multiplatform SDK reference

Every public declaration of the Kotlin Multiplatform SDK — ai.graine:inapp-kmp 0.8.0, one API in shared code over Graine's Android and iOS SDKs, and ai.graine:inapp-kmp-compose 0.8.0, the SDK's own screens for Compose Multiplatform — grouped by what you use it for. Each entry says what it is for, then gives its signature, its parameters, what it returns, the errors it can raise and an example; each type lists its fields with what to expect. The same API across every platform, topic by topic, is the SDK reference; installing and setting up is Kotlin Multiplatform.

Requirements, install, permissions and initialisation

Gradle (Kotlin DSL) — shared/build.gradle.kts

kotlin {
    androidTarget()
    iosArm64(); iosSimulatorArm64(); iosX64()
    sourceSets {
        commonMain.dependencies {
            implementation("ai.graine:inapp-kmp:0.10.3")
            implementation("ai.graine:inapp-kmp-compose:0.10.3")
        }
    }
}

• Android. The Android SDK's manifest comes with it — the microphone and notification permissions, the call screen, the call service — so there is nothing to copy (what it adds, and how to remove the calls entries from an app without calls, is on the Android reference). The library finds your application by itself, so Graine.configure(config) works from shared code. Ask for POST_NOTIFICATIONS on Android 13 and up during onboarding — without it the phone cannot ring. An activity that shows the voice bar or places calls forwards its permission answers to Graine.onRequestPermissionsResult(requestCode, grantResults). For calls Graine rings, add Firebase Cloud Messaging to the Android app (google-services.json, its Gradle plugin and com.google.firebase:firebase-messaging): the SDK registers for pushes itself. An app with a FirebaseMessagingService of its own, which outranks the SDK's, calls Graine.calls.onNewToken(token) and Graine.calls.handlePush(message.data) from it.
• iOS. Add the iOS SDK to the app: with Swift Package Manager (https://github.com/GraineAI/inapp-ios, from 0.10.3) and your shared framework built static (isStatic = true, the Compose Multiplatform default), or with CocoaPods (pod 'GraineInApp'; with Kotlin's CocoaPods plugin and a dynamic framework, pod("GraineInApp") { version = "0.10.3"; linkOnly = true }). Add NSMicrophoneUsageDescription to Info.plist, and for calls Push Notifications and Background Modes → Audio and Voice over IP. Call Graine.calls.enableVoIPPushes() at every launch. Link GraineInApp 0.10.3, the version of this library: with an older one (0.7.0), booking is not available on iOS — bookingAvailable is false and presentBooking throws Unavailable — and everything else works.

Kotlin Multiplatform · Kotlin — commonMain

Graine.configure(GraineConfig(
    baseUrl = "https://www.graine.ai",
    publishableKey = "pk_live_…",          // Agent → Embed & Widgets → Install
    appVersion = "2.4.0",
))
Graine.calls.configure(GraineCallsConfig(displayName = "Acme"))
 
// Compose Multiplatform UI
Box(Modifier.fillMaxSize()) {
    AppContent()
    GraineAgentBar(Modifier.align(Alignment.BottomCenter).fillMaxWidth().height(180.dp))
}

Every function may be called from any thread; the suspending ones never block the main thread; the states are flows that always hold the latest value.

WebRTC calls (optional)

Native calls carry their audio over a WebSocket — in both directions: the person calling the agent (startCall, your “Call us” button) and the person answering a call Graine rang (a booked call, Ring now). Add each platform's WebRTC module to the app and they carry it over WebRTC instead. Nothing in shared code changes: the same ring, the same call screen, the same “Connecting…”, the same outcomes.

Gradle (Kotlin DSL) — shared/build.gradle.kts, the Android side

kotlin {
    sourceSets {
        androidMain.dependencies {
            implementation("ai.graine:inapp-android-rtc:0.10.3")   // the same version as ai.graine:inapp-android
        }
    }
}

• Android. ai.graine:inapp-android-rtc, at the same version as the Android SDK this library brings (ai.graine:inapp-android 0.8.0) — in androidMain as above, or in the Android app's own dependencies. Its manifest adds ACCESS_NETWORK_STATE, a normal permission granted at install: nothing is asked. Its R8 rules ship inside it. Size per phone (an app bundle delivers one ABI): about 7.4 MB installed on 64-bit ARM (about 2.5–3.3 MB to download), 4.3 MB on 32-bit ARM, 8.2–8.4 MB on x86, and about 0.5 MB of classes.
• iOS. The GraineInAppRTC package, added to the iOS app target beside GraineInApp, the same way and at the same version: with Swift Package Manager https://github.com/GraineAI/inapp-ios-rtc (its library GraineInAppRTC), or with CocoaPods pod 'GraineInAppRTC', :git => 'https://github.com/GraineAI/inapp-ios-rtc.git', :tag => '0.10.3'. No code, no Info.plist entry, no capability: the calls find the module by themselves. A build that strips code nothing references can call GraineRTC.install() at launch from the app's Swift code (import GraineInAppRTC); GraineRTCVersion.name is the module's version. About 12 MB more installed on an arm64 iPhone, about 6 MB more to download. If another package in the app pins the same WebRTC build at a different version, the two cannot be resolved together: leave the module out (calls stay on the WebSocket) or align the versions.
• Choosing. GraineCallsConfig(callTransport = …), a GraineCallTransport: AUTO, the default — 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 (the WebSocket only when the module is missing or WebRTC cannot set up this call).
• 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.
• What the person notices. 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 set up a call before any audio flows — a network that blocks it, a server that turns it down, no answer within the time allowed (about 12 seconds in all) — the call continues on the WebSocket inside the same call: no second ring, no new call screen, no error; “Connecting…” shows a moment longer. 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. Graine.calls.state says which one carried a call — transport and transportFallbackReason (GraineCallInfo).
• Licences. A prebuilt WebRTC library (Google's WebRTC, BSD 3-Clause, its symbols renamed so it never clashes with another copy in the app): list it in your app's open-source notices. Android: graine-inapp-rtc/THIRD-PARTY-NOTICES.md; iOS: the package's THIRD-PARTY-NOTICES.md.

Kotlin Multiplatform · Kotlin — commonMain

Graine.calls.configure(GraineCallsConfig(displayName = "Acme", callTransport = GraineCallTransport.AUTO))

Install and the first answer

Configure the SDK once at launch, then read the agent's settings when they arrive. Calling anything on Graine before configure throws IllegalStateException (“Graine.configure(GraineConfig(…)) has not been called. Call it once, at launch.”).

Graine.configure

Call it once at launch — in Application.onCreate on Android, the app's init on iOS — to start the agent.

fun configure(config: GraineConfig, name: String = DEFAULT_AGENT): GraineAgent

Without a name it starts the default agent, which everything on Graine belongs to. An app with several agents configures each under its own name and key (Several agents). Asking again for a name already set up gives you that same agent; the configuration passed the second time is ignored. On Android the SDK finds the application by itself; on iOS the agent is the iOS SDK's agent under that name — one the app already configured from Swift is used as it is.

Returns — GraineAgent — the agent (GraineAgent).

Errors — IllegalStateException on Android when the application cannot be found (“Graine could not find the application. Keep ai.graine.inapp.kmp.GraineInitProvider in the manifest, or call Graine.configure(context, config) on Android.”), and on iOS when the iOS SDK cannot configure the agent.

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

Graine.configure (Android, with a context)

Use it on Android only when your app removed GraineInitProvider from its manifest, so the SDK cannot find the application itself.

fun Graine.configure(context: Context, config: GraineConfig, name: String = Graine.DEFAULT_AGENT): GraineAgent

The same as Graine.configure(config, name), with the application taken from context. In androidMain only.

Returns — GraineAgent.

Errors — none.

import android.app.Application
 
class AcmeApp : Application() {
    override fun onCreate() {
        super.onCreate()
        Graine.configure(this, GraineConfig(baseUrl = "https://www.graine.ai", publishableKey = "pk_live_…"))
    }
}

Graine

Use it for everything: it is the SDK, and the default agent.

object Graine

Configure it once at launch. Who the user is, this install, the memory choice, the screen and the phone's calls belong to the app and are shared by every agent; everything else on Graine is the default agent's.

What to expect — Every member may be called from any thread; calling anything but configure before it throws IllegalStateException. The flows always hold the latest value; events is not replayed.

Its functions: configure, agent, identify, setMemory, memories, forgetMemory, setVariables, currentVariables, registerAction, setScreen, updateField, removeField, clearScreen, track, tap, noteInteraction, presentBooking, scheduleCall, scheduledCalls, cancelScheduledCall, onRequestPermissionsResult — each with its parameters, what it returns, its errors and an example.

Graine.session (the agent's settings)

Collect it to know when the agent's settings have loaded — before offering what depends on them, such as booking.

val session: StateFlow<GraineSession?>

null until the default agent's settings arrive from Graine (once per launch), then the GraineSession. Each agent has its own: GraineAgent.session. The same moment is also an event, GraineEvent.SessionReady.

Parameters — none.

Returns — StateFlow<GraineSession?>. Example value: GraineSession(agentId="a7c1…", memoryEnabled=true, identityField="user_id", devicesPerUser=2, schedulingRules=GraineSchedulingRules(usersCanBook=true, …), declaredActions=[open_screen]).

Errors — none.

var callMeVisible = false   // whether your "Call me" button shows
scope.launch {
    Graine.session.filterNotNull().first()
    callMeVisible = Graine.bookingAvailable
}

GraineConfig

Pass it to Graine.configure to say which agent to start and how.

data class GraineConfig(…)

Everything the SDK needs to know up front — the native SDKs' configuration, field for field.

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

GraineSession

Read it to know what the agent's settings say once they have loaded — who the user is, the booking rules, the declared actions.

data class GraineSession(…)

From Graine.session (and GraineAgent.session, GraineEvent.SessionReady).

What to expect — Loaded once per launch; null in session until then. A setting an older server does not send means its default: the user_id trait, 2 devices per user, booking off.

GraineInitProvider

Leave it in your merged manifest on Android: it is how Graine.configure(config) finds the application from shared code.

class GraineInitProvider : ContentProvider()

Declared by the library and started by Android at process start, before Application.onCreate; it records the application and, from then on, the activity in front. It serves no data. An app that removes it calls Graine.configure(context, config) instead.

What to expect — Nothing to call. Android only.

Identity, memory and conversations that continue

Tell the agent who the user is, so it can remember them, ring them, and continue their conversation. Where the agent remembers its users, a signed-in user who comes back finds the chat where they left it: it opens with the earlier messages (restored, oldest first; an earlier call's as one “Voice call” row) and the agent continues from them. chat.newConversation() starts afresh. Who the user is belongs to the app: Graine.identify tells every agent.

Graine.identify

Call it after the user signs in, and with null when they sign out.

fun identify(traits: Map<String, Any?>?, memory: Boolean? = null)

The trait the agent's Who is the user? setting names (user_id unless the dashboard chose email, phone or a custom trait) is how Graine tells your users apart: it lets the agent remember a user and ring them. Its value goes only to Graine and never becomes a prompt variable; every other trait is masked on the device and reaches the agent as a prompt variable. A placeholder ("guest", a masked value) identifies nobody.

It applies to the next conversation, for every agent. null signs out everywhere: this device stops being one of the user's, the chat on screen is cleared, and later conversations are anonymous. Identifying a different user does the same for the previous one.

Returns — nothing.

Errors — IllegalStateException before configure.

Graine.identify(mapOf("user_id" to user.id, "name" to user.firstName), memory = user.allowsMemory)
Graine.identify(null)   // on sign-out

Graine.setMemory

Call it when the user changes their memory choice in your privacy settings.

fun setMemory(enabled: Boolean)

The same as identify with the same traits and memory = enabled, for every agent. Kept on this install for this user.

Returns — nothing.

Errors — IllegalStateException before configure.

Graine.setMemory(false)

Graine.memories

Call it to show the user what the agent remembers about them, on a privacy screen.

suspend fun memories(): List<GraineMemory>

What the default agent remembers about the signed-in user, newest first, at most 100, already redacted. Only from a device the user is using. GraineAgent.memories() asks another agent.

Parameters — none.

Returns — List<GraineMemory> (GraineMemory). Example value: [GraineMemory(id="m_31", text="Prefers a call after 6 PM", createdAt=2026-10-12T09:15:00Z, updatedAt=null)].

Errors — throws GraineException: IdentityRequired with nobody signed in, DeviceLimit from a device that is not one of the user's, RateLimited, Network, Unavailable, InvalidKey, OriginRefused.

val remembered = try { Graine.memories() } catch (e: GraineException) { emptyList() }

Graine.forgetMemory

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

suspend fun forgetMemory(): Int

Deletes everything the default agent remembers about the signed-in user — only from a device that user is using. Once it succeeds the chat on screen is cleared too; a refusal leaves it as it was.

Parameters — none.

Returns — Int — how many memories were deleted. Example value: 3.

Errors — throws GraineException: IdentityRequired, DeviceLimit, RateLimited, Network, Unavailable, InvalidKey, OriginRefused.

val deleted = Graine.forgetMemory()

GraineAgent.memories

Call it to show what one of your other agents remembers about the signed-in user.

suspend fun memories(): List<GraineMemory>

Graine.memories() for this agent: newest first, at most 100, already redacted.

Parameters — none.

Returns — List<GraineMemory>.

Errors — throws GraineException as Graine.memories(); IllegalStateException when this agent is not configured.

val remembered = Graine.agent("support")?.memories().orEmpty()

GraineAgent.forgetMemory

Call it to make one of your other agents forget the signed-in user.

suspend fun forgetMemory(): Int

Graine.forgetMemory() for this agent.

Parameters — none.

Returns — Int — how many memories were deleted.

Errors — throws GraineException as Graine.forgetMemory().

val deleted = Graine.agent("support")?.forgetMemory() ?: 0

GraineChat.newConversation

Call it to give the user a fresh conversation instead of continuing the last one.

suspend fun newConversation()

The chat hangs up, Graine lets go of the conversation it kept for this agent and user (so the next chat does not continue it), and the messages on screen and any waiting to go are cleared; when the user was in the chat, a fresh chat opens with the welcome and the starters. Memories the agent keeps about the user stay as they are. With nobody signed in there is nothing kept to let go of, so only the screen is cleared. The SDK's chat window calls it from the New conversation button in its header, which it shows only while a conversation continued from before is on screen.

Parameters — none.

Returns — nothing, once the new conversation has started.

Errors — throws GraineException when Graine refused (DeviceLimit, Network, …); the chat is then as it was.

scope.launch { runCatching { Graine.chat.newConversation() } }

GraineMemory

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

data class GraineMemory(val id: String, val text: String, val createdAt: Instant? = null, val updatedAt: Instant? = null)

What to expect — From memories(): newest first, at most 100, already redacted. The times are moments; show them in the device's time zone.

Chat

The typed conversation with an agent: Graine.chat for the default agent, Graine.agent("support")?.chat for another. Show the SDK's own chat screen — GraineChat() in Compose, GraineViews.chat() in UIKit — or draw your own from turns, status, typing and upcomingCalls. Everything works as on a call: the agent sees the screen you report, runs your actions and draws its components. Only one conversation runs at a time — opening the chat ends a voice-bar call, and during a native call the chat waits until the call is over.

GraineChat

Use it to open, send to and follow one agent's chat.

class GraineChat

Graine.chat, or GraineAgent.chat for another agent. A message typed while the chat is not connected is shown at once and sent when it is; a dropped connection is made again on its own while the user is in the chat.

What to expect — The four flows always hold the latest value. turns empties on sign-out, when another user signs in, after a successful forgetMemory(), on newConversation() and on clear().

Its functions: open, close, send, retry, clear, newConversation, refreshUpcomingCalls, cancelUpcomingCall, answerWidget — each with its parameters, what it returns, its errors and an example.

GraineChat.open

Call it when the user goes into the chat, so it connects and stays connected.

fun open(size: GraineChatSize? = null)

Ends a call the voice bar holds. A voice bar on screen moves to its chat and draws it at size — this open's own, until close(); null follows GraineConfig.chatSize, then the dashboard's Window size.

Returns — nothing.

Errors — IllegalStateException when the agent is not configured.

Graine.chat.open(GraineChatSize.LARGE)

GraineChat.close

Call it when the user leaves the chat.

fun close()

The chat hangs up and stays down; what was said stays.

Parameters — none.

Returns — nothing.

Errors — IllegalStateException when the agent is not configured.

Graine.chat.close()

GraineChat.send

Call it to send the user's message from a chat screen of your own.

fun send(text: String)

Shown at once, and sent now or as soon as the chat is connected. Blank messages are ignored.

Returns — nothing.

Errors — IllegalStateException when the agent is not configured.

Graine.chat.send("Where is my order?")

GraineChat.retry

Call it from a “Try again” control when the chat is offline or a message failed.

fun retry()

Connects now and sends what could not be sent.

Parameters — none.

Returns — nothing.

Errors — IllegalStateException when the agent is not configured.

Graine.chat.retry()

GraineChat.clear

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

fun clear()

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 what the agent remembers stays. newConversation() starts over; forgetMemory() forgets. On iOS it needs GraineInApp of this version; an older one ignores it.

Parameters — none.

Returns — nothing; turns is empty.

Errors — IllegalStateException when the agent is not configured.

Graine.chat.clear()

GraineChat.refreshUpcomingCalls

Call it after the user booked a call outside the chat, so the Upcoming calls card of your own chat shows it.

fun refreshUpcomingCalls()

Fetches upcomingCalls again. The chat refreshes them by itself when it opens and after each of the agent's replies, so most apps never call it. On iOS it needs GraineInApp of this version; an older one does nothing.

Parameters — none.

Returns — nothing; upcomingCalls changes when Graine answers.

Errors — IllegalStateException when the agent is not configured.

Graine.chat.refreshUpcomingCalls()

GraineChat.cancelUpcomingCall

Call it from the Cancel control on a row of your own Upcoming calls card.

fun cancelUpcomingCall(id: String)

The call leaves upcomingCalls once Graine has called it off; if Graine refuses, it stays in the list. A blank id is ignored. To learn the outcome yourself, call Graine.cancelScheduledCall(id) instead (Graine.cancelScheduledCall). On iOS it needs GraineInApp of this version; an older one does nothing.

Returns — nothing.

Errors — IllegalStateException when the agent is not configured.

Graine.chat.upcomingCalls.value.firstOrNull { it.canCancel }?.let { Graine.chat.cancelUpcomingCall(it.id) }

GraineChatTurn

Read it to draw one message of the chat.

data class GraineChatTurn(…)

What to expect — One per message, oldest first. The agent's message updates in place (same id) while live, then stops. A user's message typed while the chat is not connected is SENDING and goes as soon as it is; FAILED means it could not reconnect — retry() tries again. Restored turns arrive once, when the chat opens, for a signed-in user on an agent with memory on: at most 50, oldest first, delivered, never live, with their original times; the welcome is not sent then.

GraineDelivery

Read it to show where one of the user's messages is.

enum class GraineDelivery { SENDING, SENT, FAILED }

What to expect — Only on the user's messages; the agent's are null.

GraineChatChannel

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

enum class GraineChatChannel(val wire: String)

What to expect — A chat window draws a run of VOICE messages as one “Voice call” row, never their words.

GraineChatStatus

Read it to show the chat's connection.

enum class GraineChatStatus { IDLE, CONNECTING, ONLINE, RECONNECTING, OFFLINE }

What to expect — IDLE → CONNECTING → ONLINE; a drop — or a first try that failed — goes to RECONNECTING and back; OFFLINE when it could not reconnect or the conversation ended.

GraineChatSize

Pass it to choose how big the chat window opens.

enum class GraineChatSize(val wire: String)

What to expect — Which size wins: the size passed to chat.open(size), then GraineConfig.chatSize, then the agent's Window size in the dashboard, else compact. On a phone, large is a sheet over most of the screen and full the whole screen; on a tablet both open a panel in the corner.

GraineRole

Read it to know who said a line.

enum class GraineRole { USER, AGENT }

GraineChat (Compose)

Use it to show the SDK's own chat screen in a Compose Multiplatform UI.

@Composable
expect fun GraineChat(modifier: Modifier = Modifier, onClose: (() -> Unit)? = null, agent: String = Graine.DEFAULT_AGENT)

In ai.graine:inapp-kmp-compose. The chat as a whole screen, drawn in the agent's design: the header, one bubble per reply, the components the agent draws, the composer — and, where Graine rings this phone, the user's booked calls with Book a call (Booking with the SDK's sheet). It connects when it appears and hangs up shortly after it leaves the screen. A conversation that continues opens on its earlier messages — under day separators, an earlier call as one “Voice call” row, no starters — with New conversation in the header. On Android it hosts the Android SDK's chat view; on iOS the iOS SDK's chat screen, inside Compose's accessibility tree so VoiceOver reaches it. Nothing is drawn before Graine.configure, or for an agent that is not configured.

Returns — nothing (a composable).

Errors — none.

@Composable
fun ChatScreen(onBack: () -> Unit) {
    GraineChat(Modifier.fillMaxSize(), onClose = onBack)   // onBack: your navigation's back
}
 
@Composable
fun HelpScreen() {
    GraineChat(Modifier.fillMaxSize(), agent = "support")
}

GraineViews

Use it on iOS to present the SDK's own screens as UIKit view controllers.

object GraineViews

In iosMain. For an app that presents UIKit itself; Compose Multiplatform apps use GraineChat(), GraineCallScreen() and GraineAgentBar(), which host these.

What to expect — Each function throws IllegalStateException before Graine.configure (or for an agent that is not configured).

Its functions: chat, voiceBar, callScreen — each with its parameters, what it returns, its errors and an example.

GraineViews.chat

Call it on iOS to get an agent's chat as a view controller to present.

fun chat(onClose: (() -> Unit)? = null, agent: String = Graine.DEFAULT_AGENT): UIViewController

The iOS SDK's chat screen, drawn in the agent's design, with the user's booked calls and Book a call where Graine rings this phone.

Returns — UIViewController.

Errors — IllegalStateException when the agent is not configured.

import platform.UIKit.UIViewController
 
fun showChat(from: UIViewController) {
    val chat = GraineViews.chat(onClose = { from.dismissViewControllerAnimated(true, completion = null) })
    from.presentViewController(chat, animated = true, completion = null)
}

GraineChatRows

Use it to lay out a chat screen of your own the way the SDK's chat window does.

object GraineChatRows

The rule every Graine SDK draws its own chat window by: a bubble per typed message; one “Voice call · 6:05 PM” row for a run of voice messages on one day; and a day separator — Today, Yesterday, 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 draws exactly as before.

Its functions: build, dayLabel, callLabel, offersStarters, offersNewConversation — each with its parameters, what it returns, its errors and an example.

GraineChatRows.build

Call it to turn the chat's messages into the rows to draw, in order.

fun build(turns: List<GraineChatTurn>, now: Instant = Clock.System.now(), zone: TimeZone = TimeZone.currentSystemDefault()): List<GraineChatRow>

Returns — List<GraineChatRow> (GraineChatRow). Example value: [Day(TODAY, 2026-10-15, …), Turn(turn, 0), VoiceCall("voice-t2", …, 1, 3)].

Errors — none.

val rows = GraineChatRows.build(Graine.chat.turns.value)

GraineChatRows.dayLabel

Call it to write a day separator's words.

fun dayLabel(row: GraineChatRow.Day, now: Instant = Clock.System.now(), zone: TimeZone = TimeZone.currentSystemDefault()): String

Returns — String — “Today”, “Yesterday”, else the date, “Sat 10 Oct”, with the year when it is not this one (“Wed 31 Dec 2025”). Example value: "Yesterday".

Errors — none.

val separators = GraineChatRows.build(Graine.chat.turns.value)
    .filterIsInstance<GraineChatRow.Day>()
    .map { GraineChatRows.dayLabel(it) }   // ["Yesterday", "Today"]

GraineChatRows.callLabel

Call it to write an earlier call's row.

fun callLabel(clock: String): String

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

Errors — none.

val words = GraineChatRows.callLabel("6:05 PM")

GraineChatRows.offersStarters

Call it to decide whether to show the brand's conversation starters.

fun offersStarters(turns: List<GraineChatTurn>): Boolean

Starters appear only in a fresh chat: they go once the user says something, and a continued conversation never shows them.

Returns — Boolean. Example value: true.

Errors — none.

val showStarters = GraineChatRows.offersStarters(Graine.chat.turns.value)

GraineChatRows.offersNewConversation

Call it to decide whether to offer “New conversation” in your chat's header.

fun offersNewConversation(turns: List<GraineChatTurn>): Boolean

Offered while restored messages are on screen — a conversation that continues.

Returns — Boolean. Example value: false.

Errors — none.

val offer = GraineChatRows.offersNewConversation(Graine.chat.turns.value)

GraineChatRow

Read it to draw one row of a chat laid out by GraineChatRows.build.

sealed class GraineChatRow

What to expect — Draw Day as a separator, VoiceCall as one row that a call happened (never its words) and Turn as a bubble.

GraineChatDay

Read it to know which day a separator names.

enum class GraineChatDay { TODAY, YESTERDAY, DATE }

The voice bar

The agent talking inside your app, beside the screen it talks about. Show the bar with GraineAgentBar() (Compose) or GraineViews.voiceBar() (UIKit); it places and ends the call itself, draws captions, the connection's state and the chat beside the call, all in the agent's design. Graine.voice is for an app that draws its own controls. The device asks the user for the microphone when the first call starts.

GraineVoice

Use it to start and end the voice bar's call from controls of your own.

class GraineVoice

Graine.voice, or GraineAgent.voice for another agent.

Its functions: start, end, setMuted, setCaptionsOn, clearCaptions — each with its parameters, what it returns, its errors and an example.

GraineVoice.start

Call it from your own “Talk” control to place the voice bar's call.

fun start()

Mounts the voice engine first if nothing has (on Android, in the activity in front). One conversation at a time: it ends the chat, and it cannot start while a native call is live.

Parameters — none.

Returns — nothing.

Errors — IllegalStateException when the agent is not configured. A refused microphone is the event GraineEvent.MicrophoneDenied.

Graine.voice.start()

GraineVoice.end

Call it from your own hang-up control.

fun end()

Parameters — none.

Returns — nothing.

Errors — IllegalStateException when the agent is not configured.

Graine.voice.end()

GraineVoice.setMuted

Call it from your own mute control.

fun setMuted(muted: Boolean)

Stops sending the user's voice without ending the call.

Returns — nothing.

Errors — IllegalStateException when the agent is not configured.

Graine.voice.setMuted(true)

GraineVoice.setCaptionsOn

Call it from your own captions (CC) control.

fun setCaptionsOn(on: Boolean)

Moves the captions switch, GraineVoiceInfo.captionsOn. While it is off the SDK's voice bar hides the line being said; the call goes on, and what was said is still kept in captions. On by default. On iOS it needs GraineInApp of this version; with an older one the captions stay on.

Returns — nothing.

Errors — IllegalStateException when the agent is not configured.

Graine.voice.setCaptionsOn(!Graine.voice.state.value.captionsOn)

GraineVoice.clearCaptions

Call it to forget what has been said on the call — a fresh transcript for your own captions view.

fun clearCaptions()

Empties GraineVoiceInfo.captions without ending the call; the next line starts the list again. On iOS it needs GraineInApp of this version; an older one does nothing.

Parameters — none.

Returns — nothing.

Errors — IllegalStateException when the agent is not configured.

Graine.voice.clearCaptions()

GraineVoiceInfo

Read it to draw the voice bar's call in controls of your own.

data class GraineVoiceInfo(val connected: Boolean = false, val connecting: Boolean = false, val muted: Boolean = false, val captionsOn: Boolean = true, val captions: List<GraineCaption> = emptyList())

GraineCaption

Read it to show the line being said on a call.

data class GraineCaption(val role: GraineRole, val text: String, val live: Boolean)

The last line of a native call (GraineCallInfo.caption). The voice bar's lines arrive as the event GraineEvent.Caption and are kept, the last 12, in GraineVoiceInfo.captions; the captions switch (captionsOn) hides the bar's caption, never the list.

GraineTransport

Pass it in GraineConfig.transport only to force how the voice bar's audio travels.

enum class GraineTransport(val wire: String)

What to expect — Leave transport null and the dashboard's Call audio setting decides.

GraineAgentBar

Use it to show the voice bar in a Compose Multiplatform UI.

@Composable
expect fun GraineAgentBar(modifier: Modifier = Modifier, name: String? = null, onClose: (() -> Unit)? = null, agent: String = Graine.DEFAULT_AGENT)

In ai.graine:inapp-kmp-compose. It takes up the whole space you give it and draws the bar along the bottom edge, so place it in a strip at the bottom of your layout. It mounts the voice engine itself; on iOS VoiceOver reaches into it. The chat opens at the size passed to Graine.chat.open(size); failing that, at GraineConfig.chatSize; failing that, at the dashboard's setting — large and full open over the app, as a sheet or the whole screen. Nothing is drawn before Graine.configure.

Returns — nothing (a composable).

Errors — none.

@Composable
fun HomeScreen() {
    var showBar by remember { mutableStateOf(true) }
    Box(Modifier.fillMaxSize()) {
        AppContent()
        if (showBar) GraineAgentBar(Modifier.align(Alignment.BottomCenter).fillMaxWidth().height(180.dp), onClose = { showBar = false })
    }
}

GraineViews.voiceBar

Call it on iOS to get an agent's voice bar as a view controller.

fun voiceBar(name: String? = null, onClose: (() -> Unit)? = null, agent: String = Graine.DEFAULT_AGENT): UIViewController

The bar is drawn at the bottom of the view it fills.

Returns — UIViewController.

Errors — IllegalStateException when the agent is not configured.

import platform.UIKit.*   // UIViewController and its child-controller calls
 
fun showVoiceBar(parent: UIViewController) {
    lateinit var bar: UIViewController
    bar = GraineViews.voiceBar(onClose = {        // the user hung up, or closed the bar
        bar.view.removeFromSuperview()
        bar.removeFromParentViewController()
    })
    parent.addChildViewController(bar)
    bar.view.setFrame(parent.view.bounds)         // the bar draws along the bottom of this frame
    parent.view.addSubview(bar.view)
    bar.didMoveToParentViewController(parent)
}

Graine.onRequestPermissionsResult

Call it from an Android activity's onRequestPermissionsResult when that activity shows the voice bar or places calls.

fun Graine.onRequestPermissionsResult(requestCode: Int, grantResults: IntArray): Boolean

The SDK asks for the microphone from the activity in front; forwarding the answer lets the call go ahead once it is granted. In androidMain only.

Returns — Boolean — true when the request was the SDK's (and handled). Example value: true.

Errors — none.

override fun onRequestPermissionsResult(requestCode: Int, permissions: Array<out String>, grantResults: IntArray) {
    if (Graine.onRequestPermissionsResult(requestCode, grantResults)) return
    super.onRequestPermissionsResult(requestCode, permissions, grantResults)
}

Several agents in one app

A support agent in Help, another agent elsewhere — each with its own publishable key, configured under its own name. Each agent has its own settings, chat, voice bar, actions, and scheduling and memory requests; who the user is, the install ID, the memory choice, the screen and the phone's calls are the app's and shared. Across all agents, only one conversation runs at a time. Graine itself is the default agent; the views take an agent name (GraineChat(agent = "support"), GraineAgentBar(agent = …), GraineViews.chat(agent = …)), and Graine.calls.startCall(agent = …) calls a named one.

Graine.configure(GraineConfig(baseUrl = "https://www.graine.ai", publishableKey = "pk_live_support…"), name = "support")
val support = Graine.agent("support")!!
support.chat.open()
Graine.calls.startCall(reason = "billing", agent = "support")

Graine.agent (by name)

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

fun agent(name: String = DEFAULT_AGENT): GraineAgent?

Returns — GraineAgent? — the agent, or null when nothing is configured under that name. Example value: GraineAgent(name="support").

Errors — none.

val support = Graine.agent("support") ?: return

GraineAgent

Use it to work with one particular agent — its chat, voice bar, actions, bookings and memory.

class GraineAgent

Returned by Graine.configure and Graine.agent. Graine is the default agent's; this is any agent's.

What to expect — Calling a function before this agent is configured throws IllegalStateException (“The agent "support" is not configured: call Graine.configure(config, name = "support") first.”).

Its functions: setVariables, currentVariables, registerAction, memories, forgetMemory, presentBooking, scheduleCall, scheduledCalls, cancelScheduledCall, startCall — each with its parameters, what it returns, its errors and an example.

Screen context, actions and components

Tell the agent what the user is looking at, and let it act in your app through handlers you register. The screen is the app's: every agent hears it while it has a live conversation. Values are masked on the device before anything leaves it; report real values. The agent's components (product lists, choices, time slots) are drawn by the SDK's views; an app that draws its own hears them as GraineEvent.Component.

Graine.setScreen

Call it on every meaningful change of what the user can see, so the agent talks about the right thing.

fun setScreen(screen: GraineScreen?)

An unchanged screen is not sent again; the first change goes at once and later ones at most every 400 ms. After a pause, the agent names a field that is INVALID or EMPTY instead of asking “need a hand?”. null clears it.

Returns — nothing.

Errors — IllegalStateException before configure.

val postalCode = "560001"   // what the user typed: the real value, masked on the device
Graine.setScreen(GraineScreen(
    screen = "checkout_address", title = "Delivery address",
    journey = GraineScreen.Journey("Checkout", step = 2, of = 3, next = "Payment"),
    fields = listOf(GraineField("postal_code", label = "Postal code", value = postalCode,
        status = GraineFieldStatus.INVALID, error = "We don't deliver there yet")),
))

Graine.updateField

Call it when one field changes, so a screen described once need not be described again on every keystroke.

fun updateField(field: GraineField)

Merged by name into the current screen (added when it is new) and sent like any screen change. Nothing happens before a screen is set.

Returns — nothing.

Errors — IllegalStateException before configure.

val postalCode = "560034"   // what the user typed now
Graine.updateField(GraineField("postal_code", value = postalCode, status = GraineFieldStatus.FILLED))

Graine.removeField

Call it when a field leaves the screen.

fun removeField(name: String)

Nothing happens when it was never reported.

Returns — nothing.

Errors — IllegalStateException before configure.

Graine.removeField("coupon")

Graine.clearScreen

Call it when the user leaves a screen — in the screen's teardown.

fun clearScreen(screenId: String? = null)

With screenId, only if that screen is still the one described — a screen closing late must not erase the one that replaced it. null clears whatever is there.

Returns — nothing.

Errors — IllegalStateException before configure.

Graine.clearScreen("checkout_address")

Graine.track

Call it to tell the agent about something the user did that informs without interrupting — a coupon applied, a filter changed.

fun track(name: String, data: Map<String, Any?> = emptyMap())

It rides along with the next screen update, among the user's recent events (the last ten are kept). Blank names are ignored. Masked on the device.

Returns — nothing.

Errors — IllegalStateException before configure.

Graine.track("coupon_applied", mapOf("code_length" to 8))

Graine.tap

Call it to tell the agent the user tapped a control the SDK cannot name by itself — a custom-drawn button, say.

fun tap(name: String)

Reported as tap:<name> among the screen's recent events, at most twice a second, and only while a screen is set. Labelled controls are noticed by themselves (GraineConfig.captureTaps).

Returns — nothing.

Errors — IllegalStateException before configure.

Graine.tap("Apply coupon")

Graine.noteInteraction

Call it when the user does something that is not a field edit — scrolls a list, opens a picker — so the SDK does not think they are stuck.

fun noteInteraction()

Restarts the clock that notices a user stuck on a step. Field edits do not count: someone typing one character every forty seconds is exactly who is stuck.

Parameters — none.

Returns — nothing.

Errors — IllegalStateException before configure.

Graine.noteInteraction()

Graine.setVariables

Call it when your app learns something the default agent's prompt uses — a plan, a cart total.

fun setVariables(values: Map<String, Any?>?)

Merged over what is there: null under a key removes it, null for the whole map clears them all. Masked on the device; reaches the next conversation. GraineAgent.setVariables sets another agent's.

Returns — nothing.

Errors — IllegalStateException before configure.

Graine.setVariables(mapOf("plan" to "gold", "cart_total" to 42))

GraineAgent.setVariables

Call it to set prompt variables for one of your other agents.

fun setVariables(values: Map<String, Any?>?)

Graine.setVariables for this agent.

Returns — nothing.

Errors — IllegalStateException when this agent is not configured.

Graine.agent("support")?.setVariables(mapOf("ticket_count" to 2))

Graine.currentVariables

Call it to see exactly which prompt variables the default agent's next conversation will carry — on a debug screen, or before a support request.

fun currentVariables(): Map<String, String>

Every variable the agent will receive, merged in precedence order: the dashboard's defaults, GraineConfig.variables, setVariables, then who is signed in (identify's traits, the identity trait itself withheld). What the next conversation carries, as text; values are masked as they leave the device. A copy: changing it changes nothing. GraineAgent.currentVariables() reads another agent's. On iOS it needs GraineInApp of this version; an older one answers an empty map.

Parameters — none.

Returns — Map<String, String>. Example value: {plan=gold, cart_total=42, name=Asha}.

Errors — IllegalStateException before configure.

val vars = Graine.currentVariables()   // {plan=gold, cart_total=42, name=Asha}

GraineAgent.currentVariables

Call it to see the prompt variables one of your other agents will receive.

fun currentVariables(): Map<String, String>

Graine.currentVariables() for this agent: its dashboard defaults, its configuration's variables, its setVariables, then who is signed in.

Parameters — none.

Returns — Map<String, String> — a copy.

Errors — IllegalStateException when this agent is not configured.

val vars = Graine.agent("support")?.currentVariables().orEmpty()

Graine.registerAction

Call it to let the default agent do one thing in your app — open a screen, apply a filter, change a setting.

fun registerAction(name: String, handler: suspend (args: Map<String, Any?>) -> GraineActionResult): () -> Unit

Declare the action on the agent in the dashboard too: a handler with no declaration is never offered, and a declared action with no handler is refused when the agent asks for it. The handler starts on the main thread (it will usually touch your UI) and may suspend — a network call, a confirmation the user taps — continuing on the main thread. It must answer within six seconds, or the agent is told it was not done. A handler that throws answers error with its message; one cancelled answers error with “The action was cancelled.”. Defining an action again under the same name replaces its handler. GraineAgent.registerAction registers with another agent.

Returns — () -> Unit — call it to unregister this handler.

Errors — IllegalStateException before configure.

val unregister = Graine.registerAction("open_screen") { args ->
    val screen = args["screen"] as? String ?: return@registerAction GraineActionResult.refused("No screen was named.")
    router.open(screen)
    GraineActionResult.ok("Opened $screen.")
}

GraineAgent.registerAction

Call it to give one of your other agents an action.

fun registerAction(name: String, handler: suspend (args: Map<String, Any?>) -> GraineActionResult): () -> Unit

Graine.registerAction for this agent: the same six seconds, the same rules.

Returns — () -> Unit — call it to unregister.

Errors — IllegalStateException when this agent is not configured.

Graine.agent("support")?.registerAction("open_ticket") { args -> openTicket(args["id"] as String); GraineActionResult.ok() }

GraineScreen

Pass it to Graine.setScreen to describe what the user can see.

data class GraineScreen(…)

What to expect — Values are masked on the device before they leave it — report real ones; a screen that pre-redacts only blinds the agent.

GraineScreen.Journey

Pass it in GraineScreen.journey to say where a screen sits in a flow.

data class Journey(val name: String, val step: Int? = null, val of: Int? = null, val next: String? = null)

GraineField

Pass it in GraineScreen.fields (or to updateField) to describe one input.

data class GraineField(…)

What to expect — Its status is what lets the agent name the field that is wrong.

GraineFieldStatus

Use it to say where a field stands.

enum class GraineFieldStatus(val wire: String)

What to expect — INVALID and EMPTY are what make the agent speak up about a field.

GraineActionResult

Return it from an action handler to tell the agent what happened.

data class GraineActionResult(val status: Status, val message: String = "", val data: Map<String, Any?> = emptyMap())

What to expect — The agent speaks about exactly this, so tell the truth: ok only when it really happened.

Its functions: ok, refused, error — each with its parameters, what it returns, its errors and an example.

GraineActionResult.Status

Read it to know how an action went.

enum class Status(val wire: String) { OK("ok"), REFUSED("refused"), ERROR("error") }

GraineActionResult.ok

Return it when the action happened.

fun ok(message: String = "", data: Map<String, Any?> = emptyMap()): GraineActionResult

Returns — GraineActionResult with status OK.

Errors — none.

GraineActionResult.ok("The app is now in Spanish.")

GraineActionResult.refused

Return it when the action will not happen, and say why.

fun refused(message: String): GraineActionResult

Returns — GraineActionResult with status REFUSED.

Errors — none.

GraineActionResult.refused("There is no order with that number.")

GraineActionResult.error

Return it when the action was tried and failed.

fun error(message: String): GraineActionResult

Returns — GraineActionResult with status ERROR.

Errors — none.

GraineActionResult.error("The network is unavailable.")

GraineComponent

Read it to draw a component the agent sent, in an interface of your own.

data class GraineComponent(val id: String, val kind: String?, val title: String?, val payload: Map<String, Any?>)

Carried by GraineChatTurn.component and the event GraineEvent.Component. The SDK's own views draw components themselves; one you draw yourself is answered with Graine.chat.answerWidget (GraineChat.answerWidget).

GraineChat.answerWidget

Call it when the user answers a component the agent drew that you draw yourself — a choice tapped, a slot picked.

fun answerWidget(id: String, data: Map<String, Any?>, summary: String)

Sends the answer on the conversation that is live with that agent — the chat, else the voice bar's call. data is the structured answer, for your webhook; summary is the sentence that becomes the user's turn (“The blue one, please”) — without it the conversation does not move. The SDK's own views answer for themselves. On iOS it needs GraineInApp of this version; an older one does nothing.

Returns — nothing.

Errors — IllegalStateException when the agent is not configured.

// Your own `choices` view calls this when the user taps one.
fun onChoiceTapped(component: GraineComponent, choice: String, label: String) {
    Graine.chat.answerWidget(component.id, mapOf("choice" to choice), summary = label)
}

Calls the user places

Calls like WhatsApp, on the phone's own call screen and over the lock screen, going on with the screen off: the user calls the agent with startCall; the agent can also ring the user (Calls Graine rings). Only one call can be live: a ring that arrives during a call is reported as missed, reason busy.

What a call does on each platform. Both platforms start a call at once on the agent's settings already kept on the device, and refresh them behind the call.

• Android (the Android SDK's engine): opening the call has 15 seconds — “The call could not connect within 15 seconds.” Once connected, nothing at all arriving for 50 seconds (two 25-second keep-alive periods) ends the call: it ends ENDED with reason failed, and the SDK's call screen says “Call failed”. Sending never holds a call up on a slow network: at most 300 ms of the user's audio waits, the oldest dropped first. Hanging up lets go of the microphone at once, and a close the network cannot carry is forced within about a second.
• iOS (the iOS SDK's engine, under CallKit): everything before the conversation opens — loading the agent, connecting — has one 20-second deadline: “The call could not connect within 20 seconds.” (the connection itself gives up after 15 seconds of trying to open: “The conversation did not open within 15 seconds.”). Once the conversation is open, the call's audio comes from CallKit; if it does not arrive, the SDK waits 3 seconds, starts the audio itself once, and waits 3 seconds more — then the call fails: “The call's audio could not start.”

A call that never connected reaches Graine.calls.outcomes as FAILED with these sentences in reason; the call screen says “Call failed”.

WebRTC. With the platform's WebRTC module in the app (WebRTC calls), calls in both directions carry their audio over WebRTC, as GraineCallsConfig.callTransport and the agent's In-app call audio setting allow. A call WebRTC cannot set up within about 12 seconds continues on the WebSocket inside the same call — “Connecting…” shows a moment longer — and Graine.calls.state says which one carried it (transport, transportFallbackReason, GraineCallInfo).

scope.launch {
    val call = Graine.calls.state.first { it.state == GraineCallState.ACTIVE }
    if (call.transportFallbackReason != null) println("Call ${call.callId} is on the WebSocket: ${call.transportFallbackReason}")
}

GraineCalls

Use it for native calls: configure them, place one, control it, and follow its state and outcomes.

class GraineCalls

Graine.calls — the app's one call engine, whichever agent a call is with. Its functions may be called from any thread.

What to expect — state always holds the latest value; outcomes and incoming are not replayed, so collect them from app start.

Its functions: configure, startCall, end, setMuted, setSpeaker, answer, decline, callBack, dismissMissedCall, enableVoIPPushes, onNewToken, handlePush, requestCallPermissions, openCallSettings — each with its parameters, what it returns, its errors and an example.

GraineCalls.configure

Call it once at launch to set how calls ring and what they show.

fun configure(config: GraineCallsConfig)

On iOS, call it before enableVoIPPushes(). On Android it also creates the notification channels for rings, ongoing calls and missed calls.

Returns — nothing.

Errors — IllegalStateException before Graine.configure.

Graine.calls.configure(GraineCallsConfig(displayName = "Acme", ringTimeoutSeconds = 30))

GraineCallsConfig

Pass it to Graine.calls.configure to set how calls ring and what they show.

data class GraineCallsConfig(…)

What to expect — Set once at launch. Each field applies on the platforms its description names.

GraineCallTransport

Pass it in GraineCallsConfig.callTransport to choose how native calls carry their audio; read it back in GraineCallInfo.transport.

enum class GraineCallTransport(val wire: String) { AUTO("auto"), WEBSOCKET("websocket"), WEBRTC("webrtc") }

It applies to calls in both directions: one the user places (startCall, callBack) and one Graine rang (a booked call, Ring now). WebRTC needs the platform's WebRTC module in the app (WebRTC calls). Mapped to each platform SDK's own setting.

What to expect — The agent's In-app call audio setting wins over the app: Standard keeps every call on the WebSocket, whatever callTransport says, from each app's next start. A call that tried WebRTC and could not use it before any audio flowed continues on the WebSocket inside the same call, and GraineCallInfo.transport says WEBSOCKET, with transportFallbackReason saying why. AUTO is only something you choose; a call's transport is WEBRTC or WEBSOCKET.

Its functions: ofCall — each with its parameters, what it returns, its errors and an example.

GraineCalls.startCall

Call it from a “Call us” button to let the user call the agent.

fun startCall(reason: String? = null, variables: Map<String, Any?> = emptyMap(), agent: String? = null): String?

The call screen opens and the call connects. reason becomes the prompt's call_reason; variables are this call's own prompt variables, over the SDK's (masked on the device). It answers on the spot.

Returns — String? — the call's ID, which every outcome carries; null when another call is live or, on Android, when no screen of the app is in front to start it from. Example value: "call_6f1c2a9e-7d1b-4c47-9a6e-2f0d8b1c5e44".

Errors — IllegalStateException when the agent is not configured. A call that cannot connect is a FAILED outcome, not an exception.

val callId = Graine.calls.startCall(reason = "billing_help") ?: return showBusy()

GraineAgent.startCall

Call it to let the user call one of your other agents.

fun startCall(reason: String? = null, variables: Map<String, Any?> = emptyMap()): String?

A shortcut for Graine.calls.startCall(reason, variables, agent = name), with this agent's name filled in.

Returns — String? — the call's ID, or null when another call is live.

Errors — IllegalStateException when this agent is not configured.

Graine.agent("support")?.startCall(reason = "billing_help")

GraineCalls.end

Call it from your own hang-up control.

fun end()

Hangs up — or, while the call rings, declines it.

Parameters — none.

Returns — nothing.

Errors — none.

Graine.calls.end()

GraineCalls.setMuted

Call it from your own mute control.

fun setMuted(muted: Boolean)

Stops sending the user's voice without ending the call.

Returns — nothing.

Errors — none.

Graine.calls.setMuted(true)

GraineCalls.setSpeaker

Call it from your own loudspeaker control.

fun setSpeaker(on: Boolean)

Turning it off sends the audio back to a connected headset, or to the earpiece when there is none.

Returns — nothing.

Errors — none.

Graine.calls.setSpeaker(true)

GraineCallInfo

Read it to draw a call screen: the call's state, who is calling, the controls and the last line said.

data class GraineCallInfo(…)

Graine.calls.state.

What to expect — Every field has a value at every moment; with no call, state is IDLE and the rest are empty — except missedCall, kept until it is called back or dismissed.

Why a call is on the WebSocket — the values of transportFallbackReason. Log them; the person sees nothing different, only “Connecting…” a moment longer.

GraineCallState

Read it to know where the one native call is.

enum class GraineCallState { IDLE, RINGING, CONNECTING, ACTIVE, ENDED }

What to expect — IDLE → RINGING (the agent rings) or CONNECTING (the user called) → ACTIVE → ENDED, then IDLE again once reported.

GraineCallOutcome

Read it to send what became of a call to your server.

data class GraineCallOutcome(…)

From Graine.calls.outcomes, as it happens.

What to expect — One call reports RINGING (an agent's call), then ANSWERED followed by ENDED or FAILED; or DECLINED, MISSED or FAILED alone. hosted means Graine rang it, and the SDK has already told Graine. Do not rely on its order relative to state.

GraineCallOutcome.Kind

Read it to branch on what became of a call.

enum class Kind(val wire: String)

GraineCallScreen

Use it to show the SDK's call screen in a Compose Multiplatform UI while there is a call.

@Composable
expect fun GraineCallScreen(modifier: Modifier = Modifier)

In ai.graine:inapp-kmp-compose. The ring (Answer, Decline — “Scheduled call” for a call Graine rang), connecting, the call with its controls, and a missed ring with Call back, in the agent's design. Show it whenever Graine.calls.state.value.showsCallScreen is true. On iOS it is drawn in place, and VoiceOver reaches into it. On Android the SDK's call screen is a full-screen activity that also covers the lock screen and opens by itself when a call rings or is placed; composing this brings it to the front.

Returns — nothing (a composable).

Errors — none.

val call by Graine.calls.state.collectAsState()
if (call.showsCallScreen) GraineCallScreen(Modifier.fillMaxSize())

GraineViews.callScreen

Call it on iOS to get the call screen as a view controller, for while the app is open.

fun callScreen(): UIViewController

The ring, the call, and a missed ring with Call back — the app's, whichever agent calls.

Parameters — none.

Returns — UIViewController.

Errors — IllegalStateException before Graine.configure.

import platform.UIKit.UIViewController
 
fun showCallScreen(from: UIViewController) {
    from.presentViewController(GraineViews.callScreen(), animated = true, completion = null)
}

Calls Graine rings

Graine rings your users itself — a call the agent booked in a conversation, one the user booked, or one your team booked — once your push credentials are uploaded (Workspace settings → In-app calling). On iOS, call enableVoIPPushes() at every launch; on Android, add Firebase Cloud Messaging to the app and the SDK registers for pushes itself (an app with a messaging service of its own forwards its token and data messages to onNewToken and handlePush). The SDK registers the device, rings each call on the phone's own call screen (“Scheduled call”), and reports what became of it. Your own server can ring the same way, with a push of type agent_call.

A call the person answers carries its audio exactly as one they place: over WebRTC when the app includes the platform's WebRTC module and GraineCallsConfig.callTransport and the agent's In-app call audio setting allow it (WebRTC calls) — prepared while the ring shows, so answering connects as fast as before — and Graine.calls.state reports transport and transportFallbackReason for it too.

The push your server sends (data only, nothing personal): type: "agent_call", call_id (required — every outcome carries it back), reason (the prompt's call_reason), caller_name (what the ring shows), variables (a JSON object as a string: more prompt variables), and agent_id (which of the app's agents the call is with).

GraineCalls.enableVoIPPushes

Call it at every launch on iOS, so the agent's calls can ring a closed app.

fun enableVoIPPushes()

iOS wakes a closed app for a VoIP push and hands it over once this has run; the SDK registers the token with Graine when Graine rings this app. Call configure first. Android: does nothing — with Firebase in the app the SDK registers for pushes itself (see onNewToken and handlePush for an app with its own messaging service).

Parameters — none.

Returns — nothing.

Errors — IllegalStateException before Graine.configure.

Graine.calls.enableVoIPPushes()

GraineCalls.onNewToken

Call it on Android from a FirebaseMessagingService of your own, in onNewToken. Without one, the SDK's own messaging service receives each new token, and the SDK reads the current one when it starts.

fun onNewToken(token: String)

The token is kept and registered with Graine when Graine rings this app. It works before Graine.configure, as a messaging service may start first. iOS: does nothing — the VoIP token comes through enableVoIPPushes().

Returns — nothing.

Errors — none.

override fun onNewToken(token: String) = Graine.calls.onNewToken(token)

GraineCalls.handlePush

Call it on Android first thing in the onMessageReceived of a FirebaseMessagingService of your own. Without one, the SDK's own messaging service calls it for every message.

fun handlePush(data: Map<String, String>): Boolean

When the message is a call — Graine's own ring, or one your server sent — the SDK rings it and the answer is true; your own messages answer false. iOS: always false — a VoIP push reaches the SDK by itself.

Returns — Boolean — true when it was a call and you should do nothing more with it. Example value: true.

Errors — none.

override fun onMessageReceived(message: RemoteMessage) {
    if (Graine.calls.handlePush(message.data)) return
    // …your own messages
}

GraineCalls.answer

Call it from a call screen of your own to pick up the ringing call.

fun answer()

The SDK's own call screen does this itself.

Parameters — none.

Returns — nothing.

Errors — none.

Graine.calls.answer()

GraineCalls.decline

Call it from a call screen of your own to decline the ringing call.

fun decline()

Reported as DECLINED. For a call Graine rang, nothing rings that user again for 6 hours.

Parameters — none.

Returns — nothing.

Errors — none.

Graine.calls.decline()

GraineCalls.callBack

Call it from a missed-call screen's “Call back”.

fun callBack(): String?

Returns the last missed call: the user calls the agent back, with the missed call's reason and its agent. On Android it starts from the screen in front.

Parameters — none.

Returns — String? — the new call's ID, or null when it could not start (another call is live, or no screen is in front). Example value: "call_8a20d3c1-…".

Errors — none.

Graine.calls.callBack()

GraineCalls.dismissMissedCall

Call it when the user has seen the missed call, so a call screen can go.

fun dismissMissedCall()

Clears GraineCallInfo.missedCall.

Parameters — none.

Returns — nothing.

Errors — none.

Graine.calls.dismissMissedCall()

GraineIncomingCall

Read it to know an agent's call started ringing on this device — for your own UI or analytics.

data class GraineIncomingCall(…)

From Graine.calls.incoming. The SDK shows the ring itself.

What to expect — It carries only what the ring shows: nothing personal.

GraineMissedCall

Read it to show a missed call with “Call back”.

data class GraineMissedCall(…)

GraineCallInfo.missedCall: the last ring nobody answered, kept until callBack() or dismissMissedCall(). A ring refused because another call was live is not kept.

Permissions and the setup check

What a call needs from the phone, and from your app's setup, in one place — read from the platform SDKs, the same on both. The SDK never asks on its own at launch: it asks for the microphone when a call starts without it, and requestCallPermissions() asks earlier, when your app chooses (on Android from a transparent screen of the SDK's own, over the app's screen in front). callSetupProblems says what your setup still lacks; the platform SDK logs each problem once from configure on. A problem is never an exception: calls still work where they can. On iOS these need GraineInApp of this version.

GraineCalls.callPermissions

Read it to see which call permissions the phone holds now.

val callPermissions: GraineCallPermissions

The microphone, and on Android the ring's notifications (13+ asks) and the full-screen ring (14+, Settings only); on iOS those two are NOT_NEEDED — CallKit rings and draws its own screen.

Returns — a GraineCallPermissions. Read it again when the app returns to the foreground: the user may have changed Settings.

Errors — IllegalStateException before Graine.configure.

if (!Graine.calls.callPermissions.allGranted) showFinishSetupCard()

GraineCalls.requestCallPermissions

Call it at a moment you choose — onboarding, a "Call me" screen — to ask for what a call needs.

suspend fun requestCallPermissions(): GraineCallPermissions

Asks for the call permissions the system's dialog can still ask for — the microphone, and notifications on Android 13+ — and returns them as they stand after; suspends until the user answers (at once when there is nothing to ask). The full-screen ring has no dialog: openCallSettings(GraineCallPermission.FULL_SCREEN) opens its page.

Returns — a GraineCallPermissions.