Flutter SDK reference

Every public declaration the Flutter package, graine_inapp 0.10.3, exports, read from its source and grouped by what you are doing: installing, identifying the customer, the chat, the voice bar, several agents, screen context and components, calls in both directions, booking, design, going live, events and errors. Each entry starts with what it is for, then its signature, its parameters, what it returns, the errors it can raise and an example; each type sits beside the functions that use it, field by field, with what to expect. The same API across every platform, topic by topic, is the SDK reference; installing and setting up is Flutter.

Requirements, install, permissions and initialisation

YAML — pubspec.yaml

dependencies:
  graine_inapp: ^0.10.3
  permission_handler: ^11.0.0     # or whatever your app already uses to ask for permissions

• Calls that ring on Android: add Firebase Cloud Messaging to the Android app — google-services.json in android/app, the Google services Gradle plugin, and com.google.firebase:firebase-messaging in android/app/build.gradle.kts — and the SDK registers for pushes itself: its own messaging service rings Graine's calls natively, with no Dart. An app that uses firebase_messaging has its messaging service instead, which receives every message: it forwards them to handlePush (below).

• Android: nothing to add to your manifest — the package's own merges into the app: the permissions (internet, microphone, notifications, the full-screen call notification and the microphone's foreground service), the call screen, the microphone service and the call receiver. Set minSdk 24 or higher, and ask for the notification permission on Android 13+ yourself (for example Permission.notification.request()), so a ring can show.

• iOS: on the Runner target add NSMicrophoneUsageDescription to Info.plist (for example "The assistant listens when you talk to it."), the Push Notifications capability, and Background Modes → Audio, AirPlay, and Picture in Picture and Voice over IP. CallKit and VoIP pushes need a real iPhone: the simulator cannot ring.

• Microphone: for the bar's voice, your app asks, in GraineConfig.requestMicrophone, which the SDK calls before every call (left out, the SDK assumes you asked). For native calls, the SDK asks.

Flutter · Dart — lib/main.dart

import 'package:flutter/material.dart';
import 'package:firebase_core/firebase_core.dart';
import 'package:graine_inapp/graine_inapp.dart';
import 'package:permission_handler/permission_handler.dart';
 
Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();
  GraineInApp.init(GraineConfig(
    baseUrl: 'https://www.graine.ai',
    publishableKey: 'pk_live_…',                       // Agent → Embed & Widgets → Install
    requestMicrophone: () async => (await Permission.microphone.request()).isGranted,
  ));
  await GraineCalls.instance.configure(const GraineCallsOptions(
    publishableKey: 'pk_live_…',
    displayName: 'Asha from Acme',
  ));
  GraineCalls.instance.attach();                       // identity, variables, the screen and actions reach the call
  runApp(MaterialApp(
    // Once, above the navigator: a call outlives every route.
    builder: (context, child) => GraineEngine(child: Stack(children: [child!, const GraineAgentBar()])),
    home: const HomeScreen(),
  ));
}

WebRTC calls

Turn it on to carry the native calls' audio over WebRTC instead of the WebSocket — in both directions: the customer calling the agent (startCall, your "Call" button) and the customer answering a call Graine rang (a booked call, or "Ring now"). Off unless the app is built with it. New in 0.9.0.

iOS — at the top of ios/Podfile:

ENV['GRAINE_WEBRTC'] = '1'

Android — in android/gradle.properties:

graineWebRtc=true

On a build server, GRAINE_WEBRTC=1 in the build's environment turns it on for both. Then rebuild — it is native code, so it reaches customers with your next store build. flutter build runs pod install when the Podfile changes; with only the environment variable, run pod install in ios/ too.

• Nothing else changes. No code to write, no Info.plist entry, no capability: the same ring, the same call screen, the same "Connecting…", the same outcomes. GraineCallsOptions(callTransport:) chooses how calls carry their audio, and GraineCallTransport.auto, the default, takes WebRTC in a build that has it — see GraineCallTransport.
• What the customer 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. The agent's voice arrives at telephone bandwidth over WebRTC today: steadier through a weak network, narrower than the WebSocket's on a perfect one.
• When WebRTC cannot set up a call — 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 WebRTC. Once audio flows, a call never moves: a network drop is retried once, then the call ends as dropped. The snapshot says which one carried each call, and why: GraineCallSnapshot.transport and GraineCallSnapshot.transportFallbackReason.
• The dashboard's switch. The agent's In-app call audio setting (agent → Calls & scheduling): WebRTC (recommended) or Standard. Standard moves every install's calls back to the WebSocket, whatever the app chose, from each app's next start — no app release. (The voice bar's own in-app call has its own setting: GraineConfig.transport and the agent's Call audio.)
• Size. A prebuilt WebRTC library — Google's WebRTC, its symbols renamed so it never clashes with another copy in the app (flutter_webrtc, a video-calling SDK). On an iPhone (arm64), about 12 MB more installed and about 6 MB more to download. On Android, 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.
• One version of the library. CocoaPods installs one version of this WebRTC build: if another plugin in the app pins it at a different version, the two cannot be installed together. Leave WebRTC off (calls stay on the WebSocket) or align the versions.
• Permissions. Android: the plugin adds ACCESS_NETWORK_STATE to your manifest — a normal permission, granted at install: nothing is asked — and its R8 rules ship inside it. iOS: nothing new.
• Licences. WebRTC is BSD 3-Clause, with Google's patent grant: list it in your app's open-source licences.

await GraineCalls.instance.configure(const GraineCallsOptions(
  publishableKey: 'pk_live_…',
  displayName: 'Asha from Acme',
  callTransport: GraineCallTransport.auto,   // the default: WebRTC in a build that has it
));

Which one carried a call, read once it is active:

