Variables

The agent's prompt reads placeholders — {name}, {plan}, {call_reason} — and your app fills them. A variable is a name and a short text value; the prompt uses it wherever it names it, in every channel the user meets the agent on.

What your app can send

The identifier — the trait your Who is the user? setting names, user_id by default — is never a variable: it identifies the user and nothing else. Masking replaces PAN, Aadhaar, card and account numbers, phone numbers and emails with a token ([PHONE], [EMAIL] …) before anything leaves the device; your own formats can be added (addMaskRule).

Merged in this order, the later winning on a shared name: any default values the dashboard holds for the agent, the variables at start-up, setVariables, the traits — and, on a call, the call's own variables, call_reason, then who_called.

How a variable reaches the prompt

• The prompt names it. {plan} in the prompt (or the welcome message) reads the value sent under plan. List the agent's variables under its Custom Variables too: the Install tab's website snippet is written from that list, and your team sees what the prompt expects.
• A variable nothing sets renders empty. Write sentences that read well without it: Hi {name}, welcome back reads "Hi , welcome back" for an anonymous user; Greet the user by name if you know it: {name} does not break.
• Values are text. Numbers and booleans become their text (2, true); nested objects are dropped on iOS, Android, Flutter and Kotlin Multiplatform, and sent as JSON text by React Native.
• Reserved names render empty. A {graine_…} placeholder never shows a value.

What the agent sees, channel by channel

The iOS, Android, Flutter and Kotlin Multiplatform SDKs (from 0.8.0) and React Native (from 0.43.0) send the variables of a chat and of a call only in the signed ticket; the address of a connection opened with a ticket does not repeat them. The website's voice still repeats them on that address too; the agent reads the ticket's, so what it sees is the same. A connection opened without a ticket — rare: only when one cannot be issued — carries them on its address instead.

A ring itself carries no reason and no variables: only the call's id, the call name and the agent. The reason stays with Graine until the user answers.

Reserved keys

Every key starting with graine_ is Graine's own, written only by Graine's servers:

Your app can never set them: a graine_… key in setVariables, in identify's traits, in a call's variables or in load({ variables }) is dropped before the conversation starts — on every path — so no app can claim to be a user it is not. None of them is ever a prompt variable.

What you'll see if…

Examples

// At start-up: your own constants
GraineInApp.configure(GraineConfig(baseUrl: "https://www.graine.ai", publishableKey: "pk_live_…",
                                   variables: ["app_name": "Acme"]))
// Who is signed in: the identifier, then traits that become variables
GraineInApp.shared.identify(["user_id": user.id, "name": user.firstName, "plan": user.plan])
// While the app runs; nil removes one
GraineInApp.shared.setVariables(["cart_items": 3, "promo": nil])
print(GraineInApp.shared.currentVariables())             // the merged set, as the next conversation gets it
// One call's own
GraineInApp.shared.calls.startCall(reason: "order_help", variables: ["order_id": "A-1042"])

The prompt side

How a prompt might use them — in the agent's prompt, in the dashboard:

The user's name, if known: {name}. Their plan: {plan}.
If {who_called} is "customer", they called you: ask how you can help with {call_reason}.
If {who_called} is "scheduled", you are calling at a time they booked: say so, and talk about {call_reason}.
If {who_called} is "agent", the app's own team asked you to call: explain why, from {call_reason}.

Where the user's details come from: Identify the user · calls in both directions: the user calls, Graine rings.