Android SDK reference

Every public declaration of the Android SDK, ai.graine:inapp-android 0.8.0 — Kotlin first, and callable from Java (@JvmStatic, @JvmOverloads, GraineCallback) — 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 Android.

Requirements, install, permissions and initialisation

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

dependencies {
    implementation("ai.graine:inapp-android:0.10.3")
    // For calls that ring: Firebase Cloud Messaging, as Firebase describes
    implementation(platform("com.google.firebase:firebase-bom:<latest>"))
    implementation("com.google.firebase:firebase-messaging")
}

What the library's manifest merges into your app

What the SDK asks at run time: only RECORD_AUDIO — at voice.start() for the voice bar (forward your activity's onRequestPermissionsResult to voice.onRequestPermissionsResult), and from the call screen when a call is placed or after Answer (a refusal ends the call FAILED; no answer within 60 seconds too). Your app asks for notifications on Android 13 and up; without them, a ring with your app closed or in the background cannot show and ends MISSED. Your app offers the full-screen setting on Android 14 and up:

Android · Kotlin — onboarding

private val ask = registerForActivityResult(ActivityResultContracts.RequestMultiplePermissions()) { }
 
fun askForAgentPermissions() {
    val wanted = mutableListOf(Manifest.permission.RECORD_AUDIO)
    if (Build.VERSION.SDK_INT >= 33) wanted += Manifest.permission.POST_NOTIFICATIONS   // rings
    ask.launch(wanted.toTypedArray())
}
 
fun offerFullScreenRings() {
    val nm = getSystemService(NotificationManager::class.java)
    if (Build.VERSION.SDK_INT >= 34 && !nm.canUseFullScreenIntent()) {
        startActivity(Intent(Settings.ACTION_MANAGE_APP_USE_FULL_SCREEN_INTENT, Uri.parse("package:$packageName")))
    }
}

Notification channels the SDK creates in calls.configure (visible in the phone's settings): Incoming calls (high importance, the ringtone, vibration, shown on the lock screen), Incoming calls (app ringtone) (used while the SDK plays the brand's Graine or Soft ring), Missed calls and Ongoing calls.

Not using calls? On Android 14 and up, Google Play asks apps that declare USE_FULL_SCREEN_INTENT or FOREGROUND_SERVICE_MICROPHONE to justify them. An app that never places or receives calls removes them in its own manifest:

XML — AndroidManifest.xml (an app without calls)

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">
    <uses-permission android:name="android.permission.USE_FULL_SCREEN_INTENT" tools:node="remove" />
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MICROPHONE" tools:node="remove" />
    <application>
        <service android:name="ai.graine.inapp.GraineCallService" tools:node="remove" />
    </application>
</manifest>

Adding WebRTC calls

The SDK's native calls — the ones the user places (startCall, a “Call” button) and the ones Graine rings and the user answers — can carry their audio over WebRTC instead of the WebSocket. It is one more module, opt-in per app build.

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

dependencies {
    implementation("ai.graine:inapp-android:0.10.3")
    implementation("ai.graine:inapp-android-rtc:0.10.3")   // WebRTC for calls: always the same version as the SDK
}

Nothing else changes — no code, no permission to ask for, no setting: the calls find the module by themselves, and the ring, the call screen, “Connecting…”, the listeners and the outcomes are as before. It is for native calls only; the voice bar's audio follows GraineConfig.transport and the dashboard's Call audio.

What the person 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 phone's own echo canceller. The call is prepared at the tap — or while the 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 carries on over 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 (ENDED, FAILED, “The call's connection was lost.”).

// Application.onCreate — AUTO is the default; WEBRTC asks for WebRTC wherever it can carry the call
GraineInApp.get().calls.configure(GraineCallsConfig(displayName = "Acme", callTransport = GraineCallTransport.WEBRTC))
 
// Which one carried a call, once it is ACTIVE
GraineInApp.get().calls.addListener(object : GraineCallListener {
    override fun onCallState(state: GraineCallState, call: GraineCall?) {
        if (state != GraineCallState.ACTIVE) return
        val calls = GraineInApp.get().calls
        Log.d("Graine", "audio over ${calls.transport}; fallback: ${calls.transportFallbackReason}")
    }
})

Initialise

Android · Kotlin — AcmeApp.kt

class AcmeApp : Application() {
    override fun onCreate() {
        super.onCreate()
        val graine = GraineInApp.init(this, GraineConfig(
            baseUrl = "https://www.graine.ai",
            publishableKey = "pk_live_…",                // Agent → Embed & Widgets → Install
            appVersion = BuildConfig.VERSION_NAME,
            debug = BuildConfig.DEBUG,
        ))
        graine.calls.configure(GraineCallsConfig(
            displayName = "Acme",
            smallIcon = R.drawable.ic_stat_call,         // monochrome; 0 = the platform's call icon
        ))
    }
}
 
class MainActivity : Activity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.main)
        GraineInApp.get().voice.attach(this)             // the voice engine, idle: once; it follows the user between activities
        findViewById<FrameLayout>(R.id.root).addView(GraineAgentBarView(this),
            FrameLayout.LayoutParams(MATCH_PARENT, WRAP_CONTENT, Gravity.BOTTOM))
    }
 
    override fun onRequestPermissionsResult(requestCode: Int, permissions: Array<out String>, grantResults: IntArray) {
        if (!GraineInApp.get().voice.onRequestPermissionsResult(requestCode, grantResults))
            super.onRequestPermissionsResult(requestCode, permissions, grantResults)
    }
}

Jetpack Compose hosts the views with AndroidView(factory = { GraineAgentBarView(it) }). Everything that touches a view runs on the main thread; nothing the SDK does blocks it. From Java, every entry point works with only the arguments you need (Notes for Java).