GraineCalls.instance.addListener(() {
  final call = GraineCalls.instance.value;
  if (call.status != GraineNativeCallStatus.active) return;
  if (call.transport == GraineCallTransport.websocket && call.transportFallbackReason != null) {
    debugPrint('WebRTC could not carry this call (${call.transportFallbackReason}); it runs on the WebSocket.');
  }
});

Install and the first answer

Configure each agent once, at launch, with its publishable key; place GraineEngine once, above your navigator; the agent's settings (its session: design, identity, memory and booking rules) then arrive by themselves. Everything else on this page goes through the agent init returns. Readiness: loadSession() completes when the settings are in, and GraineConnectivity says whether the page that carries the voice call is there.

GraineInApp.init

Call it once at launch, before runApp, to configure an agent with its publishable key — every other call on this page goes through the agent it returns.

static GraineInApp init(GraineConfig config, {String name = defaultName})

Configures an agent and starts fetching its configuration at once. Call it before runApp or in your first widget; it initialises the Flutter binding itself. Without a name it is the default agent. The name is trimmed, and an empty name is the default agent. A later call with a name already configured returns that agent unchanged (the new config is not applied).

Returns — a new GraineInApp.

Errors — none.

GraineInApp.init(GraineConfig(baseUrl: 'https://www.graine.ai', publishableKey: 'pk_live_…'));

GraineInApp

Use it to reach an agent you configured — its call, chat, components, session and design — and to make every request your app sends Graine on the customer's behalf.

The in-app agent: one instance per publishable key, configured with GraineInApp.init(config) before runApp and reached afterwards as GraineInApp.instance (or GraineInApp.named('support') for an agent configured under a name). Accessing instance before init throws StateError. It is a WidgetsBindingObserver. Use it on the main (UI) isolate only.

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

Its functions: init, loadSession, identify, installId, setMemory, memoryEnabled, memories, forgetMemory, named, all, instance, maybeInstance, defaultName, name, setVariables, currentVariables, setScreen, updateField, removeField, clearScreen, track, tap, captureTap, noteInteraction, registerAction, checkActions, executeAction, configureFriction, clearPendingWidget, bookingAvailable, bookingBlocker, bookingListenable, deviceTimezone, schedulingRules, scheduleCall, scheduledCalls, cancelScheduledCall, loadDesignFonts, addListener, removeListener — each with its parameters, what it returns, the errors it raises and an example.

GraineInApp.loadSession

Call it when you need the agent's settings (design, identity, memory, booking rules) before the SDK has fetched them on its own, or to try again after a fetch failed.

Future<SessionConfig?> loadSession()

Fetches the agent's configuration once; concurrent callers share one request, and a failure is retried by the next caller. Completes with null on failure, which is also reported through GraineListener.onError. init calls it.

Parameters — none.

Returns — Future<SessionConfig?> — its fields: SessionConfig. Example value: null.

Errors — none.

final result = await GraineInApp.instance.loadSession();

GraineConfig

Use it to say, once, which agent the app talks to and how: the publishable key, your build's prompt variables, fonts, timing and switches.

Everything the SDK needs up front, passed to GraineInApp.init. Immutable.

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

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

GraineConfig.GraineConfig

Use it to build the configuration you pass to GraineInApp.init.

const GraineConfig({required this.baseUrl, required this.publishableKey, this.variables = const <String, Object?>{}, this.transport, this.appVersion, this.endOnBackground = true, this.timing = const GraineTiming(), this.debug = false, this.friction, this.requestMicrophone, this.fonts = const <String>[], this.captureTaps = true, this.chatSize})

The constructor.

Returns — a new GraineConfig.

Errors — none.

final result = GraineConfig(baseUrl: 'https://www.graine.ai', publishableKey: 'pk_live_…');

GraineTiming

Use it to change how long the SDK waits for the voice engine and a connect before it retries or says so — only for an app used on very slow networks.

Load and connect timing, for an app used on very slow networks. Passed as GraineConfig.timing; all values in milliseconds.

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

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

GraineTiming.GraineTiming

Use it to build the timing you pass as GraineConfig(timing:).

const GraineTiming({this.stallMs = 15000, this.bootMs = 15000, this.hardCapMs = 120000, this.retryDelaysMs = const <int>[1000, 2000, 4000, 8000, 15000, 15000], this.endWatchdogMs = 4000, this.slowConnectMs = 4000})

The constructor.

Returns — a new GraineTiming.

Errors — none.

final result = GraineTiming();

GraineEngine

Use it to carry an agent's voice call: place it once near the root, above your navigator, so a call outlives every screen and starts at once.

class GraineEngine extends StatefulWidget

What to expect — Place it once, near the root, above your navigator — one per agent the customer can call. It is one invisible pixel; it loads the agent's page idle at mount, so a tap starts a call at once, and it tells the agent what the customer taps while a screen is set (GraineConfig.captureTaps).

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

GraineEngine.GraineEngine

Use it to place the engine for the default agent — or, with app:, for another agent the customer can call.

const GraineEngine({super.key, this.child, this.voice, this.app})

Returns — a new GraineEngine.

Errors — none.

MaterialApp(
  // Once, above the navigator: a call outlives every route.
  builder: (context, child) => GraineEngine(child: Stack(children: [child!, const GraineAgentBar()])),
  home: const HomeScreen(),
);

SessionConfig

Read it to see what the dashboard says about this agent — its appearance, design, actions, identity, memory and call settings — once the session has arrived.

class SessionConfig

What to expect — Fetched once per launch when the agent is configured, and kept for the run; null until it arrives (GraineInApp.session). A setting the server does not send is null, and the SDK then behaves as before that setting existed.

Its functions: SessionConfig, fromJson, errorFor — each with its parameters, what it returns, the errors it raises and an example.

SessionConfig.SessionConfig

Use it to build a session by hand for a test or a preview; the SDK fetches the real one.

