Types

The same structures, with the same fields, on every platform. Each section gives the fields, how each platform declares the type, a JSON example of a real value, and what to expect: when it arrives or changes, what can be empty, and what a newer value looks like to an older SDK.

Times are moments, never local wall-clock times. In the JSON they are ISO-8601 strings in UTC; in code they are the platform's own type — Date (TypeScript, Swift), java.util.Date (Android), DateTime (Dart) or Instant (Kotlin Multiplatform). Show them in the device's time zone. Flutter hands times that came from Graine (bookings, memories, earlier chat messages) as UTC DateTimes: .toLocal() them for display. The few fields that are not a Date — React Native's chat and call times, Android's call timer — say so below.

Enums are spelled in each language's own style: a wire word such as no_device is "noDevice" in TypeScript, .noDevice in Swift, NO_DEVICE on Android, noDevice in Dart and NoDevice in Kotlin Multiplatform.

Chat

GraineChatTurn

One message in a chat's transcript, oldest first: the customer's, or one reply of the agent's.

// useGraineAgent().messages
interface Turn {
  role: "agent" | "customer"; text: string;
  live?: boolean;        // the agent is still streaming it
  pending?: boolean;     // delivery "sending": waiting for a connection
  id?: string; proactive?: boolean;
  at?: number;           // when it was said, in milliseconds since 1970 (UTC)
  restored?: true;       // an earlier message, put back when the conversation continued
  channel?: "voice";     // said on a call; absent for the chat
}

What to expect

• Earlier messages arrive once, first. For an identified customer with memory on, a chat that opens with this agent within 7 days of their last message starts with up to 50 earlier messages, oldest first, before the agent says anything — and there is no second welcome. They are delivered, never live, never proactive, with the time each was said, restored set, and Graine's ids. Anything of the customer's still waiting to go follows them. A reconnect brings them again; they replace the earlier copies, so nothing shows twice. For an anonymous customer, a customer who turned memory off, or an agent without memory, nothing is restored.
• A voice call is one row. A run of voice turns on one day is something said on a call: the SDK's chat window draws it as one Voice call · 6:40 pm row, never as bubbles, and so should yours. A date line (Today, Yesterday, or the date) goes wherever the day changes. Every SDK lays this out for you: GraineChatRows.
• live turns change. An agent's turn grows as its words arrive and settles (live false) when the turn ends, when the customer speaks, or when the connection goes. Redraw on every change; the next reply is a new turn.
• failed waits for a tap. The SDK's chat window marks a failed message as not sent; a tap — or retry() (iOS, Kotlin Multiplatform; Android connect(), Flutter open()), the next message, or opening the chat again — sends it.
• The transcript clears when forgetMemory() succeeds, on newConversation(), on identify(null), and when a different customer is identified on the device. A device keeps at most the last 200 turns on screen.

{
  "id": "t7",
  "role": "agent",
  "text": "Your order ships tomorrow. Want me to book a delivery slot?",
  "at": "2026-10-13T16:41:09Z",
  "delivery": "sent",
  "proactive": false,
  "live": false,
  "component": null,
  "restored": false,
  "channel": "chat"
}

An earlier message, put back when the conversation continued, and part of a call:

{ "id": "6a1f0c2e9b7d", "role": "agent", "text": "Done — I've moved your delivery to Friday.", "at": "2026-10-12T13:10:44Z", "delivery": "sent", "restored": true, "channel": "voice" }

GraineChatRows

Every SDK lays a conversation out the way its chat window draws it, for an app that draws its own chat (the SDK's own window already does): React Native chatTurnRows(messages) (chatRows(items, read) for items of your own), iOS GraineChatRows.build(turns) (GraineChatRow: .day(GraineChatDayLine), .voice(GraineChatCallLine), .turn), Android ChatRows.build(messages) (ChatRows.Row: Day, Voice, Turn), Flutter ChatRows.build(turns, now:) (ChatDayRow, ChatVoiceRow, ChatTurnRow), and Kotlin Multiplatform — from Graine.chat.turns (the SDK's GraineChat() already does): a bubble per chat turn, one Voice call row for a run of voice turns on one day, and a day separator before the first row when it is not from today and wherever the device's day changes.