Install and the first answer

Configure the agent once, in Application.onCreate, then reach it anywhere with GraineInApp.get(). The SDK loads the agent's settings from Graine once per launch; until they arrive it uses the last ones kept on the device, so a call that wakes a closed app is drawn in the brand's design. Know they have arrived with GraineInApp.session or GraineListener.onSessionReady.

GraineInApp.init

Call it once per agent in Application.onCreate to start the SDK.

@JvmStatic @JvmOverloads
companion · fun init(application: Application, config: GraineConfig, name: String = DEFAULT): GraineInApp

It starts loading the agent's settings at once. Without a name it makes the default agent, which GraineInApp.get() returns; an app with several agents names the others (Several agents). Asking again for a name already set up gives you that same agent; the configuration passed the second time is ignored.

Returns — GraineInApp — the agent (GraineInApp).

Errors — none. A key or allowed-domain problem surfaces when the settings load, in GraineListener.onError.

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

GraineInApp

Use it for everything the SDK does: it is the agent, and the way to its chat, its voice bar, calls and bookings.

class GraineInApp private constructor(…)

Made once with GraineInApp.init and reached anywhere with GraineInApp.get(). Who the user is, their memory choice, the screen and the call engine belong to the app and are shared by every agent; the rest is this agent's.

What to expect — Everything that touches a view runs on the main thread, and callbacks arrive on it with exactly one of value and error set; nothing touches the network on it. A request made before the agent's settings have loaded waits for them.

Its functions: init, get, find, identify, setMemory, memories, forgetMemory, setScreen, updateField, removeField, clearScreen, setVariables, currentVariables, track, tap, reportEvent, noteInteraction, configureFriction, registerAction, registerDeferredAction, checkActions, clearPendingWidget, answerWidget, presentBooking, scheduleCall, scheduledCalls, cancelScheduledCall, themeTokens, previewDesign, addListener, removeListener — each with its parameters, what it returns, its errors and an example.

GraineConfig

Pass it to GraineInApp.init to say which agent to start and how.

data class GraineConfig @JvmOverloads constructor(…)

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.

GraineConfig.Timing

Pass it in GraineConfig.timing only for an app used on very slow networks, to give the voice engine longer to load.

data class Timing @JvmOverloads constructor(…)

The voice bar's engine loads in the background when you call voice.attach. The SDK watches that it keeps moving rather than giving it one flat timer, and reloads it when it stalls.

What to expect — Every value is in milliseconds. The defaults suit almost every app.

SessionConfig

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

data class SessionConfig(…)

GraineInApp.session, and the argument of GraineListener.onSessionReady.

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. Missing fields are empty, never a crash.

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 · 6:05 PM” row under the day it happened) and the agent continues from them; the chat window's header then offers New conversation. Who the user is belongs to the app: identifying on any agent identifies them for every agent.

GraineInApp.identify

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

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

Traits become prompt variables and land on the call record, masked on the device. The trait the agent's Who is the user? setting names (user_id unless the dashboard chose email, phone or a custom trait) is also how Graine tells your users apart — what lets the agent remember a user and ring them — and it goes only to Graine, never into the prompt beyond the trait itself. A placeholder ("guest", "0", a masked value) identifies nobody.

Identity is taken at the start of each conversation, so a change takes effect from the next one. null signs out of every agent: this device is released for that user (it stops being rung for them and stops counting toward their devices), the chat they were having is cleared, and later conversations are anonymous. Identifying a different user does the same for the previous one.

Returns — nothing.

Errors — none.

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

GraineInApp.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 — none.

GraineInApp.get().setMemory(false)

GraineInApp.memories

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

fun memories(done: GraineCallback<List<GraineMemory>>)

What the agent remembers about the signed-in user, newest first, at most 100, already redacted. Only from a device that user is using.

Returns — nothing; the answer arrives in done. Example value (in done): [GraineMemory(id="m_31", text="Prefers a call after 6 PM", createdAt=Mon Oct 12 09:15:00 UTC 2026, updatedAt=null)].

Errors — in done's GraineError: IDENTITY_REQUIRED (“Nobody is signed in: identify() the user first.”) with nobody signed in; DEVICE_LIMIT from a device the user is not using the agent on; RATE_LIMITED, NETWORK, UNAVAILABLE, INVALID_KEY, ORIGIN_REFUSED.

GraineInApp.get().memories { list, error ->
    if (error != null) showMessage(error.message) else render(list.orEmpty().map { it.text })
}

GraineInApp.forgetMemory

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

@JvmOverloads
fun forgetMemory(done: GraineCallback<Int>? = null)

Deletes everything the agent remembers about the signed-in user — only from a device that user is using. The conversation is part of what is forgotten: once it succeeds, the chat on screen is cleared too; a refusal leaves it as it was.

Returns — nothing; the count arrives in done. Example value (in done): 3.

Errors — in done's GraineError: IDENTITY_REQUIRED (“Nobody is signed in: identify() the user first.”), DEVICE_LIMIT, RATE_LIMITED, NETWORK, UNAVAILABLE, INVALID_KEY, ORIGIN_REFUSED.

GraineInApp.get().forgetMemory { deleted, error ->
    if (error == null) showMessage("Forgot $deleted things.")
}

GraineChat.newConversation

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

@JvmOverloads
fun newConversation(done: GraineCallback<Unit>? = null): Unit

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 lines 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.

Returns — nothing; the result arrives in done.

Errors — in done's GraineError: DEVICE_LIMIT, NETWORK, RATE_LIMITED, UNAVAILABLE, … — the chat is then as it was, connected again.

GraineInApp.get().chat.newConversation { _, error -> if (error != null) showMessage(error.message) }

GraineCallback

Pass one to a request to hear its answer: the value, or why there is none.