const SessionConfig({ required this.agentId, required this.webcallAgentId, this.appearance = const <String, Object?>{}, this.variables = const <String, Object?>{}, this.pageVersion, this.declaredActions = const <String>{}, this.friction, this.design, this.wsHost, this.identity, this.memory, this.calls})

Returns — a new SessionConfig.

Errors — none.

const session = SessionConfig(agentId: 'agent_123', webcallAgentId: 'agent_123_web');

SessionConfig.fromJson

Use it to read a session from the JSON Graine sends — for a session you stored, or a test; the SDK does this itself when it loads.

static SessionConfig fromJson(Map<String, Object?> data)

Reads the session as Graine sends it, the same way every Graine SDK reads it; anything missing takes its default.

Returns — SessionConfig.

Errors — none.

import 'dart:convert';
 
const stored = '{"agentId": "agent_123", "webcallAgentId": "agent_123_web"}';   // a session your app kept
final session = SessionConfig.fromJson(jsonDecode(stored) as Map<String, Object?>);

SessionConfig.errorFor

Use it to turn a refused session request into the sentence that tells whoever has to fix it what to change.

static String? errorFor(int status, Map<String, Object?> body)

For a refused session request, a sentence aimed at the person who has to fix it; for a 2xx response, null.

Returns — String?. Example value: 'Publishable key was rejected. Check it against Embed & Widgets in the dashboard.'.

Errors — none.

final sentence = SessionConfig.errorFor(401, const <String, Object?>{});

GraineConnectivity

Read it to know whether the page that carries the voice call is there — loading, ready, retrying or failed — and to offer a retry when it failed.

enum GraineConnectivity { loading, ready, retrying, failed }

What to expect — loading at launch and after retry(); ready once the page has loaded; retrying while a failed load waits for its next attempt (the bar says "Reconnecting…"); failed once every attempt in GraineTiming.retryDelaysMs is spent, or the agent's settings could not be loaded (the bar says "Couldn't load · tap to retry"). onConnectivity reports every change. A page that is carrying a call is never reloaded.

Identity, memory and conversations that continue

Tell the agent who the customer is, let them choose whether they are remembered, show them what is remembered and delete it, and start a conversation over. An identified customer who comes back — later today, or on their other phone — finds the chat where they left it, and the agent picks up from there. Nothing here is needed for an anonymous customer: they simply start fresh every time.

GraineInApp.identify

Call it when the customer signs in — and with null when they sign out — so the agent knows who it is talking to and can remember them between conversations.

void identify(Map<String, Object?>? traits, {bool? memory})

Who is signed in. Traits become prompt variables, masked on the device, and land on the call record — except the one trait the agent's Identity setting names (user_id unless it names email, phone or a custom trait), which is kept raw and sent only where Graine needs it to recognise the user, never as a prompt variable or in the screen context. A placeholder (such as "guest", "null" or an already-masked "[EMAIL]"), null, a boolean or a fraction identifies nobody: that conversation is anonymous, with no memory. memory: false: this user's conversations are neither remembered nor recalled; the choice is kept on the device for this user, and when left out their last choice stands (on until they make one). A conversation keeps the identity it started with; a change applies from the next conversation. null signs out: Graine is told this device is no longer the user's, a chat open for them ends and its transcript is cleared, and later conversations are anonymous. A different user signing in without a sign-out first signs the previous one out the same way. One user for the whole app: every agent the app configured hears it (each keeps the trait its own Identity setting names), and the native call engine receives it too.

Returns — nothing; it returns when done.

Errors — none.

GraineInApp.instance.identify({'user_id': user.id, 'name': user.firstName, 'plan': user.plan}, memory: user.allowsMemory);
// on sign-out
GraineInApp.instance.identify(null);

GraineInApp.installId

Read it when you need this install's id — the one the SDK and the native call engine send Graine for this device, the same for every agent.

Future<String> get installId

This install's id: a UUID made on the app's first launch and kept by the platform — in the Keychain on iOS, where it survives a reinstall, and in storage excluded from backups on Android. The native call engine sends the same id, and every agent shares it. Graine counts a customer's devices by it (Devices per user in the dashboard); identify ties it to the customer, and identify(null) lets it go.

Parameters — none.

Returns — Future<String> — a lower-case UUID. Example value: '6f1c2a9e-7d1b-4c47-9a6e-2f0d8b1c5e44'.

Errors — none.

final id = await GraineInApp.instance.installId;

GraineInApp.setMemory

Call it when the customer turns "remember me" on or off in your app's settings.

void setMemory(bool enabled)

Turns remembering on or off for the current user's conversations; it does what identify(currentTraits, memory: enabled) does. Kept on the device for that user (for an anonymous user, for this run only). Applies to every agent and reaches the native call engine.

Returns — nothing; it returns when done.

Errors — none.

GraineInApp.instance.setMemory(true);

GraineInApp.memoryEnabled

Call it to read the customer's memory choice — to show your settings switch in the right position.

Future<bool> memoryEnabled()

The current user's memory choice: true unless they turned it off. Waits for the agent's configuration and the choices kept on the device.

Parameters — none.

Returns — Future<bool>. Example value: true.

Errors — none.

final result = await GraineInApp.instance.memoryEnabled();

GraineInApp.memories

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

Future<List<GraineMemory>> memories()

What this agent remembers about the identified user, already redacted, in Graine's order: newest first, at most 100. For a "what you remember about me" screen. Only from a device that is theirs.

Parameters — none.

Returns — Future<List<GraineMemory>> — its fields: GraineMemory. Example value: [GraineMemory(id: 'm_41', text: 'Prefers a call after 6 pm', createdAt: 2026-10-02 09:14:00.000Z, updatedAt: 2026-10-12 17:40:00.000Z)].

Errors — GraineException: identityRequired (checked on the device first), deviceLimit, rateLimited, unavailable, invalidKey, originRefused, network, unknown