object GraineChatRows {
    fun build(turns: List<GraineChatTurn>, now: Instant = Clock.System.now(),
              zone: TimeZone = TimeZone.currentSystemDefault()): List<GraineChatRow>
    fun dayLabel(row: GraineChatRow.Day, now: Instant = Clock.System.now(), zone: TimeZone = …): String   // "Today", "Yesterday", "Sat 10 Oct"
    fun callLabel(clock: String): String                    // "Voice call · 6:05 PM"
    fun offersStarters(turns: List<GraineChatTurn>): Boolean        // nothing said yet, and nothing restored
    fun offersNewConversation(turns: List<GraineChatTurn>): Boolean // restored turns on screen
}
 
sealed class GraineChatRow {
    abstract val key: String   // stable while the conversation grows
    data class Day(val day: GraineChatDay /* TODAY, YESTERDAY, DATE */, val date: LocalDate, val at: Instant)
    data class VoiceCall(val id: String, val at: Instant, val first: Int, val last: Int)   // turns first..last, never their words
    data class Turn(val turn: GraineChatTurn, val index: Int)
}

What to expect: days are the device's (or zone's); a date from another year carries the year (Wed 31 Dec 2025). A conversation all from today has no separator and lays out exactly as before. Rebuild the rows whenever turns changes, and key your list on key.

The chat's state

Whether the chat is connected, and what to say while it is not.

GraineChatStatus (iOS, Kotlin Multiplatform):

What to expect: a dropped chat reconnects by itself while the customer is in it. iOS, Android, Flutter and Kotlin Multiplatform try six times — 1, 2, 4, 8, 15 and 15 seconds apart — then stop, offline (failed), until the customer sends a message or your app calls retry() or opens the chat again. React Native waits 1, 2, 4, 8, 15, then 30 seconds between tries, for as long as the customer is in the chat; it stops — failed — only when its first connect failed or Graine ended or refused the conversation. None reconnects a chat closed on purpose, one Graine refused, or one a call replaced. Say Reconnecting…, not Offline, while it tries. The typing indicator runs from the customer's message to the agent's first words, a component, the chat closing, or a while with no answer (12 seconds; 30 on iOS).

GraineChatSize

How big the chat window opens: compact (the window above the bar), large (a sheet over most of a phone, a panel on a tablet or a computer) or full (the whole screen). What each looks like: Chat → Window size.

What to expect

• One open's size wins, then the app's, then the design's (the Garage's Chat window → Window size), else compact. Leave the app's size unset to follow the dashboard. An open's size lasts until the chat closes; moving to the call and back keeps it.
• A word an SDK does not know — from a newer dashboard, or a typo on a website — is passed over, never an error: the next choice applies. Android's GraineChatSize.from(wire) returns null for one.
• Flutter with no bar on screen: GraineChat.open presents the chat on the navigator — large as a sheet (a panel on a tablet), full as a screen of its own, and compact, which belongs to the bar, as large. With a bar on screen, the bar moves to the chat at that size.
• GraineChatView, GraineChatViewController, GraineChatActivity, GraineChat and React Native's GraineChatScreen fill whatever space your app gives them: the size is for the window the bar or the widget opens.

newConversation

Starts the chat over with this agent: a fresh thread.

What to expect

• Success: the chat's connection ends, Graine lets go of the conversation it kept for this agent and the identified customer, the transcript clears (with anything still waiting to go), and — when the customer was in the chat — a fresh chat opens, which greets as a first chat does.
• Memory stays. What the agent remembers about the customer is untouched, and so are other agents' conversations.
• Anonymous: nothing was kept, so nothing is asked of Graine — the transcript clears, and it cannot fail.
• Failure: it fails as forgetMemory() does — device_limit, unavailable, network, rate_limited — and changes nothing: the chat is as it was, and connected again if it was open.

Identity and memory

What identify sends and keeps

identify(traits, memory) names the signed-in customer — Identity and memory → identify.

GraineMemory

One thing the agent remembers about the signed-in customer, already redacted.

Declared as GraineMemory everywhere — an Identifiable struct in Swift, a data class on Android and in Kotlin Multiplatform, a class in Dart, an interface in TypeScript, a plain object on the website.

What to expect: memories() returns at most 100, newest first. It answers only for an identified customer (identity_required otherwise) on one of their devices (device_limit otherwise). A memory without an id or text is skipped, never handed over half-made.

{
  "id": "mem_4f9c21",
  "text": "Prefers a call after 6 pm on weekdays.",
  "createdAt": "2026-10-02T13:05:11Z",
  "updatedAt": null
}

forgetMemory's result