fun interface GraineCallback<T>

Every request the SDK makes to Graine on the user's behalf answers through one: memories, bookings, cancelling.

What to expect — Called once, on the main thread, with exactly one of value and error set. In Kotlin, a trailing lambda { value, error -> }; in Java, (value, error) -> { … }.

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

GraineCallback.onResult

Implement it to receive a request's answer.

fun onResult(value: T?, error: GraineError?)

Returns — nothing.

Errors — none.

val done = GraineCallback<Int> { deleted, error ->
    if (error != null) showMessage(error.message) else showMessage("Deleted $deleted")
}

GraineMemory

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

data class GraineMemory @JvmOverloads constructor(val id: String, val text: String, val createdAt: java.util.Date? = null, val updatedAt: java.util.Date? = null)

What to expect — From memories(): newest first, at most 100, already redacted. Only for the signed-in user, from one of their devices. The dates are moments; show them in the device's time zone.

SessionIdentity

Read it to know which trait names the user, and on how many devices they may use the agent.

data class SessionIdentity(val field: String, val devicesPerUser: Int)

SessionConfig.identity.

What to expect — From an older server that does not say: the user_id trait and 2 devices.

Chat

The typed conversation with the agent: GraineInApp.get().chat, or GraineInApp.get("support").chat for another agent. The voice bar switches to it when the dashboard offers chat (Appearance → mode: voice, chat or both); GraineChatView and GraineChatActivity show it as a whole screen. Everything the agent can do on a call works here too — it sees the screen you report, runs your actions and draws its components — and each of its replies streams into a single bubble. A line typed while the chat is connecting — or reconnecting after a drop, which it does by itself while the user is in it — is sent as soon as it can be, never lost. One conversation at a time across every agent: opening the chat ends a voice-bar call, starting a call ends the chat, and a native call holds the chat until it is over.

Where Graine rings this app, the chat window shows the user's booked calls first in the conversation, with Book a call where booking is available (Booking with the SDK's sheet).

GraineChat

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

class GraineChat internal constructor(…) : ChatSource

GraineInApp.get().chat. What the voice bar's chat window and GraineChatView draw.

What to expect — Main thread. Changes reach GraineListener.onChatState and onChatMessage, and every change listener. messages empties on sign-out, when another user signs in, after a successful forgetMemory() and on newConversation().

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

GraineChat.open

Call it from your own “Chat with us” button to open the chat.

@JvmOverloads
fun open(size: GraineChatSize? = null): Unit

Connects the chat. A GraineAgentBarView on screen moves to its chat, where the agent offers one, and draws it at size — this open's own, until close(); null follows GraineConfig.chatSize, then the dashboard's Window size.

Returns — nothing.

Errors — none.

GraineInApp.get().chat.open(GraineChatSize.FULL)

GraineChat.connect

Call it to connect the chat yourself — for a chat screen of your own that is not a GraineChatView.

fun connect(): Unit

Opens the conversation if it is not open or opening, and fetches the upcoming calls. A chat window on screen does this by itself.

Parameters — none.

Returns — nothing.

Errors — none.

GraineInApp.get().chat.connect()

GraineChat.send

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

override fun send(text: String)

On screen at once; sent now when the chat is up, or as soon as it is (a message typed while not connected is SENDING). Typing is the user asking again: a chat that gave up connects again. Blank lines are ignored.

Returns — nothing.

Errors — none.

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

GraineChat.close

Call it when the user leaves your chat screen.

fun close(): Unit

Ends the conversation: the agent is told it is over and no reconnect follows. What was said stays visible; a later connect or send begins a fresh conversation below it.

Parameters — none.

Returns — nothing.

Errors — none.

GraineInApp.get().chat.close()

GraineChat.clear

Call it to clear the lines on screen — when your app starts a new topic, for example.

fun clear(): Unit

Only the screen clears; the conversation itself goes on — connected stays connected, a message still waiting for the connection is still sent, and nothing Graine keeps is touched: a conversation that continues comes back with the next history, and the agent's memories stay. To start a fresh conversation, use newConversation; to forget, forgetMemory.

Parameters — none.

Returns — nothing.

Errors — none.

GraineInApp.get().chat.clear()

GraineChat.shown

Call it from a chat screen of your own when it comes on screen (true) and leaves it (false).

override fun shown(visible: Boolean): Unit

The chat connects while it is on screen, and is kept for 15 seconds after it leaves, for the next screen to take, before it closes. GraineChatView does this by itself.

Returns — nothing.

Errors — none.

override fun onStart() { super.onStart(); GraineInApp.get().chat.shown(true) }

GraineChat.addChangeListener

Call it to redraw a chat screen of your own whenever anything the chat shows changes.

override fun addChangeListener(listener: Runnable)

The listener runs on the main thread after every change — a line arriving or growing, the connection coming up or dropping, the upcoming calls.

Returns — nothing.

Errors — none.

GraineInApp.get().chat.addChangeListener(redraw)

GraineChat.removeChangeListener

Call it when your chat screen goes away, to stop hearing changes.

override fun removeChangeListener(listener: Runnable)

Returns — nothing.

Errors — none.

GraineInApp.get().chat.removeChangeListener(redraw)

ChatSource

Implement it to show a conversation your app runs itself in the SDK's chat views.

interface ChatSource

What a chat window draws from — GraineAgentBarView.chat and GraineChatView.source. The SDK's own is GraineChat, the default everywhere.

What to expect — Called on the main thread. typing and failed default to false, and shown does nothing unless you override it.

Its functions: send, shown, addChangeListener, removeChangeListener — each with its parameters, what it returns, its errors and an example.

ChatSource.send

Implement it to send the line the user typed in the chat window.

fun send(text: String)

Returns — nothing.

Errors — none.