final result = await GraineInApp.instance.memories();

GraineInApp.forgetMemory

Call it when the customer asks the agent to forget them: it deletes everything the agent remembers about the signed-in customer.

Future<int> forgetMemory()

Deletes everything this agent's memory holds about the identified user. Allowed only from a device that is theirs. Completes with the number deleted (0 when Graine does not say).

Parameters — none.

Returns — Future<int> — how many memories were deleted. Example value: 3.

Errors — GraineException: identityRequired (checked on the device first), deviceLimit, rateLimited, unavailable, invalidKey, originRefused, network, unknown

final result = await GraineInApp.instance.forgetMemory();

GraineChatSession.newConversation

Call it when the customer wants to start over: a fresh conversation with the welcome and the starters, while what the agent remembers about them stays.

Future<void> newConversation()

Starts a new conversation — a fresh thread, as a support chat offers one.

Parameters — none.

Returns — nothing; it returns when done.

Errors — none.

await GraineInApp.instance.chat.newConversation();

GraineMemory

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

class GraineMemory

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

Its functions: GraineMemory, fromJson, listFrom, toJson — each with its parameters, what it returns, the errors it raises and an example.

GraineMemory.GraineMemory

Use it to build a memory by hand for a test or a preview; memories() returns the real ones.

const GraineMemory({required this.id, required this.text, this.createdAt, this.updatedAt})

Returns — a new GraineMemory.

Errors — none.

const memory = GraineMemory(id: 'm_1', text: 'Prefers calls in the evening');

GraineMemory.fromJson

Use it to read one memory from JSON you stored; memories() already returns them read.

static GraineMemory? fromJson(Object? raw)

Returns null for anything other than a memory that has an id and some text.

Returns — GraineMemory?. Example value: GraineMemory(id: 'm_41', text: 'Prefers a call after 6 pm', createdAt: 2026-10-02 09:14:00.000Z, updatedAt: 2026-10-12 17:40:00.000Z).

Errors — none.

final memory = GraineMemory.fromJson({'id': 'mem_1', 'text': 'Prefers a call after 6 pm', 'createdAt': '2026-10-01T09:30:00Z'});

GraineMemory.listFrom

Use it to read a list of memories from an answer you stored or forwarded, newest first.

static List<GraineMemory> listFrom(Object? body)

{memories: [...]} (or a bare list), in Graine's order — newest first. Entries that are not memories are skipped.

Returns — List<GraineMemory>. Example value: [GraineMemory(id: 'm_41', text: 'Prefers a call after 6 pm', createdAt: 2026-10-02 09:14:00.000Z, updatedAt: 2026-10-12 17:40:00.000Z)].

Errors — none.

final memories = GraineMemory.listFrom({'memories': [{'id': 'mem_1', 'text': 'Prefers a call after 6 pm'}]});

GraineMemory.toJson

Use it to turn a memory into JSON — to cache it or hand it to your own server.

Map<String, Object?> toJson()

Parameters — none.

Returns — Map<String, Object?>.

Errors — none.

for (final memory in await GraineInApp.instance.memories()) {
  debugPrint(memory.toJson().toString());
}

IdentitySetting

Read it to know which trait identifies a customer for this agent (user_id unless the dashboard names another) and how many devices each customer may use.

class IdentitySetting

What to expect — Part of the session; null until it arrives, and from an agent that does not say — which means user_id and 2 devices.

Its functions: IdentitySetting, fromJson — each with its parameters, what it returns, the errors it raises and an example.

IdentitySetting.IdentitySetting

Use it to build the identity setting by hand for a test; the session carries the real one.

const IdentitySetting({this.field = Identity.defaultField, this.devicesPerUser = 2})

Returns — a new IdentitySetting.

Errors — none.

final result = IdentitySetting();

IdentitySetting.fromJson

Use it to read the identity setting from the session's JSON.

static IdentitySetting? fromJson(Object? raw)

Null when raw is not an object — the settings did not say.

Returns — IdentitySetting?. Example value: null.

Errors — none.

final identity = IdentitySetting.fromJson({'field': 'email', 'devicesPerUser': 2});

MemorySetting

Read it to know whether the agent remembers identified customers between conversations.

class MemorySetting

What to expect — Part of the session; null until it arrives, and from an agent that does not say — which means memory off.

Its functions: MemorySetting, fromJson — each with its parameters, what it returns, the errors it raises and an example.

MemorySetting.MemorySetting

Use it to build the memory setting by hand for a test; the session carries the real one.

const MemorySetting({this.enabled = false})

Returns — a new MemorySetting.

Errors — none.

final result = MemorySetting();

MemorySetting.fromJson

Use it to read the memory setting from the session's JSON.

static MemorySetting? fromJson(Object? raw)

Returns — MemorySetting?. Example value: null.

Errors — none.

final memory = MemorySetting.fromJson({'enabled': true});

Identity

Use it to check on the device what the SDK treats as a customer's identity: which trait, which values identify nobody, and what is sent with a request.

abstract final class Identity

What to expect — Public so a custom UI can reuse it; an integration does not need it.

Its functions: normaliseField, valueOf, pick, normaliseInstallId, normaliseTimezone, uuidV4, serverLowercase, serverTrim, normaliseValue, memoryKey, withoutIdentity, requestFields — each with its parameters, what it returns, the errors it raises and an example.

Identity.normaliseField

Use it to turn a trait name into the form the identity setting stores — or to learn that it is not a valid trait name.

static String? normaliseField(Object? field)

A trait name as the setting stores it: trimmed, lower case, and matching ^[a-z][a-z0-9_]{0,39}$ — else null.

Returns — String?. Example value: 'customer_id'.

Errors — none.

final field = Identity.normaliseField(' Customer_ID ');

Identity.valueOf

Use it to read one trait's value the way the SDK sends it as an identity — or learn that it identifies nobody.