An integer: how many memories were deleted — Promise<number> (React Native, website), Int (iOS async throws, Kotlin Multiplatform suspend), Future<int> (Flutter), and the callback's Int on Android.

What to expect: 0 is a success too — there was nothing to forget. Only when it succeeds, the conversation kept to continue is forgotten with the memories and the chat on screen clears. A failure — unavailable (503), device_limit, network, identity_required — deletes nothing and leaves the chat on screen as it is.

3

Session settings

What the SDK reads from the agent's settings once per launch.

What to expect: null (or the defaults) until the settings load — a moment after start-up, then kept for the launch. An older server sends none of the newer values: the identity field is then user_id, two devices, and nobody may book. A change in the dashboard reaches an app the next time it starts.

{
  "identity": { "field": "user_id", "devicesPerUser": 2 },
  "memoryEnabled": true,
  "calls": { "hosted": true, "platforms": ["ios", "android"], "ringTimeoutSeconds": 45, "callName": "Asha from Acme" },
  "schedulingRules": { "usersCanBook": true, "minLeadMinutes": 5, "maxDaysAhead": 14, "maxPendingPerUser": 3 }
}

IdentityChannel

React Native's identityChannel(): what the SDK will send with the next conversation.

{ "value": "u_8812", "installId": "3f6a0c1e-9b2d-4c7a-8e51-2d9f0a7b6c43", "memory": true, "timezone": "Asia/Kolkata" }

Scheduling

GraineScheduledCall

A call booked for later — returned by scheduleCall and scheduledCalls, and shown in the chat's upcoming calls.

interface GraineScheduledCall {
  id: string; at: Date | null; status: GraineCallStatus; source: GraineCallSource | null;
  reason: string | null; isUpcoming: boolean; canCancel: boolean;
}

What to expect: a booking is for the identified customer — or, with nobody identified, for this install — and rings their newest app device, in their time zone. Its reason is kept by Graine for the agent and never travels in the push that rings it. scheduledCalls() lists those still to come, soonest first; read the status again to learn what became of one.

{
  "id": "c3a8f1d2-5b7e-4a19-9f02-6d4e8b1a7c35",
  "at": "2026-10-14T12:30:00Z",
  "status": "scheduled",
  "source": "app",
  "reason": "Talk through my order",
  "isUpcoming": true,
  "canCancel": true
}

GraineCallStatus

Where a booked call is. The dashboard and your webhooks use the wire words; the SDKs use the enum.

scheduled → ringing → answered → completed
    │           ├──→ declined
    │           ├──→ missed      (rings once more after your re-ring delay, if set)
    │           └──→ failed
    ├──→ cancelled
    ├──→ expired
    └──→ no_device

Swift and Kotlin types also give wire (the word) and a constructor from it: GraineCallStatus(wire:), GraineCallStatus.from(wire). Flutter gives statusWire on the booking. A booking with no status at all reads as scheduled.

GraineCallSource

Who booked a call.

source is null when Graine does not say. Swift, Android and Kotlin Multiplatform also accept app as the wire word.

GraineSchedulingRules

What the agent allows, read from its settings when the SDK loads them — for a booking screen that offers only times that will be accepted.

interface GraineSchedulingRules {
  usersCanBook: boolean; minLeadMinutes: number; maxDaysAhead: number; maxPendingPerUser: number;
  ringTimeoutSeconds: number; callName: string | null; hostedRinging: boolean; platforms: ("ios" | "android")[];
  earliest(now?: Date): Date; latest(now?: Date): Date;
}

What to expect: the defaults — and no booking — until the agent's settings load. scheduleCall checks a time against these rules on the device, before any request: scheduling_off when usersCanBook is false, too_soon before earliest(now), too_far after latest(now) (React Native and the website allow 30 seconds' grace on too_soon, for the moment between computing earliest and sending). The calling hours and the calls already waiting are Graine's to judge: outside_window and too_many_pending come back from it.

{
  "usersCanBook": true,
  "minLeadMinutes": 5,
  "maxDaysAhead": 14,
  "maxPendingPerUser": 3,
  "ringTimeoutSeconds": 45,
  "callName": "Asha from Acme",
  "hostedRinging": true,
  "platforms": ["ios", "android"]
}

What the scheduling calls return

Each platform's way: a promise (React Native, website), async throws (iOS), a GraineCallback on the main thread (Android), a Future (Flutter), a suspend function (Kotlin Multiplatform). Parameters and errors: Scheduling.

Calls

GraineCallOutcome