override fun send(text: String) { myConversation.post(text) }

ChatSource.shown

Implement it to open your conversation when a chat window shows it, and let it go when none does.

fun shown(visible: Boolean)

Called with true when a chat window showing this conversation comes on screen, false when it leaves. Does nothing unless overridden.

Returns — nothing.

Errors — none.

override fun shown(visible: Boolean) { if (visible) myConversation.connect() }

ChatSource.addChangeListener

Implement it so the chat window hears every change to your conversation.

fun addChangeListener(listener: Runnable)

Returns — nothing.

Errors — none.

override fun addChangeListener(listener: Runnable) { listeners += listener }

ChatSource.removeChangeListener

Implement it so a chat window can stop hearing changes.

fun removeChangeListener(listener: Runnable)

Returns — nothing.

Errors — none.

override fun removeChangeListener(listener: Runnable) { listeners -= listener }

GraineChatTurn

Read it to draw one message of the chat.

data class GraineChatTurn @JvmOverloads constructor(…)

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 every reconnect was spent — the next message, or a retry, sends it. Restored messages arrive once, when the chat opens, for a signed-in user 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. Restored lines never reach onChatMessage.

GraineChatTurn.Delivery

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

enum class Delivery { SENDING, SENT, FAILED }

What to expect — Only meaningful on the user's messages: SENDING → SENT; FAILED once every reconnect was spent.

GraineChatTurn.Channel

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

enum class Channel { CHAT, VOICE }

What to expect — VOICE only on a restored message.

Role

Read it to know who said a line.

enum class Role { AGENT, CUSTOMER }

ChatRows

Use it to lay out a chat of your own the way the SDK's chat window draws it: a bubble per message, one row for an earlier call, and a line where the day changes.

object ChatRows

From GraineInApp.get().chat.messages. A conversation all from today is a bubble per message. A conversation that continues from before gets a day line — Today, Yesterday or a date — before its first row and wherever the phone's day changes between rows, and a run of an earlier call's messages on one day becomes one “Voice call · 6:05 PM” row, never the call's transcript. The SDK's own chat window draws exactly these rows. Every function is static, so Java calls ChatRows.build(messages) as Kotlin does.

What to expect — Pure: no state, no network, any thread. Days are the phone's, in its time zone unless you pass another.

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

ChatRows.Row

Read it for one row of a chat window: a day line, an earlier call, or a message.

sealed class Row

From ChatRows.build, oldest first. Branch on its three kinds with when.

ChatRows.build

Call it for the rows to draw in a chat of your own, in order.

@JvmStatic @JvmOverloads
fun build(turns: List<GraineChatTurn>, now: java.util.Date = java.util.Date(), zone: java.util.TimeZone = java.util.TimeZone.getDefault()): List<Row>

A day line goes before the first row when it is not from today, and wherever the day changes between rows; a run of an earlier call's messages on one day is one Voice row (a day line never sits inside one); every other message is a Turn. Build again whenever the chat changes (addChangeListener).

Returns — List<ChatRows.Row> (ChatRows.Row). Example value: [Day(day=yesterday, date=2026-10-14, …), Voice(id=voice-t1, …, first=0, last=5), Day(day=today, …), Turn(turn=GraineChatTurn(id=t7, …))].

Errors — none.

val clock = android.text.format.DateFormat.getTimeFormat(this)            // the phone's short time
for (row in ChatRows.build(GraineInApp.get().chat.messages)) when (row) {
    is ChatRows.Row.Day -> addDayLine(ChatRows.dayLabel(row))                // Today, Yesterday, Tue 14 Oct
    is ChatRows.Row.Voice -> clock.format(row.at).let { addCallRow(ChatRows.callLabel(it), ChatRows.callSpoken(it)) }
    is ChatRows.Row.Turn -> addBubble(row.turn)
}

ChatRows.dayLabel

Call it for the words on a day line.

@JvmStatic @JvmOverloads
fun dayLabel(day: Row.Day, now: java.util.Date = java.util.Date(), zone: java.util.TimeZone = java.util.TimeZone.getDefault(), locale: java.util.Locale = java.util.Locale.getDefault()): String

“Today”, “Yesterday”, else the date in the phone's own language and order — “Tue 14 Oct” — with the year when it is not this year.

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

Errors — none.

val dayLines = ChatRows.build(GraineInApp.get().chat.messages).filterIsInstance<ChatRows.Row.Day>().map { ChatRows.dayLabel(it) }

ChatRows.callLabel

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

@JvmStatic
fun callLabel(clock: String): String

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

Errors — none.

val label = ChatRows.callLabel("6:05 PM")   // "Voice call · 6:05 PM"

ChatRows.callSpoken

Call it for what a screen reader says for an earlier call's row.

@JvmStatic
fun callSpoken(clock: String): String

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

Errors — none.

val spoken = ChatRows.callSpoken("6:05 PM")   // the row's contentDescription

ChatRows.offersNewConversation

Call it to decide whether your chat's header offers New conversation.

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

New conversation belongs to a conversation that continues from before: it is offered while restored messages are on screen, and calls chat.newConversation().

Returns — Boolean — true when any of them is restored. Example value: true.

Errors — none.

val offerNew = ChatRows.offersNewConversation(GraineInApp.get().chat.messages)

ChatRows.offersStarters

Call it to decide whether your chat shows the brand's starters.

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

The starters belong to a new chat: not once the user has said something, nor on a conversation that continues from before.

Returns — Boolean — true while none of them is the user's and none is restored. Example value: false.

Errors — none.

val showStarters = ChatRows.offersStarters(GraineInApp.get().chat.messages)

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. An open's size lasts until the chat closes. On a phone, large is a sheet over most of the screen (the app dimmed behind it, a handle to drag it closed, Back too) and full the whole screen; on a tablet both open a panel, 420 dp wide, in the corner. A word from a newer design that the SDK does not know is passed over.

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