static String? valueOf(Object? v)

Returns one trait in the raw form the identity channel sends, or null for a value that identifies nobody: null, a boolean, a fraction, an object or a list, a placeholder, or anything longer than maxValueLength.

Returns — String?. Example value: null (a placeholder identifies nobody).

Errors — none.

final value = Identity.valueOf('guest');

Identity.pick

Use it to find the identity among a customer's traits for the agent's identity trait.

static String? pick(Map<String, Object?>? traits, String field)

The identity in traits for the setting's field: the trait under exactly that name, else one whose name normalises to it (Customer_ID for customer_id).

Returns — String?. Example value: 'u_8812'.

Errors — none.

final value = Identity.pick({'user_id': 'u_8812', 'plan': 'gold'}, 'user_id');

Identity.normaliseInstallId

Use it to check that an install id is in the shape the SDK sends.

static String? normaliseInstallId(Object? id)

An install id this SDK will send: lower case and matching ^[0-9a-f-]{16,64}$ — else null.

Returns — String?. Example value: '6f1c2a9e-7d1b-4c47-9a6e-2f0d8b1c5e44'.

Errors — none.

final id = Identity.normaliseInstallId('6F1C2A9E-7D1B-4C47-9A6E-2F0D8B1C5E44');

Identity.normaliseTimezone

Use it to check that a time zone name is one the SDK sends (an IANA name such as Asia/Kolkata).

static String? normaliseTimezone(Object? zone)

Returns an IANA zone name that Graine's servers accept, such as Asia/Kolkata or UTC, or null.

Returns — String?. Example value: 'Asia/Kolkata'.

Errors — none.

final zone = Identity.normaliseTimezone('Asia/Kolkata');

Identity.uuidV4

Use it to make a random version-4 UUID, the shape of an install id.

static String uuidV4([math.Random? random])

Makes a random lower-case UUIDv4, used as the install id where the platform cannot supply one (a test or a desktop build).

Returns — String. Example value: '6f1c2a9e-7d1b-4c47-9a6e-2f0d8b1c5e44'.

Errors — none.

final id = Identity.uuidV4();

Identity.serverLowercase

Use it to lower-case text exactly as Graine does when it compares identities.

static String serverLowercase(String s)

Lower-cases text exactly as Graine does when it compares identities — including the full mapping of U+0130 ("İ" → "i̇") and the final sigma ("ΟΔΟΣ" → "οδος"), which Dart's toLowerCase() does not apply.

Returns — String. Example value: 'asha@example.com'.

Errors — none.

final lower = Identity.serverLowercase('Asha@Example.COM');

Identity.serverTrim

Use it to trim whitespace exactly as Graine does when it compares identities.

static String serverTrim(String s)

Returns — String. Example value: 'u_8812'.

Errors — none.

final trimmed = Identity.serverTrim('  u_8812 ');

Identity.normaliseValue

Use it to see how Graine reads an identity value for a trait — trimmed, and lower case for an email — before it compares it.

static String? normaliseValue(String field, Object? value)

Returns — String?. Example value: 'asha@example.com'.

Errors — none.

final value = Identity.normaliseValue('email', ' Asha@Example.com ');

Identity.memoryKey

Use it to compute the key the customer's memory choice is kept under on this device.

static String memoryKey(String field, String value)

The key one customer's memory choice is kept under on the device, the same on every Graine SDK: the first 16 bytes of the SHA-256 of graine:memory:v1, a newline, the trait, a newline and the normalised value, as hex. Nothing about the customer can be read back from it.

Returns — String. Example value: 32 hex characters, e.g. '3f2a…'.

Errors — none.

final key = Identity.memoryKey('user_id', 'u_8812');

Identity.withoutIdentity

Use it to take the identity trait out of a set of traits — what the SDK does before traits become prompt variables.

static Map<String, Object?>? withoutIdentity(Map<String, Object?>? traits, String? field)

traits without the trait that identifies the customer — that one travels only with the identity, never as a prompt variable or in the screen context.

Returns — Map<String, Object?>?. Example value: {'plan': 'gold'}.

Errors — none.

final rest = Identity.withoutIdentity({'user_id': 'u_8812', 'plan': 'gold'}, 'user_id');

Identity.requestFields

Use it to build the identity fields the SDK adds to a request to Graine.

static Map<String, Object?> requestFields({ String? value, required String installId, bool? memory, String? timezone, String? callId})

Returns — Map<String, Object?>.

Errors — none.

final fields = Identity.requestFields(value: 'u_8812', installId: await GraineInApp.instance.installId, memory: true, timezone: 'Asia/Kolkata');

Chat

The agent's typed conversation: the same agent, screen context and actions as the call, in writing. GraineAgentBar offers and opens it for you; GraineChat places it yourself; for a chat of your own design, draw from GraineInApp.instance.chat (a GraineChatSession) and lay its rows out with ChatRows and ChatPieces. One conversation at a time: opening the chat ends a call the bar holds.

GraineChat

Use it to place the chat window yourself — a screen, a tab or a sheet of your own — in the agent's design.

class GraineChat extends StatefulWidget

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

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

GraineChat.GraineChat

Use it to place the chat window where you want it; it opens the chat while it is on screen and closes it when it leaves.

const GraineChat({ super.key, this.chat, this.components, this.design, this.scheme, this.accent, this.name, this.onClose, this.showComponents = true, this.app})

Returns — a new GraineChat.

Errors — none.

Navigator.of(context).push(PageRouteBuilder<void>(
  pageBuilder: (context, _, __) => GraineChat(onClose: () => Navigator.of(context).pop()),
));

GraineChat.open

Call it to open the chat now, at a size you choose for this once — on the agent's bar when one is on screen, else over your navigator.

static Future<void> open(BuildContext context, {GraineInApp? app, GraineChatSize? size})