What became of a native call on this device — sent to your app as it happens, and, for a call Graine rang, reported to Graine by the SDK itself.

type GraineCallOutcome = (
  | { callId: string; outcome: "ringing" } | { callId: string; outcome: "answered" }
  | { callId: string; outcome: "declined" } | { callId: string; outcome: "missed" }
  | { callId: string; outcome: "ended"; reason: "local" | "remote" | "failed" }
  | { callId: string; outcome: "failed"; error: string }
) & { durationSeconds?: number | null; hosted?: boolean; agent?: string | null };

What to expect

• Every outcome carries the call's id; send it to your server with it. An answered call is followed by ended or failed. A call that connected and dropped ends ended with failed — calls do not reconnect.
• What each platform reports. Kotlin Multiplatform reports every field above but busy (its reason says busy), ringing included; on Android its agent is null for a ring refused because another call was live. iOS reports the five outcomes, with endReason and error; read GraineCalls.agent and GraineCalls.hosted for the call. Android has no ringing (a ring is onIncomingCall) and no agent (calls.callAgent). React Native and Flutter type every field; their 0.7.0 engines send callId, outcome, reason (or error) and agent, and leave durationSeconds and hosted empty and ringing unsent.
• Not replayed. Listen from app start. React Native and Flutter hold the last 20 outcomes until a listener arrives; the native SDKs report to the listeners you have.

{
  "callId": "c3a8f1d2-5b7e-4a19-9f02-6d4e8b1a7c35",
  "outcome": "ended",
  "reason": "local",
  "durationSeconds": 212,
  "hosted": true,
  "agent": "support"
}

GraineIncomingCall

A call ringing on this device.

{ "callId": "c3a8f1d2-5b7e-4a19-9f02-6d4e8b1a7c35", "callerName": "Asha from Acme", "reason": null, "hosted": true, "agent": "support" }

GraineMissedCall

A ring nobody answered, kept so a call screen can say Missed call and offer Call back — iOS (GraineCalls.missedCall) and Kotlin Multiplatform (GraineCallInfo.missedCall). Android shows a missed-call notification with Call back instead; React Native and Flutter leave it to the native engine's call screen and notification.

What to expect: kept until the customer calls back, dismissMissedCall() is called, or another call rings or is placed. On iOS showsCallScreen leads with it for ten minutes. A ring refused because another call was live is not kept.

{ "callId": "c3a8f1d2-5b7e-4a19-9f02-6d4e8b1a7c35", "callerName": "Asha from Acme", "reason": null, "hosted": true, "at": "2026-10-14T12:31:00Z", "agent": "support" }

The call, to draw

What a call screen of your own reads.

What to expect: one call at a time. ended is reported once, then idle (on iOS after a second; elsewhere it can pass at once) — take how a call ended from its outcome, not from the state. A call being placed has no stages here: connecting until it connects or fails. The stages a bar's call goes through are in Connection values.

{
  "state": "active",
  "callId": "c3a8f1d2-5b7e-4a19-9f02-6d4e8b1a7c35",
  "direction": "incoming",
  "reason": null,
  "callerName": "Asha from Acme",
  "muted": false,
  "speakerOn": false,
  "agentSpeaking": true,
  "caption": { "role": "agent", "text": "Thanks for picking up — is now a good time?", "live": true },
  "connectedAt": "2026-10-14T12:30:04Z",
  "error": null,
  "agent": "support",
  "transport": "webrtc",
  "transportFallbackReason": null
}

GraineCallTransport

What carries a native call's audio — in both directions, a call the customer places and a call Graine rang. Chosen in the calls configuration (callTransport), read back on the call (transport). WebRTC needs the SDK's WebRTC module in the app (In-app calling → WebRTC).

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 — the customer sees Connecting… a moment longer — and transport says websocket.

Why a call is on the WebSocket

transportFallbackReason, set only for a call that wanted WebRTC and runs on the WebSocket. Final once the call is active.

GraineCaption

Kept as captions on every platform's voice (Android: GraineCaption, new in 0.9.0); the captions switch (captionsOn) hides the bar's caption, never the list.

startCall's result

The call's id — a string every outcome carries — or null, when nothing was placed:

The push payload

What a messaging service hands to handlePush — the SDK's own, or your app's (Android, React Native, Flutter, Kotlin Multiplatform) — or iOS receives as a VoIP push. Every value is a string.