GraineChatSize.from

Call it to read a size word — from your own settings, for example — into a GraineChatSize.

@JvmStatic
companion · fun from(wire: Any?): GraineChatSize?

Case and surrounding spaces do not matter.

Returns — GraineChatSize? — null for anything else (absent, or a word newer than this SDK). Example value: GraineChatSize.LARGE.

Errors — none.

val size = GraineChatSize.from("large")

GraineChatView

Use it to show the chat as a whole screen inside your own layout.

class GraineChatView @JvmOverloads constructor(context: Context, attrs: AttributeSet? = null) : FrameLayout(context, attrs), GraineListener

The text conversation, drawn by the SDK in the brand's design — header, bubbles, composer, suggestions — with the agent's components right under the line that asked for them, and the booked calls first in the conversation. The conversation opens when the view appears and closes shortly after the view leaves the screen. Built from standard Android views, so it needs neither AndroidX nor Compose.

What to expect — Main thread. Add it to any layout, or open GraineChatActivity to show it as a screen of its own.

setContentView(GraineChatView(this).apply { onClose = { finish() } })
// Another of the app's agents:
GraineChatView(this).apply { source = GraineInApp.get("support").chat }

GraineChatActivity

Use it to open the chat on a screen of its own, with no layout of yours.

class GraineChatActivity : Activity()

GraineChatView full screen, in the brand's design, above the keyboard, with the system bars in the chat's colours; closed by its close button or Back. Declared in the SDK's manifest; nothing for your app to add.

What to expect — Open it with GraineChatActivity.open; it shows the agent you name, or the default.

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

GraineChatActivity.open

Call it from any “Chat with us” entry point to open the chat screen.

@JvmStatic @JvmOverloads
companion · fun open(context: Context, agent: String = GraineInApp.DEFAULT)

From anything with a context; a non-activity context starts it in a new task. A name no agent was made under opens the default agent's chat, with a warning in the log.

Returns — nothing.

Errors — none.

GraineChatActivity.open(this, agent = "support")

The voice bar

The agent talking inside your app, beside the screen it talks about. Attach the voice engine once with voice.attach(activity) — it loads idle in the background, so a tap costs only the call — and place a GraineAgentBarView (or a GraineLauncherView) in your layout: the bar places and ends calls by itself, shows captions, the connection's state and the chat beside the call, all in the agent's design. GraineVoice's state and the listener's events are for an app that draws its own controls. The bar says the network's state out loud — “Weak connection”, “No connection”, “Reconnecting…” — and, while a call comes up or the agent works out its answer, shows the dashboard's loader in the brand's words.

GraineVoice

Use it to place and end the voice bar's call from controls of your own, and to read its state.

class GraineVoice internal constructor(…)

GraineInApp.get().voice. Attach the engine once with attach(activity); the bar starts and ends calls itself.

What to expect — Main thread. The state below changes as the call moves, and each change reaches GraineListener. One conversation at a time: starting a call closes an open chat, and a native call holds the line.

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

GraineVoice.attach

Call it once, from your first activity, to load the voice engine so a call can start at once.

fun attach(activity: Activity)

The engine loads idle — nothing is dialled and the microphone is not used — so a start() later costs only the call. Once is enough: from then on the engine follows the user, moving to whichever of your activities is in front, and a call in progress carries on across them. Calling it again from another activity is the same move, never a reload.

Returns — nothing.

Errors — none.

GraineInApp.get().voice.attach(this)

GraineVoice.detach

Call it only when your app no longer wants the voice bar at all — a sign-out that removes the agent, for example.

fun detach()

Ends a call in progress and unloads the engine. attach loads it again.

Parameters — none.

Returns — nothing.

Errors — none.

GraineInApp.get().voice.detach()

GraineVoice.start

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

fun start()

Asks for the microphone first if the app does not hold it — forward your activity's onRequestPermissionsResult to onRequestPermissionsResult so the call goes ahead when it is granted. Before the engine is ready the start is held and placed when it is. It ends the chat (its lines stay) and another agent's call.

Parameters — none.

Returns — nothing.

Errors — none as an exception: before attach it reports “GraineVoice.attach(activity) must be called before start().” to onError; while a native call is live, “A call is already in progress.”. A refused microphone is onMicDenied("NotAllowedError").

GraineInApp.get().voice.start()

GraineVoice.end

Call it from your own hang-up control.

fun end()

Hangs up. If the call does not confirm it within GraineConfig.Timing.endWatchdogMs (4 s), the SDK ends it itself.

Parameters — none.

Returns — nothing.

Errors — none.

GraineInApp.get().voice.end()

GraineVoice.setMuted

Call it from your own mute control.

fun setMuted(value: Boolean)

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

Returns — nothing.

Errors — none.

GraineInApp.get().voice.setMuted(true)

GraineVoice.setCaptionsOn

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

fun setCaptionsOn(on: Boolean)

The voice bar shows the line being said only while the switch is on. The call goes on either way, and captions keeps what was said. On by default; your choice holds for the rest of the launch.

Returns — nothing.

Errors — none.

val voice = GraineInApp.get().voice
voice.setCaptionsOn(!voice.captionsOn)

GraineVoice.clearCaptions

Call it to forget what has been said on the call — from a “Clear” control on a transcript of yours, say.

fun clearCaptions()

Empties captions without ending the call; the voice bar's caption clears too. A new call starts empty by itself.

Parameters — none.

Returns — nothing.

Errors — none.

GraineInApp.get().voice.clearCaptions()

GraineVoice.retry

Call it from a “Try again” control when the engine could not load (connectivity is FAILED).

fun retry()