Opens the chat at size for this open — over the app's size (GraineConfig.chatSize) and the dashboard's (Embed & Widgets → Appearance → Chat window → Window size). With the agent's bar on screen, the bar moves to the chat and draws it; with no bar, the chat shows over your navigator — a sheet, a tablet's panel or a screen of its own — and compact, which rides on the bar, opens as large.

Returns — Future<void>, which completes when the chat closes.

Errors — none.

await GraineChat.open(context, size: GraineChatSize.full);

GraineChatSession

Use it to draw a chat of your own: the conversation, the connection and the customer's booked calls, as a ChangeNotifier you listen to.

class GraineChatSession extends ChangeNotifier implements GraineChatState, GraineChatConnection, GraineChatTyping

What to expect — GraineInApp.instance.chat (each agent has its own, created on first use). It connects while the customer is in the chat (open()) and hangs up when they leave (close()); a message typed while it is not connected is shown at once and sent when it is, and a dropped connection is made again with backoff (the GraineTiming.retryDelaysMs ladder) — reconnecting is true meanwhile — then, every try spent, stays offline (failed) until the customer sends something. An identified customer who comes back finds the conversation restored when it opens. It is a ChangeNotifier: listen to it and redraw. Opening the chat ends a call the bar holds. A conversation that starts with a ticket carries the prompt variables on its ticket — since 0.8.0 they are no longer added to that connection's address — and one without a ticket carries them in its address.

Everything it has — its own members, and those of the three interfaces it implements:

Its functions: newConversation, answerWidget, clear, refreshUpcoming, cancelUpcoming, cancelStateOf — each with its parameters, what it returns, the errors it raises and an example.

GraineChatSession.answerWidget

Call it when the customer answers a component the agent drew in the chat, if you draw components yourself.

void answerWidget(String widgetId, Map<String, Object?> data, String summary)

Answers a component the agent drew in the chat: the structured answer, then summary as the customer's turn — without it the conversation does not move.

Returns — nothing; it returns when done.

Errors — none.

final components = GraineInApp.instance.components;
final widget = components.widget, content = components.content;
if (widget != null && content != null) {
  final answer = content.pick(0);   // the customer tapped the first row
  GraineInApp.instance.chat.answerWidget(widget.id, answer.data, answer.summary);
}

GraineChatSession.clear

Call it to empty the chat on screen without ending the conversation Graine keeps.

void clear()

Empties the chat on screen — only the screen. The connection stays as it is, and nothing Graine keeps is touched: an identified customer's conversation comes back with the history the next connection brings, and the agent's memories stay. A message still waiting to be sent is cleared with the rest. newConversation() starts over; forgetMemory() forgets.

Parameters — none.

Returns — nothing; it returns when done.

Errors — none.

GraineInApp.instance.chat.clear();

GraineChatState

Implement it to hand the bar a chat your app runs itself; GraineChatSession is the SDK's own.

abstract class GraineChatState implements Listenable

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

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

GraineChatState.send

Call it to send the customer's typed message.

void send(String text)

The customer typed text and sent it.

Returns — nothing; it returns when done.

Errors — none.

GraineInApp.instance.chat.send('Where is my order?');

GraineChatConnection

Use it to connect the chat while the customer is in it and hang it up when they leave.

abstract interface class GraineChatConnection

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

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

GraineChatConnection.open

Call it when the customer enters your chat screen: the chat connects, and the agent greets a new customer.

void open()

Call it when the customer is in the chat; it connects and keeps the connection up.

Parameters — none.

Returns — nothing; it returns when done.

Errors — none.

@override
void initState() {
  super.initState();
  GraineInApp.instance.chat.open();
}

GraineChatConnection.close

Call it when the customer leaves your chat screen: the chat hangs up; the conversation stays.

void close()

The customer left the chat: hang up.

Parameters — none.

Returns — nothing; it returns when done.

Errors — none.

@override
void dispose() {
  GraineInApp.instance.chat.close();
  super.dispose();
}

GraineChatTyping

Read it to show a typing bubble while the agent composes its answer.

abstract interface class GraineChatTyping

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

GraineChatTurn

Read it to draw one message of the chat — who said it, what, when, and whether it was delivered.

class GraineChatTurn

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

Its functions: GraineChatTurn, copyWith — each with its parameters, what it returns, the errors it raises and an example.

GraineChatTurn.GraineChatTurn

Use it to build a message by hand for a test or a preview; the chat makes the real ones.

const GraineChatTurn({ required this.id, required this.role, required this.text, required this.at, this.delivery, this.proactive = false, this.component, this.live = false, this.restored = false, this.channel = GraineChatChannel.chat})

Returns — a new GraineChatTurn.

Errors — none.

final turn = GraineChatTurn(id: 't1', role: GraineChatRole.user, text: 'Where is my order?', at: DateTime.now(), delivery: GraineChatDelivery.sent);

GraineChatTurn.copyWith

Use it to make a changed copy of a message — its text, whether it is still arriving, its delivery or its component.

GraineChatTurn copyWith({String? text, bool? live, GraineChatDelivery? delivery, GraineComponent? component})

Returns — GraineChatTurn.

Errors — none.

final turns = GraineInApp.instance.chat.turns;
final settled = turns.isEmpty ? null : turns.last.copyWith(live: false);

GraineChatRole

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

enum GraineChatRole { user, agent }

What to expect — Every message has one. Draw the customer's on one side and the agent's on the other.

GraineChatDelivery

Read it to show whether the customer's message is sending, sent or failed — and offer a retry when it failed.

enum GraineChatDelivery { sending, sent, failed }

What to expect — Only on the customer's messages; null on the agent's. A message typed while the chat is not connected is shown at once as sending and goes the moment it connects.

GraineChatChannel

Read it to tell a typed message from one said on a call, so an earlier call is drawn as one "Voice call" row.