A ring Graine sends carries only type, call_id, caller_name, hosted and agent_id — nothing about the customer, no reason and no variables; the agent reads those from Graine when the call connects.

{ "type": "agent_call", "call_id": "c3a8f1d2-5b7e-4a19-9f02-6d4e8b1a7c35", "caller_name": "Asha from Acme", "hosted": "1", "agent_id": "agent_5b7d21e9c8a34f60" }

Errors

GraineError

What a method that asks Graine fails with.

What to expect: the same codes on every platform — invalid_key, origin_refused, rate_limited, invalid_request, identity_required, device_limit, scheduling_off, too_soon, too_far, outside_window, too_many_pending, not_found, unavailable, network — and a newer one as unknown, carrying its word. Retry network and unavailable with backoff, and rate_limited after retryAfterSeconds; fix the setup for invalid_key and origin_refused; show the message for the scheduling codes. When each happens, which methods raise it, and the fix: Errors.

{ "code": "too_soon", "message": "Pick a time at least 5 minutes from now", "retryAfterSeconds": null, "status": 0 }

Agent instances

An app can run several agents, each under a name with its own publishable key — Use more than one agent in your app, and the signatures on the SDK reference.

What to expect: a name is trimmed, and an empty one is the default agent, "default". Configuring a name again returns that agent unchanged. Each agent has its own session and design, chat, voice bar, actions, prompt variables set with setVariables, booking rules and bookings, memory scope and kept conversation. Shared by every agent: who the customer is, the install ID, the memory choice, the current screen, the call engine — and one conversation at a time.

Screens, actions and components

GraineScreen and GraineField

What your app reports about a screen.

{
  "screen": "delivery_address",
  "title": "Delivery address",
  "journey": { "name": "Checkout", "step": 2, "of": 3, "next": "Payment" },
  "fields": [
    { "name": "postal_code", "label": "Postal code", "value": "56007", "status": "invalid", "error": "We don't deliver there yet" }
  ]
}

GraineActionResult

What an action handler answers. ActionResult on Android and in Flutter.

Built with ok(message, data), refused(message) and error(message) on every native platform; a plain object in TypeScript and on the website.

{ "status": "refused", "message": "The order has already shipped, so the address can't change.", "data": {} }

The component

A component the agent drew — the object your own renderer reads.

GraineWidget in React Native and on Android (GraineComponent is its alias on Android); a map in Swift and Dart listeners, and in the website's messages, where the keys are on_select and fallback_text; GraineComponent(id, kind, title, payload) in Kotlin Multiplatform, where payload is the whole component as it arrived. A kind your build does not know is still handed over — draw its fallbackText.

{
  "id": "w_19",
  "kind": "calendar_slots",
  "data": { "slots": [{ "id": "2026-10-17T10:00", "label": "Fri 17 Oct, 10:00" }, { "id": "2026-10-17T15:30", "label": "Fri 17 Oct, 15:30" }] },
  "style": { "preset": "compact" },
  "onSelect": { "path": "appointments?time={id}" },
  "fallbackText": "I can offer Friday at 10:00 or 15:30."
}

Connection values

The bar's own call — not a native call — reports these.

Each SDK spells them in its own style — GrainePhase and GraineConnectStage in Swift (voice.connectStage), CallPhase and ConnectStage on Android and in Flutter (voice.connectStage), ConnectionQuality everywhere. A stage an SDK does not know is ignored, never guessed at.

Wire frames the SDK handles for you

For the curious: the SDKs read and send these themselves, and your app never has to.

The history frame

How earlier messages reach a chat when the conversation continues: one frame, before any message from the agent.

{
  "type": "history",
  "turns": [
    { "id": "6a1f0c2e9b7d", "role": "user", "text": "Can you move my delivery?", "at": "2026-10-12T13:10:31Z", "channel": "voice" },
    { "id": "6a1f0c2e9b7e", "role": "assistant", "text": "Done — I've moved your delivery to Friday.", "at": "2026-10-12T13:10:44Z", "channel": "voice" }
  ],
  "continued": true
}

role is user or assistant, at is ISO-8601 in UTC, and channel is chat or voice (anything else is read as chat). A turn that cannot be read — no text, no time, another role — is skipped; a frame whose turns is not a list is ignored. The SDKs turn each into a GraineChatTurn with restored set.

The website loader's messages

The loader on your page talks to the widget's frame with postMessage.

The widget answers a different visitor, or nobody, by clearing its chat and starting again; a page that hosts the engine itself sends these the same way.