Reloads the engine and starts the reload schedule over (GraineConfig.Timing.retryDelaysMs).

Parameters — none.

Returns — nothing.

Errors — none.

GraineInApp.get().voice.retry()

GraineVoice.onRequestPermissionsResult

Call it from your activity's onRequestPermissionsResult, so a call waiting for the microphone can go ahead.

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

When the user refuses, the waiting call is dropped and onMicDenied("NotAllowedError") fires.

Returns — Boolean — true when the request was the SDK's (MIC_REQUEST) and is handled; pass anything else on. Example value: true.

Errors — none.

override fun onRequestPermissionsResult(requestCode: Int, permissions: Array<out String>, grantResults: IntArray) {
    if (!GraineInApp.get().voice.onRequestPermissionsResult(requestCode, grantResults))
        super.onRequestPermissionsResult(requestCode, permissions, grantResults)
}

GraineVoice.viewOpened

Call it when a voice interface of your own — anything but a GraineAgentBarView, which says so itself — comes on screen.

fun viewOpened()

While one of your views is open, the user is waiting on the voice: an engine still loading behind it is their wait, reported as slowConnect (“Still connecting…”) past Timing.slowConnectMs. Call it in pairs with viewClosed; several views of yours count as one while any is open. Main thread.

Parameters — none.

Returns — nothing.

Errors — none.

override fun onStart() { super.onStart(); GraineInApp.get().voice.viewOpened() }
override fun onStop() { super.onStop(); GraineInApp.get().voice.viewClosed() }

GraineVoice.viewClosed

Call it when the voice interface of yours from viewOpened leaves the screen.

fun viewClosed()

When it was the last one, and no GraineAgentBarView is on screen either, a failed connect and its stage are no longer news: callFailed, connectStage and slowConnect clear. A close with nothing open is ignored.

Parameters — none.

Returns — nothing.

Errors — none.

GraineInApp.get().voice.viewClosed()

GraineCaption

Read it for one line of what was said on the voice bar's call — to draw a transcript of your own.

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

GraineVoice.captions, oldest first.

What to expect — A live line is replaced as its words arrive, not appended; the last 12 lines are kept, and a new call starts empty. The captions switch (captionsOn) hides the bar's caption, never this list.

GraineAgentBarView

Place it in your layout to give the user the voice bar.

class GraineAgentBarView @JvmOverloads constructor(context: Context, attrs: AttributeSet? = null) : LinearLayout(context, attrs), GraineListener

What the user sees during a call, drawn exactly as the dashboard's Garage previews it: the avatar (the design's glyph, the brand's logo whole on its plate, or the first letter), the heading and a status line with a meter that moves at the design's pace, the microphone, and the end button. Above it, the line being said on a card of its own (while voice.captionsOn), and above that the components the agent draws (widgetView), so a card the agent shows moves with the bar. Where the dashboard offers chat, the bar switches between the call and the chat. Plain platform widgets: no AndroidX, Compose or Material.

What to expect — The design is the source for everything; the properties below override one thing each. From a server without designs, the bar is Graine Classic in the dashboard's accent and corners.

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

GraineAgentBarView.resetPlacement

Call it to put the bar back where you placed it — from a “Reset position” setting, for example.

fun resetPlacement()

Moves the bar back to its anchor and tells onPlacementChange (with 0).

Parameters — none.

Returns — nothing.

Errors — none.

bar.resetPlacement()

GraineLauncherView

Place it in your layout to give the user a floating button that starts the call — or opens what you choose.

class GraineLauncherView @JvmOverloads constructor(context: Context, attrs: AttributeSet? = null) : View(context, attrs), GraineListener

The floating button, drawn the way the brand designed it: 56 dp, in the accent, with the design's glyph, the brand's logo (whole, on its plate) or the first letter of the name, in the design's shape — circle, squircle, rounded or plain square, or a pill as wide as its label — with the design's depth. A tap starts the call, and ends one that is live; setOnClickListener replaces that. Place it yourself, like any view (bottom-end over the content is usual); it measures its own size, shadow room included.

What to expect — Main thread. Without a design (an older server) it is a circle in the dashboard's accent with its logo.

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

GraineLauncherView.setOnClickListener

Call it to make the launcher open something of yours — the voice bar, the chat — instead of starting the call.

override fun setOnClickListener(l: OnClickListener?)

Replaces the default tap (start or end the call) with your own listener.

Returns — nothing.

Errors — none.

launcher.setOnClickListener { bar.visibility = View.VISIBLE }

GraineLoaderView

Use it to draw the brand's loader in a waiting state of your own.

class GraineLoaderView @JvmOverloads constructor(context: Context, attrs: AttributeSet? = null) : View(context, attrs)

How waiting looks, from the dashboard's Appearance → loader: dots, pulse, ring, bars, or the brand's logo breathing (“mark”, which is the pulse when no logo is uploaded), at the chosen size and speed. Drawn on a canvas, with no resources or animation library. The bar and the components use it themselves.

What to expect — Call configure with a look from Loaders.resolve.

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

GraineLoaderView.configure

Call it to set what the loader draws — the kind, colour, size and speed.

fun configure(look: LoaderLook, color: Int, track: Int, sizeDp: Int? = null, logoUrl: String? = null)

Returns — nothing.

Errors — none.

val look = Loaders.resolve(GraineInApp.get().session?.appearance?.opt("loader"))
val loaderView = GraineLoaderView(this)
loaderView.configure(look, Color.parseColor(look.color ?: "#318CE7"), 0x332C2E33, sizeDp = 16)

LoaderLook

Read it to draw the dashboard's loader yourself, with every value worked out.

data class LoaderLook(val kind: String, val color: String?, val px: Int, val periodMs: Long, val text: LoaderText, val skeleton: Boolean)