enum GraineChatChannel { chat, voice }

What to expect — chat for every message typed now. Only a restored message — from an earlier conversation — can be voice; the SDK's chat window draws a run of them as one "Voice call · 6:05 PM" row, never their words.

GraineChatSize

Use it to choose how big the chat window opens: compact above the bar, a large sheet or panel, or the full screen.

enum GraineChatSize

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

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

GraineChatSize.fromWire

Use it to read a window size from its word (compact, large, full).

static GraineChatSize? fromWire(Object? raw)

Maps the design's size word to a value; returns null for anything else, whether the word is missing or one only a newer server uses.

Returns — GraineChatSize?. Example value: GraineChatSize.compact.

Errors — none.

final size = GraineChatSize.fromWire('large');

ChatRows

Use it to lay out a chat of your own exactly as the SDK's chat window does: bubbles, one row per earlier call, and day lines.

abstract final class ChatRows

What to expect — The rows a chat window draws for a list of turns: a bubble per chat turn, one "Voice call · time" row per call, and day separators (Today, Yesterday, a date) in the device's time zone.

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

ChatRows.build

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

static List<ChatRow> build(List<GraineChatTurn> turns, {required DateTime now, DateTime Function(DateTime)? local})

The rows for turns (oldest first), in order: a day line before the first row when it is not from today and wherever the day changes, one row per earlier call, and a bubble per typed message.

Returns — List<ChatRow> — its fields: ChatRow. Example value: [].

Errors — none.

final rows = ChatRows.build(GraineInApp.instance.chat.turns, now: DateTime.now());

ChatRows.dayLabel

Use it to get the words for a day line: "Today", "Yesterday" or the date.

static String dayLabel(ChatDayRow row, {required DateTime now, DateTime Function(DateTime)? local})

Gives "Today" or "Yesterday", and otherwise the date in the form ChatTime.booked uses for a day: "Sat 10 Oct", plus the year when it is not the current one ("Wed 31 Dec 2025").

Returns — String. Example value: 'Yesterday'.

Errors — none.

final now = DateTime.now();
for (final row in ChatRows.build(GraineInApp.instance.chat.turns, now: now).whereType<ChatDayRow>()) {
  debugPrint(ChatRows.dayLabel(row, now: now));   // Today, Yesterday, Mon 13 Oct
}

ChatRows.callLabel

Use it to get the words for an earlier call's row.

static String callLabel(String clock)

"Voice call · 6:05 PM" — with clock, the call's first message's time in the device's short form.

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

Errors — none.

for (final row in ChatRows.build(GraineInApp.instance.chat.turns, now: DateTime.now()).whereType<ChatVoiceRow>()) {
  debugPrint(ChatRows.callLabel(ChatTime.clock(row.at, h24: false)));   // Voice call · 6:05 PM
}

ChatRows.callSpoken

Use it to get what a screen reader says for an earlier call's row.

static String callSpoken(String clock)

The text a screen reader reads out for the row, such as "Voice call at 6:05 PM".

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

Errors — none.

final spoken = ChatRows.callSpoken('6:05 PM');

ChatRows.offersNewConversation

Use it to decide whether to offer "New conversation" in your chat's header.

static bool offersNewConversation(List<GraineChatTurn> turns)

The header offers "New conversation" only for a continuing conversation, that is, while restored turns are on screen.

Returns — bool. Example value: true.

Errors — none.

final offer = ChatRows.offersNewConversation(GraineInApp.instance.chat.turns);

ChatRows.offersStarters

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

static bool offersStarters(List<GraineChatTurn> turns)

The brand's starters are for a fresh chat only: they are not offered after the user has said anything, or on a continuing conversation.

Returns — bool. Example value: true.

Errors — none.

final offer = ChatRows.offersStarters(GraineInApp.instance.chat.turns);

ChatRow

Read it as one row of the chat to draw: a day line, an earlier call, or a message.

sealed class ChatRow

What to expect — The rows a chat window draws for a list of turns: a bubble per chat turn, one "Voice call · time" row per call, and day separators (Today, Yesterday, a date) in the device's time zone.

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

ChatRow.ChatRow

The base constructor of the three row types; you never call it directly.

const ChatRow()

Parameters — none.

Returns — nothing you call directly: ChatRow is sealed: its three kinds come from ChatRows.build.

Errors — none.

final rows = ChatRows.build(GraineInApp.instance.chat.turns, now: DateTime.now());

ChatDayRow

Read it to draw a day line between messages.

final class ChatDayRow extends ChatRow

What to expect — The rows a chat window draws for a list of turns: a bubble per chat turn, one "Voice call · time" row per call, and day separators (Today, Yesterday, a date) in the device's time zone.

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

ChatDayRow.ChatDayRow

Use it to build a day line by hand for a test; ChatRows.build makes the real ones.

const ChatDayRow(this.day, this.date, this.at)

Returns — a new ChatDayRow.

Errors — none.

final row = ChatDayRow(ChatDay.yesterday, '2026-10-13', DateTime.utc(2026, 10, 13, 12, 30));

ChatVoiceRow

Read it to draw an earlier call as one "Voice call · 6:05 PM" row — that a call happened and when, never its words.

final class ChatVoiceRow extends ChatRow

What to expect — The rows a chat window draws for a list of turns: a bubble per chat turn, one "Voice call · time" row per call, and day separators (Today, Yesterday, a date) in the device's time zone.

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

ChatVoiceRow.ChatVoiceRow

Use it to build an earlier call's row by hand for a test; ChatRows.build makes the real ones.

const ChatVoiceRow(this.id, this.at, this.first, this.last)

Returns — a new ChatVoiceRow.

Errors — none.

final row = ChatVoiceRow('voice-m7', DateTime.utc(2026, 10, 14, 12, 35), 7, 12);