From Loaders.resolve.

LoaderStyle

Read it for the loader exactly as chosen in the dashboard, before defaults are applied.

data class LoaderStyle(val kind: String? = null, val color: String? = null, val size: String? = null, val speed: String? = null, val text: LoaderText? = null, val skeleton: Boolean? = null)

From Loaders.normalise; only known words survive. null means “use the default”.

LoaderText

Read it for the words shown in each moment the user waits.

data class LoaderText(val connecting: String? = null, val reconnecting: String? = null, val thinking: String? = null, val component: String? = null)

What to expect — null means the default: “Connecting…”, “Reconnecting…”, “Thinking…”, “Loading…”. A word the brand chose is at most 40 characters, often not English — show it as it is.

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

LoaderText.forMoment

Call it to get the words for one waiting moment by name.

fun forMoment(moment: String): String?

Returns — String? — the words for that moment, or null (a moment with no words of its own, or an unknown name). Example value: "Thinking…".

Errors — none.

val look = Loaders.resolve(GraineInApp.get().session?.appearance?.opt("loader"))
val words = look.text.forMoment("thinking")

Loaders

Use it to turn the dashboard's loader setting into something you can draw.

object Loaders

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

Loaders.normalise

Call it to read the dashboard's loader setting, keeping only the words the SDK knows.

fun normalise(raw: Any?): LoaderStyle

Returns — LoaderStyle (LoaderStyle) — anything unknown or malformed is dropped. Example value: LoaderStyle(kind=ring, color=accent, size=null, speed=quick, text=null, skeleton=null).

Errors — none.

val style = Loaders.normalise(GraineInApp.get().session?.appearance?.opt("loader"))

Loaders.resolve

Call it to get the loader to draw, with every default applied.

fun resolve(raw: Any?): LoaderLook
fun resolve(s: LoaderStyle): LoaderLook

Takes the raw setting (anything — junk resolves to the default dots) or a LoaderStyle already read.

Returns — LoaderLook (LoaderLook). Example value: LoaderLook(kind=dots, color=null, px=20, periodMs=1100, text=LoaderText(…), skeleton=false).

Errors — none.

val look = Loaders.resolve(GraineInApp.get().session?.appearance?.opt("loader"))

Connectivity

Read it to know whether the voice engine has loaded.

enum class Connectivity { LOADING, READY, RETRYING, FAILED }

What to expect — LOADING → READY; a stalled load goes RETRYING (the SDK reloads it on its own schedule) and, after the last reload, FAILED.

ConnectionQuality

Read it to tell the user when the network is the problem.

enum class ConnectionQuality { EXCELLENT, GOOD, POOR, LOST, UNKNOWN }

What to expect — Reported as it changes (onQuality). The same thresholds on every Graine SDK and the website.

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

ConnectionQuality.classify

Call it to rate a connection you measured yourself the way the SDK does.

companion · fun classify(rttMs: Double?, jitterMs: Double?, loss: Double?): ConnectionQuality

The worst of the three decides: any one alone can ruin a call.

Returns — ConnectionQuality — UNKNOWN when all three are null. Example value: ConnectionQuality.GOOD.

Errors — none.

val quality = ConnectionQuality.classify(180.0, 12.0, 0.01)   // GOOD

ConnectStage

Read it to say where a call being placed is, so the user waits instead of giving up.

enum class ConnectStage(val wire: String)

What to expect — Only during a connect; null outside one. A stage newer than this SDK is ignored. Nothing could carry the call at all is not a stage: it is GraineVoice.callFailed.

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

ConnectStage.from

Call it to read a stage word into a ConnectStage.

@JvmStatic
companion · fun from(s: String?): ConnectStage?

Returns — ConnectStage? — null for anything else (failed, or a stage newer than this SDK). Example value: ConnectStage.DIALLING.

Errors — none.

val stage = ConnectStage.from("retrying")

CallPhase

Read it for what the voice bar's call is doing, in one word — to draw your own status line.

enum class CallPhase { IDLE, CONNECTING, RECONNECTING, THINKING, SPEAKING, LISTENING }

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

CallPhase.of

Call it to work out the phase from state you track yourself, the way the bar does.

@JvmStatic
companion · fun of(reconnecting: Boolean, connectivity: Connectivity, connecting: Boolean, ready: Boolean, connected: Boolean, agentSpeaking: Boolean, awaitingAgent: Boolean): CallPhase

First match wins: reconnecting (or the engine retrying or failed) → RECONNECTING; connecting or not ready → CONNECTING; not connected → IDLE; the agent speaking → SPEAKING; waiting for the agent → THINKING; else LISTENING.

Returns — CallPhase. Example value: CallPhase.LISTENING.

Errors — none.

val phase = CallPhase.of(false, Connectivity.READY, false, true, true, false, false)   // LISTENING

Transport

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

enum class Transport(val wire: String)

What to expect — Leave transport null and the dashboard's Call audio setting decides. onTransport says which path carries a call, and why it is not the one asked for.

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

Transport.from

Call it to read a transport word into a Transport.

companion · fun from(s: String?): Transport

Returns — Transport — WEBRTC for "rtc", WEBSOCKET for anything else. Example value: Transport.WEBRTC.

Errors — none.

val transport = Transport.from("rtc")

Several agents in one app

A support agent in Help, a sales agent on Plans — each with its own publishable key, made under its own name with GraineInApp.init(application, config, name = "sales") and reached with GraineInApp.get("sales"). Each agent has its own settings, chat, voice bar, actions, and scheduling and memory requests, sent with its own key. The install ID, who the user is (identify on one is for all; identify(null) signs out of all), the memory choice, the screen and the call engine are the app's. One conversation at a time across every agent. Views take the agent: GraineAgentBarView.graine, GraineChatView.source = GraineInApp.get("sales").chat, GraineChatActivity.open(context, agent), GraineWidgetView.graine, GraineLauncherView.graine; calls.startCall(activity, reason, variables, agent) calls a named one, and a ring Graine sends rings with the agent it is for. An app with one agent names none.