ChatTurnRow

Read it to draw one message bubble.

final class ChatTurnRow extends ChatRow

What to expect — The rows a chat window draws for a list of turns: a bubble per chat turn, one "Voice call · time" row per call, and day separators (Today, Yesterday, a date) in the device's time zone.

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

ChatTurnRow.ChatTurnRow

Use it to build a bubble row by hand for a test; ChatRows.build makes the real ones.

const ChatTurnRow(this.turn, this.index)

Returns — a new ChatTurnRow.

Errors — none.

final turn = GraineChatTurn(id: 't1', role: GraineChatRole.user, text: 'Where is my order?', at: DateTime.now());
final row = ChatTurnRow(turn, 0);

ChatDay

Read it to know which words a day line takes: today, yesterday or a date.

enum ChatDay { today, yesterday, date }

What to expect — Decided on the device's clock: a conversation that runs past midnight gets a new day line.

ChatPieces

Use it to decide which optional pieces your own chat window draws, as the agent's design sets them: earlier messages, the starters, New conversation, the booked-calls card and Book a call.

final class ChatPieces

What to expect — Work them out again whenever the messages, the booked calls or booking's availability change. The SDK's chat window draws exactly these.

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

ChatPieces.of

Use it to work out the pieces from your own settings.

static ChatPieces of(List<GraineChatTurn> turns, { bool showHistory = true, bool newConversation = true, bool showUpcomingCalls = true, String upcomingTitle = '', int upcomingCount = 0, bool bookingAvailable = false})

The pieces for turns and upcomingCount booked calls, as the design sets them. With earlier messages hidden, the window opens like a new chat: the restored messages are not drawn (the agent still has them), the starters may show, and New conversation — which belongs to earlier messages on screen — does not.

Returns — ChatPieces — its fields: ChatPieces.

Errors — none.

final chat = GraineInApp.instance.chat;
final pieces = ChatPieces.of(chat.turns, upcomingCount: chat.upcomingCalls.length, bookingAvailable: GraineInApp.instance.bookingAvailable);

ChatPieces.ofChat

Use it to work out the pieces from the agent's design (tokens?.chat), as the SDK's chat window does.

static ChatPieces ofChat(List<GraineChatTurn> turns, ThemeChat? chat, {int upcomingCount = 0, bool bookingAvailable = false})

The same, under the design's chat tokens — what the SDK's chat window does. Null tokens (an agent with no design) turn every piece on.

Returns — ChatPieces — its fields: ChatPieces.

Errors — none.

final graine = GraineInApp.instance;
final pieces = ChatPieces.ofChat(graine.chat.turns, graine.tokens?.chat,
    upcomingCount: graine.chat.upcomingCalls.length, bookingAvailable: graine.bookingAvailable);

ChatTime

Use it to write a chat's times the way the SDK does, in the device's own time zone.

abstract final class ChatTime

What to expect — The chat's framing, as the SDK's own chat window uses it. Public so a chat window of your own can reuse it.

Its functions: clock, booked, day — each with its parameters, what it returns, the errors it raises and an example.

ChatTime.clock

Use it to write the short time under a message.

static String clock(DateTime time, {required bool h24})

Formats a time in the device's short style: "9:41 PM", or "21:41" where the device uses a 24-hour clock.

Returns — String. Example value: '9:41 PM' ('21:41' with h24: true).

Errors — none.

final time = ChatTime.clock(DateTime(2026, 10, 14, 21, 41), h24: false);

ChatTime.booked

Use it to write when a booked call rings: "Today, 5:30 PM", "Tomorrow, 9:00 AM" or the date.

static String booked(DateTime at, DateTime now, {required bool h24})

Writes when a booked call is due: "Today, 5:30 PM" or "Tomorrow, 9:00 AM", and otherwise the weekday with the date, as in "Wed 14 Oct, 10:00 AM".

Returns — String. Example value: 'Tomorrow, 9:00 AM'.

Errors — none.

for (final call in await GraineInApp.instance.scheduledCalls()) {
  final at = call.at;
  if (at != null) debugPrint(ChatTime.booked(at, DateTime.now(), h24: MediaQuery.alwaysUse24HourFormatOf(context)));
}

ChatTime.day

Use it to write a day in short words — the weekday and the date, as the booking sheet's chips and lines do.

static String day(DateTime at)

A day in short words on the device's clock: the weekday and the date. New in 0.8.0; the booking sheet's chips, its time zone line and its "Booked — …" line use it.

Returns — String. Example value: 'Wed 14 Oct'.

Errors — none.

final words = ChatTime.day(DateTime(2026, 10, 14, 18));

The voice bar

The assistant bar: the agent's voice call, its captions and components, and the switch to the chat, in one bar the SDK draws in your agent's design. Place GraineEngine once and GraineAgentBar where the bar should sit — or draw your own controls from GraineInApp.instance.voice with the words, phases and meters below, so every surface says the same thing at the same moment.

GraineVoice

Use it to start and end the agent's voice call from your own controls, and to draw its state; GraineAgentBar already does both.

class GraineVoice extends ChangeNotifier implements GraineCallState, GraineCallFault, GraineConnectProgress, GraineCaptionsSwitch

What to expect — GraineInApp.instance.voice (each agent has its own). GraineEngine attaches it once, above the navigator, and GraineAgentBar starts and ends calls itself; use it directly only for controls of your own. It is a ChangeNotifier: listen to it and redraw. One conversation at a time: starting it closes an open chat and ends another agent's call, and it waits while a native call is live.

Everything it has — its own members, and those of the four interfaces it implements:

Its functions: attach, detachPage, detach, viewOpened, viewClosed, answerWidget, reportEvent — each with its parameters, what it returns, the errors it raises and an example.

GraineVoice.attach

Called by GraineEngine to give the call the page that carries it; call it yourself only with an engine page of your own.