GraineInApp.init(this, GraineConfig("https://www.graine.ai", "pk_live_support…"))                 // the default agent
GraineInApp.init(this, GraineConfig("https://www.graine.ai", "pk_live_sales…"), name = "sales")
GraineInApp.get("sales").chat.open()

GraineInApp.get

Call it anywhere to reach an agent you made with init.

@JvmStatic @JvmOverloads
companion · fun get(name: String = DEFAULT): GraineInApp

Returns — GraineInApp — the agent.

Errors — IllegalStateException when there is none: “GraineInApp.init(application, config) has not been called” for the default agent, or “No agent is named "sales": GraineInApp.init(application, config, name = "sales") first”. Use find when it may not exist.

val sales = GraineInApp.get("sales")

GraineInApp.find

Call it to reach an agent that may not have been made.

@JvmStatic
companion · fun find(name: String): GraineInApp?

Returns — GraineInApp? — the agent, or null when init made none under that name. Example value: null.

Errors — none.

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

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: reported on any agent, every agent has it and sends it on while it has a live conversation. Values are masked on the device before anything leaves it — card and account numbers, government ID numbers, phone numbers and email addresses, plus your own rules — so report real values. The agent's components (product lists, plan comparisons, choices, time slots, information cards) are drawn by GraineWidgetView, which the voice bar and the chat already hold; a view of your own answers them with answerWidget.

GraineInApp.setScreen

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

fun setScreen(next: GraineScreen?)

An unchanged screen is not resent. The first change goes at once and later ones at most every 400 ms, the latest always last — a screen updated on every keystroke is neither flooded nor stalled. After a pause, the agent names the field that is INVALID or EMPTY instead of asking “need a hand?”. null clears it.

Returns — nothing.

Errors — none.

GraineInApp.get().setScreen(GraineScreen(
    screen = "checkout_address", title = "Delivery address",
    journey = GraineScreen.Journey("Checkout", step = 2, of = 3, next = "Payment"),
    fields = listOf(GraineField(name = "postal_code", label = "Postal code", value = "400001",
        status = GraineField.Status.INVALID, error = "We don't deliver there yet")),
))

GraineInApp.updateField

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

fun updateField(field: GraineField)

The field replaces the one with the same name on the current screen — or is added, if the screen has none — and the agent gets the update like any other screen change. Before any screen has been reported it does nothing.

Returns — nothing.

Errors — none.

GraineInApp.get().updateField(GraineField("postal_code", value = "400001", status = GraineField.Status.FILLED))

GraineInApp.removeField

Call it when a field leaves the screen.

fun removeField(name: String)

Nothing happens when it was never reported.

Returns — nothing.

Errors — none.

GraineInApp.get().removeField("coupon")

GraineInApp.clearScreen

Call it when the user leaves a screen — in the screen's onStop or onDestroy.

@JvmOverloads
fun clearScreen(screenId: String? = null)

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

Returns — nothing.

Errors — none.

override fun onStop() { super.onStop(); GraineInApp.get().clearScreen("checkout_address") }

GraineInApp.setVariables

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

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

Merged over what is there, not replaced: null under a key removes it, null for the whole map clears them all. Numbers and booleans are written out as text; nested maps and lists are dropped. Masked on the device. Reaches the next call, and a live voice-bar call picks it up. A conversation carries up to 12 variables, about 1 KB — past that, the biggest are left off first, who_called and call_reason last.

Returns — nothing.

Errors — none.

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

GraineInApp.currentVariables

Call it to check, while you build, exactly which prompt variables the agent will receive.

fun currentVariables(): Map<String, String>

In order of precedence, each later one winning: the dashboard's defaults, GraineConfig.variables, setVariables, then the signed-in user's traits (without the trait that identifies them).

Parameters — none.

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

Errors — none.

Log.d("Graine", GraineInApp.get().currentVariables().toString())

GraineInApp.track

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

@JvmOverloads
fun track(name: String, data: Map<String, Any?> = emptyMap(), coalesce: Boolean = false)

It rides along with the screen, among the user's recent events (the last ten are kept), for every agent. Masked on the device.

Returns — nothing.

Errors — none.

GraineInApp.get().track("coupon_applied", mapOf("code_length" to 8))

GraineInApp.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 reported — a tap means something only against the screen it was on. Labelled controls are noticed by themselves (GraineConfig.captureTaps).

Returns — nothing.

Errors — none.

GraineInApp.get().tap("Apply coupon")

GraineInApp.reportEvent

Call it when something happens that the agent may want to speak up about — a payment failing, a form being rejected.

@JvmOverloads
fun reportEvent(name: String, detail: String? = null, data: Map<String, Any?> = emptyMap())

It reaches whichever conversation is live — the voice-bar call or the chat — with the current screen sent first, so the agent reads the event against the right one. When no conversation is live there is no one to tell, and the event is discarded.

Returns — nothing.

Errors — none.

GraineInApp.get().reportEvent("payment_failed", "The card was declined.")

GraineVoice.reportEvent

Call it to tell the voice-bar call about something the agent may want to speak up about.

@JvmOverloads
fun reportEvent(name: String, detail: String? = null, data: Map<String, Any?> = emptyMap())

Only during a voice-bar call; prefer GraineInApp.reportEvent, which reaches whichever conversation is live.

Returns — nothing.

Errors — none.

GraineInApp.get().voice.reportEvent("upload_failed", "The file was too large.")

GraineInApp.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 — none.

GraineInApp.get().noteInteraction()